Stay

Request#

Authenticate with your API key in the x-api-key header (see Authentication).

Body#

JSON object. Unknown fields are rejected with 422.

• tokenstringrequiredmin length 8

  Google property token. Get one from POST /v1/search — it is the token on each match. Looks like ChUIoben2Mv6-CYaCi9tLzA3czVwbjQQAQ.

• check_instring (date)required

  First night of the stay, YYYY-MM-DD.

• check_outstring (date)required

  Must be after check_in. The gap is the LOS, and the per-night price does change with it.

• marketstring | null

  Market/country, e.g. US, MX, AU, GB. Sets gl and the default tax basis. Omit to derive it from currency.

  18 allowed values

  AG, AT, AU, BE, BZ, CA, CH, DE, ES, FR, GB, IE, IT, MX, NL, NZ, PT, US

• countrystring | null

  gl override.

  251 allowed values

  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

• currencystring | null

  ISO currency for the returned prices.

  39 allowed values

  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

• adultsintegerdefault 2min 1, max 8

  Occupancy: number of adults, 1-8. Children are not supported by the Google calendar.

• rates_include_taxboolean | null

  Which basis the summary price uses. Omit to take the market convention; pass the property's own setting to override.

• is_hostelbooleandefault 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.

Example request#

curl -X POST "https://api.scrapercompany.com/v1/stay" \
  -H "x-api-key: $SCRAPERCOMPANY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "ChUIoben2Mv6-CYaCi9tLzA3czVwbjQQAQ",
    "check_in": "2026-11-30",
    "check_out": "2026-12-03",
    "market": "US",
    "currency": "USD"
  }'

Response#

200 — One priced stay window, tax split out. Metered responses carry x-credits-charged and x-credits-remaining headers (see credit headers).

{
  "nights": 3,
  "token": "ChUIoben2Mv6-CYaCi9tLzA3czVwbjQQAQ",
  "rate": 2492.73,
  "rate_base": 2492.73,
  "rate_before_taxes_with_fees": 2567.73,
  "rate_total": 3053.03,
  "tax": 485.3,
  "fees": 75,
  "currency": "USD",
  "market": "US",
  "rates_include_tax": false,
  "adults": 2,
  "los": 3,
  "stay_date": "2029-02-05",
  "implied_tax_rate": 0.1947,
  "provenance": {
    "schema_version": 1,
    "observation_id": "rateobs_0123456789abcdef0123456789abcdef",
    "collection_id": "ratecol_0123456789abcdef0123456789abcdef",
    "observed_at": "2026-08-07T01:23:45.678Z",
    "source": "google_hotels_calendar",
    "source_kind": "calendar",
    "collector": "scrapingme.google_calendar",
    "source_property_id": "ChUIoben2Mv6-CYaCi9tLzA3czVwbjQQAQ",
    "requested_market": "US",
    "requested_currency": "USD",
    "returned_currency": "USD",
    "egress_mode": "direct",
    "price_basis": "room_base_before_taxes_and_fees",
    "derivation": "normalized_upstream"
  }
}

Response fields#

Fields marked required are always present; others appear when they apply.

• nightsintegerrequired

  Nights between check_in and check_out.

• tokenstringrequired

  Google property token.

• stay_datestring (date)required

  Stay (check-in) date.

• ratenumberrequired

  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_basenumber | nullrequired

  Room-only price before tax and mandatory fees.

• rate_before_taxes_with_feesnumber | nullrequired

  rate_base + fees (SearchAPI's extracted_price_before_taxes basis).

• rate_totalnumber | nullrequired

  All-in price including tax and fees.

• taxnumber | nullrequired
• feesnumber | nullrequired
• currencystringrequired
• marketstringrequired
• rates_include_taxbooleanrequired

  Which basis rate uses.

• adultsintegerrequired
• losintegerrequired

  Length of stay the price was quoted for.

• min_length_of_stayinteger | nullrequired

  Set when the night only prices at a longer stay; rate is then a per-night figure derived from that stay.

• rate_mainstream_basenumber | nullrequired

  Cheapest mainstream-OTA base price (only populated with basis: mainstream).

• rate_mainstream_totalnumber | nullrequired

  Cheapest mainstream-OTA all-in price (only populated with basis: mainstream).

• mainstream_sourcestring | nullrequired

  OTA that produced the mainstream figure.

• aggregator_discountnumber | nullrequired

  rate_mainstream_total - rate_total when both exist.

• implied_tax_ratenumber | nullrequired

  tax / rate_base.

• provenanceobjectrequired

  Provenance of one calendar row.

  Show 17 child fieldsHide child fields

  • provenance.schema_versionintegerrequired

    Provenance schema version (currently 1).

  • provenance.observation_idstringrequired

    Deterministic id of this price observation (rateobs_...).

  • provenance.collection_idstringrequired

    Id shared by every price from one upstream fetch (ratecol_...).

  • provenance.observed_atstringrequired

    UTC observation time, ISO-8601.

  • provenance.sourcestringrequired

    Upstream source, e.g. google_hotels_calendar.

  • provenance.source_kindstringrequired

    Kind of source, e.g. calendar, offer, ota_calendar, official.

  • provenance.collectorstringrequired

    Identifier of the collector that produced the price.

  • provenance.source_property_idstringrequired

    Property identifier at the source.

  • provenance.requested_marketstring | nullrequired
  • provenance.requested_currencystring | nullrequired
  • provenance.returned_currencystring | nullrequired
  • provenance.egress_modestringrequired

    How the request reached the source, e.g. direct.

  • provenance.price_basisstringrequired

    What the price represents, e.g. room_base_before_taxes_and_fees.

  • provenance.derivationstringrequired

    How the figure was derived, e.g. normalized_upstream.

  • provenance.upstream_rate_idstring | nullrequired

    Source-native rate/room id when available.

  • provenance.derived_fieldsarray of stringrequired

    Fields computed by ScraperCompany rather than read from the source.

  • provenance.mainstreamobject

    Present only when mainstream figures were added (basis: mainstream).

    Show 3 child fieldsHide child fields

    • provenance.mainstream.sourcestringrequired
    • provenance.mainstream.supplierstring | nullrequired
    • provenance.mainstream.methodstringrequired

Errors#

Errors return a JSON body with a detail field. Failed requests are not charged. See Errors for the full list and retry advice.

Try it#

1. Export your key: export SCRAPERCOMPANY_API_KEY=sk_... (no key yet? request access).
2. Copy the cURL example above and run it in a terminal.
3. Or open the interactive playground on api.scrapercompany.com, paste your key and pick this endpoint.