# Calendar: `POST /v1/calendar`

Cost: from 8 credits (8, plus 3 per night with `basis: mainstream` and 3 per `verify_sources` spot-check (failed requests are free)). Docs: https://scrapercompany.com/docs/reference/calendar

Forward horizon of nightly rates — the cheap bulk path.

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`.
- `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): Two-letter `gl` override. Normally set by `market`.
- `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.
- `days` (integer; optional; default 90; min 1, max 330): Nights to price, starting at `start`. Max 330.
- `start` (string (date) | null; optional): First stay date. Defaults to tomorrow.
- `adults` (integer; optional; default 2; min 1, max 8): Occupancy. Any value 1-8 works. Children are not supported by the calendar.
- `los` (integer; optional; default 1; min 1, max 30): Length of stay per quote. Nightly price genuinely moves with LOS.
- `rates_include_tax` (boolean | null; optional): Overrides the market default; pass the property's own setting
- `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.
- `probe_min_stay` (boolean; optional; default true): Re-ask for any night that will not price as a single night. Google returns a two-night-minimum night identically to a sold-out one — empty, with no reason and no min-stay field — so without this, weekends silently vanish. On a beach market in August that was every Friday and Saturday on half the comp set. Filled rows carry `min_length_of_stay` and a per-night rate derived from the longer stay. Costs one extra call per probe level, not per date.
- `basis` (string; optional; default cheapest; one of cheapest, mainstream; pattern ^(cheapest|mainstream)$): What the nightly figure should mean. **`cheapest` (default)** is the fast calendar path: one small request for the whole horizon. It returns Google's lowest bookable rate, including aggregators. The base/fees/taxes/total split and SERP-compatible `rate_before_taxes_with_fees` remain populated. **`mainstream`** also returns `rate_mainstream_total` / `rate_mainstream_base` / `mainstream_source` / `aggregator_discount` — the cheapest rate on Booking, Expedia, Hotels.com, Priceline, Tripadvisor or Agoda, which is what a comp-set audit means by 'the OTA rate'. `rate_total` is left untouched, so both bases are available. This is intentionally expensive: it samples multi-megabyte offers pages and, when an aggregator sets the floor, re-prices each date. Measured on a 14-day request it took about 8s versus 0.4s for `cheapest`; use it selectively. `basis_applied` reports which path ran.
- `verify_sources` (integer; optional; default 0; min 0, max 5): Spot-check this many nights against the per-OTA offers page and return a `source_check` block. The calendar gives one price per night and never says which source it came from — usually a mainstream OTA, but where a discounter undercuts them it reports the discounter. Measured on four properties: three matched the cheapest mainstream OTA to the cent, the fourth's figure was Super.com's at 15% under. Costs one offers lookup per sampled night, so it is a sample, not every date.
- `compact` (boolean; optional; default false): Return only essential fields per night (stay_date, rate, rate_total, rate_including_vat, currency, rates_include_tax) for smaller responses over MCP. Omits base/tax/fees breakdown, mainstream rates, and min_length_of_stay details.

Response fields:

- `token` (string; required)
- `collection_id` (string; required): Shared by every row of this collection (`ratecol_...`).
- `observed_at` (string; required): UTC observation time, ISO-8601.
- `market` (string; required)
- `requested_days` (integer; required): Nights requested (capped at 330).
- `coverage` (number; required): Share of requested nights that returned a priced row, 0-1 rounded to 4 decimals (e.g. `0.9333` = 84 of 90). A number, not an `N/M` string.
- `elapsed_s` (number; required): End-to-end seconds for this request.
- `calendar_elapsed_s` (number; required): Seconds spent on the upstream calendar fetch.
- `tax_profile` (object | null; required): The property's effective tax profile, derived from the returned nights.
  - `tax_profile.rate` (number; required): Median tax / base ratio observed across nights.
  - `tax_profile.confidence` (string; required; one of high, low, none)
  - `tax_profile.itemised` (integer; required): Nights where the tax split was itemised.
  - `tax_profile.derived` (integer; required): Nights where only a total was given and the split was derived.
- `unpriced_dates` (array of string (date); required): Requested nights with no bookable offer.
- `validation` (object; required): Plausibility checks on the returned rows.
  - `validation.ok` (boolean; required): False when any error-level finding exists.
  - `validation.errors` (array of string; required)
  - `validation.warnings` (array of string; required)
- `booking_window` (object; optional): How far out the property actually sells. Present on successful collections.
  - `booking_window.requested_days` (integer; required)
  - `booking_window.priced_days` (integer; required)
  - `booking_window.last_priced_day` (integer | null; required): 1-based day of the last priced night.
  - `booking_window.contiguous_days` (integer; optional): Priced nights from the start with no gap (absent when nothing priced).
  - `booking_window.dry_after_day` (integer; required)
  - `booking_window.note` (string; required)
- `basis_applied` (string; optional; one of mainstream:annotated, mainstream:calendar-already-matched): Present only with `basis: mainstream`.
- `source_check` (object; optional): Present only when `verify_sources` > 0 or `basis: mainstream` sampled nights against the offers page.
  - `source_check.sampled` (integer; required)
  - `source_check.mainstream_sources` (array of string; required)
  - `source_check.calendar_matches_mainstream` (boolean; required)
  - `source_check.note` (string; required)
  - `source_check.checks` (array of object; required)
  - `source_check.reprice` (object; optional): Present when mainstream re-pricing ran.
- `rates` (array of object; required): One row per priced night.
  - `rates[].token` (string; required): Google property token.
  - `rates[].stay_date` (string (date); required): Stay (check-in) date.
  - `rates[].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.
  - `rates[].rate_base` (number | null; required): Room-only price before tax and mandatory fees.
  - `rates[].rate_before_taxes_with_fees` (number | null; required): `rate_base` + `fees` (The standard SERP API `extracted_price_before_taxes` basis).
  - `rates[].rate_total` (number | null; required): All-in price including tax and fees.
  - `rates[].tax` (number | null; required)
  - `rates[].fees` (number | null; required)
  - `rates[].currency` (string; required)
  - `rates[].market` (string; required)
  - `rates[].rates_include_tax` (boolean; required): Which basis `rate` uses.
  - `rates[].adults` (integer; required)
  - `rates[].los` (integer; required): Length of stay the price was quoted for.
  - `rates[].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.
  - `rates[].rate_mainstream_base` (number | null; required): Cheapest mainstream-OTA base price (only populated with `basis: mainstream`).
  - `rates[].rate_mainstream_total` (number | null; required): Cheapest mainstream-OTA all-in price (only populated with `basis: mainstream`).
  - `rates[].mainstream_source` (string | null; required): OTA that produced the mainstream figure.
  - `rates[].aggregator_discount` (number | null; required): `rate_mainstream_total - rate_total` when both exist.
  - `rates[].implied_tax_rate` (number | null; required): `tax / rate_base`.
  - `rates[].provenance` (object; required): Provenance of one calendar row.

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)
