Skip to content
Docs

Google Hotels calendar (SERP-compatible)

No SERP API equivalent — a whole forward horizon in one call.

POST/v1/serp/google_hotels_calendar
8 creditsTry itGoogle Hotels API overview →

Other SERP APIs bill one request per stay date; this returns ~330 nights in a single ~105 KB response. extracted_price_before_taxes uses the standard SERP API 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).

Run this request on your own API key from this page, with the values you type. Signed out? Sign in or get an API key.

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 1-8 works.

  • 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 the standard SERP API 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": "2026-12-31",
      "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",
        "source_property_id": "ChUIoben2Mv6-CYaCi9tLzA3czVwbjQQAQ",
        "requested_market": "US",
        "requested_currency": "USD",
        "returned_currency": "USD",
        "price_basis": "room_base_before_taxes_and_fees",
        "derivation": "normalized_upstream"
      }
    },
    {
      "date": "2027-01-01",
      "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,
    "elapsed_s": 0.171,
    "retries": 0
  }
}

Response fields

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

  • search_parametersobjectrequired
    Show 7 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 fields
    • calendar[].datestring (date)required
    • calendar[].priceobjectrequired

      The market-correct nightly figure (same as rate on /v1/calendar).

      Show 2 child fields
      • calendar[].price.pricestringrequired
      • calendar[].price.extracted_pricenumberrequired
    • calendar[].extracted_price_before_taxesnumber | nullrequired

      Base + mandatory fees (SERP API 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 15 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.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.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 fields
    • tax_profile.ratenumberrequired
    • tax_profile.confidencestringrequired

      One ofhighlownone

  • metaobjectrequired
    Show 5 child fields
    • meta.coveragenumberrequired

      Share of requested nights priced, 0-1.

    • meta.collection_idstringrequired
    • meta.observed_atstringrequired
    • 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.

StatusMeaningRetry?
401Unauthorized

Missing or invalid API key.

{"detail":"missing or invalid API key"}
No, fix the request
402Payment Required

Not enough credits for this request: the account's credits mode is enforce (mode in GET /v1/billing) and the request costs more than the available credits. Nothing is run or charged.

{"detail":"insufficient credits: this request costs 5, 0 available. Credits renew 2026-11-01."}
No, fix the request
404Not Found

The property, stay, job or record was not found.

{"detail":"job not found"}
No, fix the request
422Unprocessable Content

Request validation failed.

{"detail":[{"loc":["body","token"],"msg":"Field required","type":"missing"}]}
No, fix the request
429Too Many Requests

Too many requests: the key's requests-per-minute limit was exceeded, or (in enforce credits mode) 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
502Bad 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

Press Try it above to run this request on your own key, with the values you type (sign in first). For a no-code walkthrough, use the workspace’s guided Try it.

  1. Export your key: export SCRAPERCOMPANY_API_KEY=sk_... (no key yet? start a free trial).
  2. Copy the cURL example above and run it in a terminal.

Credits

8 credits per successful call. Failed, blocked and empty results are free.

Questions about this page?

Send the page link and your question, and the team will answer.

Email support