Booking.com calendar

Request#

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

Body#

JSON object. Unknown fields are rejected with 422.

• pagenamestringrequiredmin length 2

  URL slug returned by POST /v1/ota/booking/search. For booking.com/hotel/us/moxy-boston-downtown.html the slug is moxy-boston-downtown and country is us.

• countrystringdefault usmin length 2, max length 2

  The two-letter segment in the URL before the slug — part of the property's address on Booking, not your own location.

  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

• startstring (date) | null

  Defaults to today.

• daysintegerdefault 61min 1, max 365

  Booking truncates any single response to 61 days, so larger windows are paged automatically — a year is 6 calls, not 1.

• 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

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

• roomsintegerdefault 1min 1, max 8

  Rooms requested.

Example request#

curl -X POST "https://api.scrapercompany.com/v1/ota/booking" \
  -H "x-api-key: $SCRAPERCOMPANY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pagename": "moxy-boston-downtown",
    "country": "us",
    "days": 61,
    "currency": "USD"
  }'

Response#

200 — Booking's own calendar. Paged past its 61-day cap automatically. Metered responses carry x-credits-charged and x-credits-remaining headers (see credit headers).

{
  "search_parameters": {
    "engine": "booking_calendar",
    "pagename": "moxy-boston-downtown",
    "country": "us",
    "start_date": "2029-02-05",
    "days": 3,
    "currency": "USD",
    "adults": 2,
    "rooms": 1
  },
  "property": {
    "pagename": "moxy-boston-downtown",
    "hotel_id": 5375786
  },
  "calendar": [
    {
      "stay_date": "2029-02-05",
      "available": true,
      "price": 453,
      "currency": "USD",
      "min_length_of_stay": 1,
      "provenance": {
        "schema_version": 1,
        "observation_id": "rateobs_0123456789abcdef0123456789abcdef",
        "collection_id": "ratecol_0123456789abcdef0123456789abcdef",
        "observed_at": "2026-08-07T01:23:45.678Z",
        "source": "booking_com",
        "source_kind": "ota_calendar",
        "collector": "scrapingme.ota.booking",
        "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"
      }
    },
    {
      "stay_date": "2029-02-06",
      "available": false,
      "price": null,
      "currency": "USD",
      "min_length_of_stay": 1
    }
  ],
  "unavailable_dates": [
    "2029-02-06",
    "2029-02-07"
  ],
  "meta": {
    "source": "booking",
    "collection_id": "ratecol_0123456789abcdef0123456789abcdef",
    "observed_at": "2026-08-07T01:23:45.678Z",
    "calls": 1,
    "wire_bytes": 454,
    "elapsed_s": 2.147,
    "dates": 3,
    "priced": 1
  }
}

Response fields#

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

• search_parametersobjectrequired
  Show 8 child fieldsHide child fields

  • search_parameters.enginestringrequired

    One ofbooking_calendar

  • search_parameters.pagenamestringrequired
  • search_parameters.countrystringrequired
  • search_parameters.start_datestring (date)required
  • search_parameters.daysintegerrequired
  • search_parameters.currencystringrequired
  • search_parameters.adultsintegerrequired
  • search_parameters.roomsintegerrequired
• propertyobjectrequired
  Show 2 child fieldsHide child fields

  • property.pagenamestringrequired
  • property.hotel_idinteger | nullrequired

    Booking.com's numeric hotel id as returned upstream.

• calendararray of objectrequired
  Show 6 child fieldsHide child fields

  • calendar[].stay_datestring (date)required
  • calendar[].availablebooleanrequired
  • calendar[].pricenumber | nullrequired

    Null for unsellable dates.

  • calendar[].currencystringrequired
  • calendar[].min_length_of_stayinteger | nullrequired
  • calendar[].provenanceobjectrequired

    Where, when and how one normalized price was observed.

    Show 15 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.

• unavailable_datesarray of string (date)required
• metaobjectrequired
  Show 8 child fieldsHide child fields

  • meta.sourcestringrequired

    One ofbooking

  • meta.collection_idstringrequired
  • meta.observed_atstringrequired
  • meta.callsintegerrequired
  • meta.wire_bytesintegerrequired
  • meta.elapsed_snumberrequired
  • meta.datesintegerrequired
  • meta.pricedintegerrequired

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.