# Stay: `POST /v1/stay`

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

One explicit stay window. `rate` is the WHOLE-STAY figure — length of
stay moves the nightly price, so dividing it out would misrepresent it.

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); required): Must be after `check_in`. The gap is the LOS, and the per-night price does change with it.
- `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. Omit to derive it from `currency`.
- `country` (string | null; optional; one of ad, ae, af, ag, ai, al, am, ao, aq, ar, as, at, au, aw, ax, az, ba, bb, bd, be, bf, bg, bh, bi, bj, bl, bm, bn, bo, bq, br, bs, bt, bv, bw, by, bz, ca, cc, cd, cf, cg, ch, ci, ck, cl, cm, cn, co, cr, cu, cv, cw, cx, cy, cz, de, dj, dk, dm, do, dz, ec, ee, eg, eh, er, es, et, fi, fj, fk, fm, fo, fr, ga, gb, gd, ge, gf, gg, gh, gi, gl, gm, gn, gp, gq, gr, gs, gt, gu, gw, gy, hk, hm, hn, hr, ht, hu, id, ie, il, im, in, io, iq, ir, is, it, je, jm, jo, jp, ke, kg, kh, ki, km, kn, kp, kr, kw, ky, kz, la, lb, lc, li, lk, lr, ls, lt, lu, lv, ly, ma, mc, md, me, mf, mg, mh, mk, ml, mm, mn, mo, mp, mq, mr, ms, mt, mu, mv, mw, mx, my, mz, na, nc, ne, nf, ng, ni, nl, no, np, nr, nu, nz, om, pa, pe, pf, pg, ph, pk, pl, pm, pn, pr, ps, pt, pw, py, qa, re, ro, rs, ru, rw, sa, sb, sc, sd, se, sg, sh, si, sj, sk, sl, sm, sn, so, sr, ss, st, sv, sx, sy, sz, tc, td, tf, tg, th, tj, tk, tl, tm, tn, to, tr, tt, tv, tw, tz, ua, ug, uk, um, us, uy, uz, va, vc, ve, vg, vi, vn, vu, wf, ws, xk, ye, yt, za, zm, zw): `gl` override.
- `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. Omit to take the market convention; pass the property's own setting to override.
- `is_hostel` (boolean; optional; default false): Hostels are priced per bed rather than per room, so occupancy changes the rate differently. Set this and the per-person maths is applied.

Response fields:

- `nights` (integer; required): Nights between check_in and check_out.
- `token` (string; required): Google property token.
- `stay_date` (string (date); required): Stay (check-in) date.
- `rate` (number; required): The market-correct figure to store: all-in (`rate_total`) when `rates_include_tax` is true, otherwise the pre-tax base. For `POST /v1/stay` it is the whole-stay figure.
- `rate_base` (number | null; required): Room-only price before tax and mandatory fees.
- `rate_before_taxes_with_fees` (number | null; required): `rate_base` + `fees` (The standard SERP API `extracted_price_before_taxes` basis).
- `rate_total` (number | null; required): All-in price including tax and fees.
- `tax` (number | null; required)
- `fees` (number | null; required)
- `currency` (string; required)
- `market` (string; required)
- `rates_include_tax` (boolean; required): Which basis `rate` uses.
- `adults` (integer; required)
- `los` (integer; required): Length of stay the price was quoted for.
- `min_length_of_stay` (integer | null; required): Set when the night only prices at a longer stay; `rate` is then a per-night figure derived from that stay.
- `rate_mainstream_base` (number | null; required): Cheapest mainstream-OTA base price (only populated with `basis: mainstream`).
- `rate_mainstream_total` (number | null; required): Cheapest mainstream-OTA all-in price (only populated with `basis: mainstream`).
- `mainstream_source` (string | null; required): OTA that produced the mainstream figure.
- `aggregator_discount` (number | null; required): `rate_mainstream_total - rate_total` when both exist.
- `implied_tax_rate` (number | null; required): `tax / rate_base`.
- `provenance` (object; required): Provenance of one calendar row.
  - `provenance.schema_version` (integer; required): Provenance schema version (currently 1).
  - `provenance.observation_id` (string; required): Deterministic id of this price observation (`rateobs_...`).
  - `provenance.collection_id` (string; required): Id shared by every price from one upstream fetch (`ratecol_...`).
  - `provenance.observed_at` (string; required): UTC observation time, ISO-8601.
  - `provenance.source` (string; required): Upstream source, e.g. `google_hotels_calendar`.
  - `provenance.source_kind` (string; required): Kind of source, e.g. `calendar`, `offer`, `ota_calendar`, `official`.
  - `provenance.source_property_id` (string; required): Property identifier at the source.
  - `provenance.requested_market` (string | null; required)
  - `provenance.requested_currency` (string | null; required)
  - `provenance.returned_currency` (string | null; required)
  - `provenance.price_basis` (string; required): What the price represents, e.g. `room_base_before_taxes_and_fees`.
  - `provenance.derivation` (string; required): How the figure was derived, e.g. `normalized_upstream`.
  - `provenance.upstream_rate_id` (string | null; required): Source-native rate/room id when available.
  - `provenance.derived_fields` (array of string; required): Fields computed by ScraperCompany rather than read from the source.
  - `provenance.mainstream` (object; optional): Present only when mainstream figures were added (`basis: mainstream`).

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)
