Skip to content
ScraperCompany
Google Hotels

Room matrix

Room types by OTA, aligned onto a comparable signature.

POST/v1/rooms
3 credits

Each OTA names the same room its own way — on one property the official site and Expedia shared zero names verbatim — so a pivot on the raw name shows every row filled by one source. Rows here are keyed on a normalised signature and every cell keeps the source's own wording.

Room detail rides on Google's featured-offer blocks, which the thin variant of the page omits entirely. A source with rooms: 0 means this render carried none for it, NOT that the OTA has no inventory.

Request

POSThttps://api.scrapercompany.com/v1/rooms

Authenticate with your API key in the x-api-key header (see Authentication).

Body

JSON object. Unknown fields are rejected with 422.

  • tokenstringrequiredmin length 8

    Google property token. Get one from POST /v1/search — it is the token on each match. Looks like ChUIoben2Mv6-CYaCi9tLzA3czVwbjQQAQ.

  • check_instring (date)required

    First night of the stay, YYYY-MM-DD.

  • nightsintegerdefault 1min 1, max 30

    Length of stay. Ignored when check_out is supplied.

  • marketstring | null

    Market/country, e.g. US, MX, AU, GB. Sets gl and the default tax basis. Omit to derive it from currency.

    18 allowed values

    AG, AT, AU, BE, BZ, CA, CH, DE, ES, FR, GB, IE, IT, MX, NL, NZ, PT, US

  • currencystring | null

    ISO currency for the returned prices.

    39 allowed values

    AED, ARS, AUD, BRL, CAD, CHF, CLP, CNY, COP, CZK, DKK, EGP, EUR, GBP, HKD, HUF, IDR, ILS, INR, JPY, KRW, MXN, MYR, NOK, NZD, PEN, PHP, PLN, QAR, RON, SAR, SEK, SGD, THB, TRY, TWD, USD, VND, ZAR

  • adultsintegerdefault 2min 1, max 8

    Occupancy: number of adults, 1-8. Children are not supported by the Google calendar.

  • sourcesarray of string | null

    Defaults to ['Official site', 'Booking.com', 'Hotels.com', 'Expedia']

Example request

curl -X POST "https://api.scrapercompany.com/v1/rooms" \
  -H "x-api-key: $SCRAPERCOMPANY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "ChUIoben2Mv6-CYaCi9tLzA3czVwbjQQAQ",
    "check_in": "2026-11-30",
    "nights": 1,
    "market": "US",
    "currency": "USD"
  }'

Response

200 — Room signature x source. An empty cell means the render carried no detail for that source, NOT that the room is unavailable. Metered responses carry x-credits-charged and x-credits-remaining headers (see credit headers).

200 response
{
  "search_parameters": {
    "engine": "google_hotels_rooms",
    "token": "ChUIoben2Mv6-CYaCi9tLzA3czVwbjQQAQ",
    "check_in_date": "2029-02-05",
    "check_out_date": "2029-02-06",
    "adults": 2,
    "currency": "USD",
    "sources": [
      "Official site",
      "Booking.com"
    ]
  },
  "property": {
    "name": "Hilton Chicago",
    "currency": "USD",
    "currency_matches_request": true,
    "requested_market": "US",
    "egress_market": "US",
    "egress_geo_locked_ok": true
  },
  "render": {
    "wire_bytes": 4416000,
    "carried_room_detail": true
  },
  "sources": [
    {
      "source": "Official site",
      "rooms": 23,
      "cheapest": 420.06,
      "dearest": 527.98,
      "currency": "USD",
      "is_official": true
    },
    {
      "source": "Hotels.com",
      "rooms": 28,
      "cheapest": 419.51,
      "dearest": 1974.23,
      "currency": "USD",
      "is_official": false,
      "duplicate_of": "Expedia"
    }
  ],
  "rows": [
    {
      "signature": "1 king",
      "cells": {
        "Official site": {
          "name": "1 KING BED",
          "price": 420.06,
          "total": 499.45
        },
        "Expedia": {
          "name": "Room, 1 King Bed",
          "price": 419.51,
          "total": 498.79
        }
      }
    }
  ],
  "totals": {
    "sources_present": 4,
    "sources_with_rooms": 3,
    "distinct_signatures": 32
  }
}
Arrays are shortened to their first items.

Response fields

