# Offers: `POST /v1/offers`

Cost: 10 credits (14 with require_rooms). Docs: https://scrapercompany.com/docs/reference/offers

Per-OTA breakdown for one night.

Costs 10 credits, or 14 when `require_rooms` is set (up to three extra
page fetches). A failed call is free. Much heavier than /v1/calendar,
so use it for the dates that matter, not all of them.

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.
- `nights` (integer; optional; default 1; min 1, max 30): Ignored when `check_out` is given.
- `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.
- `rates_include_tax` (boolean | null; optional): Which basis the summary price uses. Defaults to the market convention.
- `property_name` (string; optional; default ): Improves official-site detection
- `include_metasearch` (boolean; optional; default false): Include metasearch aggregators (Trivago, Vio, Kayak, Goseek) alongside real OTAs. Off by default: they resell other sources, so they inflate the offer count without adding inventory.
- `free_cancellation_only` (boolean; optional; default false): Only offers with a stated free-cancellation deadline
- `device` (string; optional; default iphone; one of android, desktop, iphone): Render profile. Google returns a different offer list per device and desktop is the thinnest — iphone found 17 offers where desktop found 12 on the same property.
- `coverage` (integer; optional; default 1; min 1, max 3): Fetch this many device profiles and merge. Each one is an extra page fetch; 2 is the sensible maximum.
- `require_sources` (array of string | null; optional): Sources to insist on; retries a thin answer. Defaults to official + Booking + Hotels.com + Expedia + Agoda. Pass [] to disable.
- `require_rooms` (boolean; optional; default false): Fetch again (up to 3 extra pages) until an offer carries per-room detail. Google omits room detail from about half of its pages at random; `carried_room_detail` says which you got. A truthy value costs 14 credits instead of 10. A failed call is free either way.

Response fields:

- `token` (string; required)
- `check_in` (string (date); required)
- `check_out` (string (date); required)
- `nights` (integer; required)
- `adults` (integer; required)
- `device` (string; required)
- `coverage` (integer; required): Device profiles fetched (echo of the request).
- `currency` (string | null; required): Currency the page actually priced in.
- `currency_matches_request` (boolean; required)
- `requested_market` (string; required)
- `egress_market` (string | null; required): Market the seller list is verified for, or null when unverified.
- `egress_geo_locked_ok` (boolean; required)
- `price_insights_market_verified` (boolean; required)
- `rates_include_tax` (boolean; required): Basis used for `lowest_price_per_night`.
- `lowest_price_per_night` (number | null; required)
- `rooms_total` (integer; required)
- `name` (string; required)
- `hotel_class` (string; required)
- `hotel_class_stars` (integer | null; required)
- `rating` (number | null; required)
- `reviews` (integer | null; required)
- `deal` (string | null; required)
- `deal_description` (string | null; required)
- `has_deal` (boolean; required)
- `price_insights` (object; required)
  - `price_insights.lowest_price` (string | null; required): As Google displays it, e.g. `$304`.
  - `price_insights.price_level` (string | null; required)
  - `price_insights.price_level_code` (integer | null; required)
  - `price_insights.typical_price_range` (object | null; required)
- `sources` (array of string; required): Distinct sellers in `offers`.
- `missing_sources` (array of string; required): Required sources not offered after retry.
- `refundable_offers` (integer; required)
- `elapsed_s` (number; required)
- `warnings` (array of string; required)
- `offers` (array of object; required)
  - `offers[].source` (string; required): Normalized seller name, e.g. `Booking.com`, `Official site`.
  - `offers[].raw_source` (string; required): Seller name exactly as Google rendered it.
  - `offers[].is_official` (boolean; required)
  - `offers[].currency` (string | null; required)
  - `offers[].nights` (integer; required)
  - `offers[].room_id` (string | null; required): Seller-native room / rate-plan id.
  - `offers[].price_per_night` (number | null; required): All-in price per night.
  - `offers[].price_per_night_before_taxes` (number | null; required)
  - `offers[].total` (number | null; required): All-in price for the stay window.
  - `offers[].tax` (number | null; required)
  - `offers[].fees` (number | null; required)
  - `offers[].has_free_cancellation` (boolean; required)
  - `offers[].free_cancellation_until` (string | null; required)
  - `offers[].free_cancellation_time` (string | null; required)
  - `offers[].discount_remarks` (array of string; required): Member/loyalty remarks shown beside the offer.
  - `offers[].has_member_rate` (boolean; required)
  - `offers[].rooms` (array of object; required)
  - `offers[].headline_price_total` (number | null; required)
  - `offers[].headline_price_before_taxes` (number | null; required)
  - `offers[].price_derived_from_room` (boolean; required)
  - `offers[].provenance` (object; required): Where, when and how one normalized price was observed.

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)
