# Official site rates: `POST /v1/official`

Cost: from 4 credits (4, or 19 for the few hotel sites that need more work to read; `x-credits-charged` shows what a call cost. Failed requests are free.). Docs: https://scrapercompany.com/docs/reference/official

Rates from the hotel's own booking engine.

The hotel website is resolved to its booking page, then the booking
engine is detected automatically: over 50 are supported, with more added
regularly. The caller never chooses a vendor.
``property_id`` is the rental or property key when ``property_ref`` ends
in one: the part after the last slash. Other engines leave it null.
``property_ref`` itself is unchanged.
Every rate carries `access_type` and the loyalty fields
(`loyalty_program`, `points`, `cash_component`,
`member_discount_vs_public`); the response's `loyalty` object summarises
public vs member vs points for the property. Chain rates also carry the
brand's own `rate_code`, a normalised `rate_category` (`bar`, `rack`,
`advance_purchase`, `member`, `points`, `package`, `promo`,
`qualified`, `unknown`) with its `rate_category_source`, and
`refundable` / `meal_plan` where the brand states them; every other
engine is labelled from its rate names.

Request body (JSON):

- `url` (string; required; min length 8): The hotel's public homepage or property page. The API finds its booking link and detects the booking engine automatically; a direct booking URL is also accepted.
- `check_in` (string (date); required): First night of the stay, `YYYY-MM-DD`.
- `check_out` (string (date) | null; optional): Departure date. An alternative to `nights` — if both are given, this wins.
- `nights` (integer; optional; default 1; min 1, max 30): Length of stay. Ignored when `check_out` is supplied.
- `adults` (integer; optional; default 2; min 1, max 8): Adults in the room. Two is the hotel default; pass one for a hostel, which is priced per bed. Any value 1-8 works.
- `rooms` (integer; optional; default 1; min 1, max 8): Rooms requested.
- `currency` (string; optional; default USD; 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 4217 code for the returned prices. Major currencies include AED, AUD, BRL, CAD, CHF, CNY, EUR, GBP, HKD, INR, JPY, KRW, MXN, NZD, SGD, USD; all 39 supported codes are listed in the enum.
- `qualified_rates` (array of string; optional; max items 3): Also shop these eligibility-restricted rates where the hotel's engine offers them (Hilton, Marriott, Radisson): `aaa`, `senior`, `government`. They come back with `access_type: "qualified"` and `rate_category: "qualified"`, never count as the public price, and add 1 credit per type the engine searched. `qualified_rates` in the response says which were searched.

Response fields:

- `search_parameters` (object; required)
  - `search_parameters.engine` (string; required): `official_` + engine id.
  - `search_parameters.source_url` (string; required)
  - `search_parameters.booking_url` (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)
- `engine` (string; required): Detected engine id.
- `source_url` (string; required)
- `booking_url` (string; required)
- `detected_by` (string; required): How the engine was detected, e.g. `url`, `redirect`, `booking_link`, `html_fingerprint`.
- `discovery_pages` (integer; required)
- `wrapper_resolutions` (integer; required)
- `discovery_cache_hit` (boolean; required)
- `discovery_elapsed_s` (number; required)
- `collection_id` (string; required)
- `observed_at` (string; required)
- `property_ref` (string; required): Engine-native property id (may be empty).
- `check_in` (string (date); required)
- `check_out` (string (date); required)
- `nights` (integer; required)
- `currency` (string; required)
- `sold_out` (boolean; required)
- `cheapest_rate` (number | null; required): Cheapest public rate across available rooms.
- `cheapest_member_rate` (number | null; required)
- `member_rates_returned` (integer; required)
- `rooms_returned` (integer; required)
- `elapsed_s` (number; required)
- `rooms` (array of object; required)
  - `rooms[].name` (string; required)
  - `rooms[].code` (string; required)
  - `rooms[].max_occupancy` (integer | null; required)
  - `rooms[].quantity` (integer | null; required)
  - `rooms[].available` (boolean; required)
  - `rooms[].cheapest_rate` (number | null; required): Cheapest PUBLIC rate in `rates`.
  - `rooms[].rates` (array of object; 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)