Fields marked required are always present; others appear when they apply.

  • search_parametersobjectrequired
    Show 7 child fields
    • search_parameters.enginestringrequired

      One ofgoogle_hotels_rooms

    • search_parameters.tokenstringrequired
    • search_parameters.check_in_datestring (date)required
    • search_parameters.check_out_datestring (date)required
    • search_parameters.adultsintegerrequired
    • search_parameters.currencystringrequired
    • search_parameters.sourcesarray of stringrequired
  • propertyobjectrequired
    Show 6 child fields
    • property.namestringrequired
    • property.currencystringrequired
    • property.currency_matches_requestbooleanrequired
    • property.requested_marketstringrequired
    • property.egress_marketstring | nullrequired
    • property.egress_geo_locked_okbooleanrequired
  • renderobjectrequired
    Show 2 child fields
    • render.wire_bytesintegerrequired
    • render.carried_room_detailbooleanrequired
  • sourcesarray of objectrequired
    Show 8 child fields
    • sources[].sourcestringrequired
    • sources[].roomsintegerrequired

      Distinct rooms this render carried for the source; 0 does NOT mean no inventory.

    • sources[].cheapestnumber | nullrequired
    • sources[].dearestnumber | nullrequired
    • sources[].currencystringrequired
    • sources[].is_officialbooleanrequired
    • sources[].duplicate_ofstring | nullrequired
    • sources[].provenanceobject | nullrequired

      Where, when and how one normalized price was observed.

      Show 15 child fields
      • sources[].provenance.schema_versionintegerrequired

        Provenance schema version (currently 1).

      • sources[].provenance.observation_idstringrequired

        Deterministic id of this price observation (rateobs_...).

      • sources[].provenance.collection_idstringrequired

        Id shared by every price from one upstream fetch (ratecol_...).

      • sources[].provenance.observed_atstringrequired

        UTC observation time, ISO-8601.

      • sources[].provenance.sourcestringrequired

        Upstream source, e.g. google_hotels_calendar.

      • sources[].provenance.source_kindstringrequired

        Kind of source, e.g. calendar, offer, ota_calendar, official.

      • sources[].provenance.collectorstringrequired

        Identifier of the collector that produced the price.

      • sources[].provenance.source_property_idstringrequired

        Property identifier at the source.

      • sources[].provenance.requested_marketstring | nullrequired
      • sources[].provenance.requested_currencystring | nullrequired
      • sources[].provenance.returned_currencystring | nullrequired
      • sources[].provenance.egress_modestringrequired

        How the request reached the source, e.g. direct.

      • sources[].provenance.price_basisstringrequired

        What the price represents, e.g. room_base_before_taxes_and_fees.

      • sources[].provenance.derivationstringrequired

        How the figure was derived, e.g. normalized_upstream.

      • sources[].provenance.upstream_rate_idstring | nullrequired

        Source-native rate/room id when available.

  • rowsarray of objectrequired
    Show 2 child fields
    • rows[].signaturestringrequired

      Normalized room signature, e.g. 1 king.

    • rows[].cellsobjectrequired

      Keyed by source name.

  • totalsobjectrequired
    Show 3 child fields
    • totals.sources_presentintegerrequired
    • totals.sources_with_roomsintegerrequired
    • totals.distinct_signaturesintegerrequired

Errors

Errors return a JSON body with a detail field. Failed requests are not charged. See Errors for the full list and retry advice.

StatusMeaningRetry?
401Unauthorized

Missing or invalid API key.

{"detail":"missing or invalid API key"}		No, fix the request
402Payment Required

Not enough credits for this request. Only returned once credit enforcement is switched on; during the beta metering runs in shadow mode and never blocks.

{"detail":"insufficient credits: this request costs 5, 0 available. Credits renew 2026-11-01."}		No, fix the request
404Not Found

The property, stay, job or record was not found.

{"detail":"job not found"}		No, fix the request
422Unprocessable Content

Request validation failed.

{"detail":[{"loc":["body","token"],"msg":"Field required","type":"missing"}]}		No, fix the request
429Too Many Requests

Too many requests: the key's requests-per-minute limit was exceeded, or (once credit enforcement is on) the plan's concurrent-request limit. No rate-limit or Retry-After headers are sent; back off and retry.

{"detail":"rate limit 60/min exceeded"}		Yes, with backoff
502Bad Gateway

The upstream source failed, blocked the request or returned an unusable answer. Safe to retry later; failed requests are not charged.

{"detail":"RuntimeError"}		Yes, with backoff

Try it

  1. Export your key: export SCRAPERCOMPANY_API_KEY=sk_... (no key yet? request access).
  2. Copy the cURL example above and run it in a terminal.
  3. Or open the interactive playground on api.scrapercompany.com, paste your key and pick this endpoint.

Credits

3 credits per successful call. Failed, blocked and empty results are free. Credit metering is in beta and does not block requests yet.

Questions or feedback on this page? Email us