Skip to content
Docs

Room matrix

Room types by OTA, aligned onto a comparable signature.

POST/v1/rooms
5 creditsTry it

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 page carried none for it, NOT that the OTA has no inventory.

Google serves a room-less variant of the page about half the time (measured 2026-10-03, 18 of 36 pages), which is why this used to come back empty so often. It now fetches again up to room_attempts times (default 3) and keeps the first page with room detail; render.renders is what that cost. A matrix still without rooms is status: "no_room_detail" and is not billed.

Prices are per room. rooms is echoed on search_parameters and does not multiply the totals. nights is the priced stay, including when the caller sent check_out instead of nights.

Each cell's price is the pre-tax stay. It equals total when Google does not split tax out of a tax-inclusive display. total is the full stay including taxes. Both are rounded to the cent. search_parameters.market is the market the caller sent, or null when it was omitted — the same value as property.requested_market. Currency still chooses the fetch market when market is omitted; that choice is not reported as a request.

Request

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

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

Run this request on your own API key from this page, with the values you type. Signed out? Sign in or get an API key.

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.

  • check_outstring (date) | null

    Alternative to nights; wins if both are given. The stay cannot exceed 30 nights, the same cap as nights.

  • nightsintegerdefault 1min 1, max 30

    Length of stay. Ignored when check_out is supplied.

  • roomsintegerdefault 1min 1, max 10

    Number of rooms requested. Prices in the matrix are per room (search_parameters.price_scope is per_room); the count is echoed and does not multiply the totals.

  • marketstring | null

    Market/country, e.g. US, MX, AU, GB. Sets gl and the default tax basis. Null when omitted.

    52 allowed values

    AE, AG, AR, AT, AU, BE, BR, BZ, CA, CH, CL, CN, CO, CZ, DE, DK, EG, ES, FI, FR, GB, GR, HK, HR, HU, ID, IE, IL, IN, IT, JP, KR, MX, MY, NL, NO, NZ, PE, PH, PL, PT, QA, RO, SA, SE, SG, TH, TR, TW, US, VN, ZA

  • currencystring | null

    ISO currency for the returned prices. It is part of the request, so it does not depend on where the request is served from.

    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. Any value 1-8 works. Children are not supported by the calendar.

  • sourcesarray of string | null

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

  • room_attemptsintegerdefault 3min 0, max 5

    Extra page fetches to try when a page carries no room detail. Google serves a room-less variant of the same page about half the time (measured 2026-10-03), so one page alone returns an empty matrix that often. 0 restores single-fetch behaviour.

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": "2027-01-15",
    "nights": 1,
    "market": "US",
    "currency": "USD"
  }'

Response

200 — Room signature x source. Prices are per room (`search_parameters.price_scope`). `price` is the pre-tax stay and `total` is the full stay including taxes; they are equal when the source does not split tax, and both are rounded to the cent. `nights` is the priced stay. `search_parameters.market` matches `property.requested_market` (null when the caller omitted `market`). An empty cell means the page carried no detail for that source, NOT that the room is unavailable. `status` is `ok`, `no_rooms_for_sources`, or `no_room_detail` (no page carried rooms after `room_attempts` extra fetches; not billed). 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": "2027-05-07",
    "check_out_date": "2027-05-08",
    "nights": 1,
    "rooms": 1,
    "price_scope": "per_room",
    "adults": 2,
    "currency": "USD",
    "market": "US",
    "sources": [
      "Official site",
      "Booking.com"
    ]
  },
  "property": {
    "name": "Hilton Chicago",
    "currency": "USD",
    "currency_matches_request": true,
    "requested_market": "US"
  },
  "status": "ok",
  "render": {
    "renders": 1,
    "carried_room_detail": true
  },
  "sources": [
    {
      "source": "Official site",
      "rooms": 24,
      "cheapest": 230.84,
      "dearest": 316.75,
      "currency": "USD",
      "is_official": true
    },
    {
      "source": "Booking.com",
      "rooms": 3,
      "cheapest": 230.85,
      "dearest": 251.06,
      "currency": "USD",
      "is_official": false
    }
  ],
  "rows": [
    {
      "signature": "2 double",
      "cells": {
        "Official site": {
          "name": "2 DOUBLE BEDS",
          "price": 230.84,
          "total": 231
        },
        "Booking.com": {
          "name": "Double Room with Two Double Beds",
          "price": 230.85,
          "total": 231
        },
        "Hotels.com": {
          "name": "Room, 2 Double Beds",
          "price": 229.75,
          "total": 230
        },
        "Expedia": {
          "name": "Room, 2 Double Beds",
          "price": 228.19,
          "total": 228.19
        }
      }
    },
    {
      "signature": "1 king",
      "cells": {
        "Official site": {
          "name": "1 KING BED",
          "price": 230.84,
          "total": 231
        },
        "Hotels.com": {
          "name": "Room, 1 King Bed",
          "price": 229.75,
          "total": 230
        },
        "Expedia": {
          "name": "Room, 1 King Bed",
          "price": 228.19,
          "total": 228.19
        }
      }
    }
  ],
  "totals": {
    "sources_present": 4,
    "sources_with_rooms": 4,
    "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 1 child field
    • 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 13 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.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.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: the account's credits mode is enforce (mode in GET /v1/billing) and the request costs more than the available credits. Nothing is run or charged.

{"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 (in enforce credits mode) 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

Press Try it above to run this request on your own key, with the values you type (sign in first). For a no-code walkthrough, use the workspace’s guided Try it.

  1. Export your key: export SCRAPERCOMPANY_API_KEY=sk_... (no key yet? start a free trial).
  2. Copy the cURL example above and run it in a terminal.

Credits

5 credits per successful call. Failed, blocked and empty results are free.

Questions about this page?

Send the page link and your question, and the team will answer.

Email support