Google Hotels calendar (SearchAPI) — POST /v1/serp/google_hotels_calendar

SearchAPI bills one request per stay date; this returns ~330 nights in a single ~105 KB response. extracted_price_before_taxes uses SearchAPI's base-plus-mandatory-fees basis; extracted_price_base and fees preserve the itemised values.

Request

POSThttps://api.scrapercompany.com/v1/serp/google_hotels_calendar

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

Body

JSON object. Unknown fields are rejected with 422.

property_tokenstringrequiredmin length 8
Google property token, as returned by /v1/search.
daysintegerdefault 90min 1, max 330
Nights to price in one call. Max 330.
startstring (date) | null
First stay date. Defaults to tomorrow.
adultsintegerdefault 2min 1, max 8
Adults in the room. Two is the hotel default; pass one for a hostel, which is priced per bed. Any value from 1 to 8 is accepted.
currencystringdefault USD
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.
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
glstringdefault us
Two-letter country for the request.
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
losintegerdefault 1min 1, max 30
Length of stay each night is priced at. The per-night figure genuinely moves with LOS.

Example request

curl -X POST "https://api.scrapercompany.com/v1/serp/google_hotels_calendar" \
  -H "x-api-key: $SCRAPERCOMPANY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "property_token": "ChUIoben2Mv6-CYaCi9tLzA3czVwbjQQAQ",
    "days": 90,
    "currency": "USD",
    "gl": "us"
  }'

Response

200 — A whole horizon in one call, in SearchAPI's shape. Metered responses carry x-credits-charged and x-credits-remaining headers (see credit headers).

200 response

{
  "search_parameters": {
    "engine": "google_hotels_calendar",
    "property_token": "ChUIoben2Mv6-CYaCi9tLzA3czVwbjQQAQ",
    "days": 5,
    "adults": 2,
    "currency": "USD",
    "gl": "us",
    "los": 1
  },
  "calendar": [
    {
      "date": "2028-12-26",
      "price": {
        "price": "$327",
        "extracted_price": 327.11
      },
      "extracted_price_before_taxes": 352.11,
      "extracted_price_base": 327.11,
      "extracted_price_total": 418.65,
      "tax": 66.54,
      "fees": 25,
      "currency": "USD",
      "rates_include_tax": false,
      "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"
      }
    },
    {
      "date": "2028-12-27",
      "price": {
        "price": "$324",
        "extracted_price": 324.37
      },
      "extracted_price_before_taxes": 349.37,
      "extracted_price_base": 324.37,
      "extracted_price_total": 415.4,
      "tax": 66.03,
      "fees": 25,
      "currency": "USD",
      "rates_include_tax": false
    }
  ],
  "unavailable_dates": [],
  "tax_profile": {
    "rate": 0.2051,
    "confidence": "high"
  },
  "meta": {
    "coverage": 1,
    "wire_bytes": 1839,
    "elapsed_s": 0.171,
    "retries": 0
  }
}

Response fields

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

search_parametersobjectrequired
Show 7 child fieldsHide child fields
- search_parameters.enginestringrequired
  One ofgoogle_hotels_calendar
- search_parameters.property_tokenstringrequired
- search_parameters.daysintegerrequired
- search_parameters.adultsintegerrequired
- search_parameters.currencystringrequired
- search_parameters.glstringrequired
- search_parameters.losintegerrequired
calendararray of objectrequired
One row per priced night.
Show 10 child fieldsHide child fields
- calendar[].datestring (date)required
- calendar[].priceobjectrequired
  The market-correct nightly figure (same as rate on /v1/calendar).
  Show 2 child fieldsHide child fields
  - calendar[].price.pricestringrequired
  - calendar[].price.extracted_pricenumberrequired
- calendar[].extracted_price_before_taxesnumber | nullrequired
  Base + mandatory fees (SearchAPI basis).
