# Room matrix: `POST /v1/rooms`

Cost: 5 credits (5 (failed requests are free)). Docs: https://scrapercompany.com/docs/reference/rooms

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 body (JSON):

- `token` (string; required; min length 8): Google property token. Get one from `POST /v1/search` — it is the `token` on each match. Looks like `ChUIoben2Mv6-CYaCi9tLzA3czVwbjQQAQ`.
- `check_in` (string (date); required): First night of the stay, `YYYY-MM-DD`.
- `check_out` (string (date) | null; optional): Alternative to `nights`; wins if both are given. The stay cannot exceed 30 nights, the same cap as `nights`.
- `nights` (integer; optional; default 1; min 1, max 30): Length of stay. Ignored when `check_out` is supplied.
- `rooms` (integer; optional; default 1; min 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.
- `market` (string | null; optional; one of 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): Market/country, e.g. `US`, `MX`, `AU`, `GB`. Sets `gl` and the default tax basis. Null when omitted.
- `currency` (string | null; optional; one of 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): ISO currency for the returned prices. It is part of the request, so it does not depend on where the request is served from.
- `adults` (integer; optional; default 2; min 1, max 8): Occupancy. Any value 1-8 works. Children are not supported by the calendar.
- `sources` (array of string | null; optional): Defaults to ['Official site', 'Booking.com', 'Hotels.com', 'Expedia']
- `room_attempts` (integer; optional; default 3; min 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.

Response fields:

- `search_parameters` (object; required)
  - `search_parameters.engine` (string; required; one of google_hotels_rooms)
  - `search_parameters.token` (string; required)
  - `search_parameters.check_in_date` (string (date); required)
  - `search_parameters.check_out_date` (string (date); required)
  - `search_parameters.adults` (integer; required)
  - `search_parameters.currency` (string; required)
  - `search_parameters.sources` (array of string; required)
- `property` (object; required)
  - `property.name` (string; required)
  - `property.currency` (string; required)
  - `property.currency_matches_request` (boolean; required)
  - `property.requested_market` (string; required)
  - `property.egress_market` (string | null; required)
  - `property.egress_geo_locked_ok` (boolean; required)
- `render` (object; required)
  - `render.carried_room_detail` (boolean; required)
- `sources` (array of object; required)
  - `sources[].source` (string; required)
  - `sources[].rooms` (integer; required): Distinct rooms this render carried for the source; 0 does NOT mean no inventory.
  - `sources[].cheapest` (number | null; required)
  - `sources[].dearest` (number | null; required)
  - `sources[].currency` (string; required)
  - `sources[].is_official` (boolean; required)
  - `sources[].duplicate_of` (string | null; required)
  - `sources[].provenance` (object | null; required): Where, when and how one normalized price was observed.
- `rows` (array of object; required)
  - `rows[].signature` (string; required): Normalized room signature, e.g. `1 king`.
  - `rows[].cells` (object; required): Keyed by source name.
- `totals` (object; required)
  - `totals.sources_present` (integer; required)
  - `totals.sources_with_rooms` (integer; required)
  - `totals.distinct_signatures` (integer; required)

Base URL: `https://api.scrapercompany.com`. Auth: send your key in the `x-api-key` header. A failed request (4xx or 5xx) or an empty result costs 0 credits.

- [Full API reference as one Markdown file](https://scrapercompany.com/llms-full.txt)
- [OpenAPI spec](https://scrapercompany.com/openapi.json)
