Room matrix
Room types by OTA, aligned onto a comparable signature.
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
https://api.scrapercompany.com/v1/roomsAuthenticate 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 thetokenon each match. Looks likeChUIoben2Mv6-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 asnights. - nightsintegerdefault
1min 1, max 30Length of stay. Ignored when
check_outis supplied. - roomsintegerdefault
1min 1, max 10Number of rooms requested. Prices in the matrix are per room (
search_parameters.price_scopeisper_room); the count is echoed and does not multiply the totals. - marketstring | null
Market/country, e.g.
US,MX,AU,GB. Setsgland 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 8Occupancy. 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 5Extra 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).
{
"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
}
}Response fields
Fields marked required are always present; others appear when they apply.
- search_parametersobjectrequired
Show 7 child fieldsHide child fields
- search_parameters.enginestringrequired
One of
google_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 fieldsHide 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 fieldHide child fields
- render.carried_room_detailbooleanrequired
- sourcesarray of objectrequired
Show 8 child fieldsHide 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 fieldsHide 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 fieldsHide child fields
- rows[].signaturestringrequired
Normalized room signature, e.g.
1 king. - rows[].cellsobjectrequired
Keyed by source name.
- totalsobjectrequired
Show 3 child fieldsHide 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.
| Status | Meaning | Retry? |
|---|---|---|
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 {"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 {"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.
- Export your key:
export SCRAPERCOMPANY_API_KEY=sk_...(no key yet? start a free trial). - Copy the cURL example above and run it in a terminal.
Questions about this page?
Send the page link and your question, and the team will answer.