- calendar[].extracted_price_basenumber | nullrequired
- calendar[].extracted_price_totalnumber | nullrequired
- calendar[].taxnumber | nullrequired
- calendar[].feesnumber | nullrequired
- calendar[].currencystringrequired
- calendar[].rates_include_taxbooleanrequired
- calendar[].provenanceobjectrequired
  Provenance of one calendar row.
  Show 17 child fieldsHide child fields
  - calendar[].provenance.schema_versionintegerrequired
    Provenance schema version (currently 1).
  - calendar[].provenance.observation_idstringrequired
    Deterministic id of this price observation (rateobs_...).
  - calendar[].provenance.collection_idstringrequired
    Id shared by every price from one upstream fetch (ratecol_...).
  - calendar[].provenance.observed_atstringrequired
    UTC observation time, ISO-8601.
  - calendar[].provenance.sourcestringrequired
    Upstream source, e.g. google_hotels_calendar.
  - calendar[].provenance.source_kindstringrequired
    Kind of source, e.g. calendar, offer, ota_calendar, official.
  - calendar[].provenance.collectorstringrequired
    Identifier of the collector that produced the price.
  - calendar[].provenance.source_property_idstringrequired
    Property identifier at the source.
  - calendar[].provenance.requested_marketstring | nullrequired
  - calendar[].provenance.requested_currencystring | nullrequired
  - calendar[].provenance.returned_currencystring | nullrequired
  - calendar[].provenance.egress_modestringrequired
    How the request reached the source, e.g. direct.
  - calendar[].provenance.price_basisstringrequired
    What the price represents, e.g. room_base_before_taxes_and_fees.
  - calendar[].provenance.derivationstringrequired
    How the figure was derived, e.g. normalized_upstream.
  - calendar[].provenance.upstream_rate_idstring | nullrequired
    Source-native rate/room id when available.
  - calendar[].provenance.derived_fieldsarray of stringrequired
    Fields computed by ScraperCompany rather than read from the source.
  - calendar[].provenance.mainstreamobject
    Present only when mainstream figures were added (basis: mainstream).
unavailable_datesarray of string (date)required
tax_profileobject | nullrequired
Show 2 child fieldsHide child fields
- tax_profile.ratenumberrequired
- tax_profile.confidencestringrequired
  One ofhighlownone
metaobjectrequired
Show 6 child fieldsHide child fields
- meta.coveragenumberrequired
  Share of requested nights priced, 0-1.
- meta.collection_idstringrequired
- meta.observed_atstringrequired
- meta.wire_bytesintegerrequired
- meta.elapsed_snumberrequired
- meta.retriesintegerrequired

Errors

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

Status	Meaning	Retry?
`401`Unauthorized	Missing or invalid API key. `{"detail":"missing or invalid API key"}`	No, fix the request
`402`Payment Required	Not enough credits for this request. Only returned once credit enforcement is switched on; during the beta metering runs in shadow mode and never blocks. `{"detail":"insufficient credits: this request costs 5, 0 available. Credits renew 2026-11-01."}`	No, fix the request
`404`Not Found	The property, stay, job or record was not found. `{"detail":"job not found"}`	No, fix the request
`422`Unprocessable Content	Request validation failed. `{"detail":[{"loc":["body","token"],"msg":"Field required","type":"missing"}]}`	No, fix the request
`429`Too Many Requests	Too many requests: the key's requests-per-minute limit was exceeded, or (once credit enforcement is on) the plan's concurrent-request limit. No rate-limit or Retry-After headers are sent; back off and retry. `{"detail":"rate limit 60/min exceeded"}`	Yes, with backoff
`502`Bad Gateway	The upstream source failed, blocked the request or returned an unusable answer. Safe to retry later; failed requests are not charged. `{"detail":"RuntimeError"}`	Yes, with backoff

Try it

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

Credits

5 credits per successful call. Failed, blocked and empty results are free. Credit metering is in beta and does not block requests yet.

Request#

Body#

Example request#

Response#

Response fields#

Errors#

Try it#