Skip to content
Docs

Booking.com calendar

Booking.com forward horizon — 61 dates per call.

POST/v1/ota/booking
12 creditsTry itBooking.com API overview →

price is the hotel's undiscounted base rate per night, before Booking promotions and excluding taxes and charges, not the payable rate. It equals the crossed-out price only on hotels running a Late Escape Deal (OYO Red Hill Chennai, 2026-10-17: calendar 3,323 INR = crossed-out 3,322.57 vs 1,196 INR payable + 93.81 taxes and charges); other deals strike through a lower figure. For payable prices and parity use POST /v1/ota/booking/rooms; use this for availability and trend.

12 credits when at least one night is priced; free when the calendar is empty or every day is unpriced. A partial calendar (some priced nights) is charged in full. Sold-out rooms on POST /v1/ota/booking/rooms stay charged.

Request

POSThttps://api.scrapercompany.com/v1/ota/booking

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.

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

  • roomsintegerdefault 1min 1, max 8

    Rooms requested.

  • country_marketstring | null

    Visitor country (point of sale), two letters, e.g. GB. Booking and Agoda price by the visitor's country - measured 2026-10-03, Booking showed a GB visitor 321 USD where US and CA visitors saw 276 for the same night - so this asks for the price a visitor from that country sees. The answer's point_of_sale block says whether that country was actually served; when it was not, the price is the default market's. Omit for the previous behaviour.

    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

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

200 response
{
  "search_parameters": {
    "engine": "booking_calendar",
    "pagename": "moxy-boston-downtown",
    "country": "us",
    "start_date": "2027-02-10",
    "days": 3,
    "currency": "USD",
    "adults": 2,
    "rooms": 1,
    "country_market": "GB"
  },
  "property": {
    "pagename": "moxy-boston-downtown",
    "hotel_id": 5375786
  },
  "point_of_sale": {
    "country_market": "GB"
  },
  "calendar": [
    {
      "stay_date": "2027-02-10",
      "available": true,
      "availability": "available",
      "is_soldout": false,
      "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",
        "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"
      }
    },
    {
      "stay_date": "2027-02-11",
      "available": false,
      "availability": "sold_out",
      "is_soldout": true,
      "currency": "USD",
      "min_length_of_stay": 1
    }
  ],
  "unavailable_dates": [
    "2027-02-11",
    "2027-02-12"
  ],
  "meta": {
    "source": "booking",
    "collection_id": "ratecol_0123456789abcdef0123456789abcdef",
    "observed_at": "2026-08-07T01:23:45.678Z",
    "calls": 1,
    "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 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 fields
    • property.pagenamestringrequired
    • property.hotel_idinteger | nullrequired

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

  • calendararray of objectrequired
    Show 6 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 13 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.

  • unavailable_datesarray of string (date)required
  • metaobjectrequired
    Show 7 child fields
    • meta.sourcestringrequired

      One ofbooking

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

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
422Unprocessable Content

Request validation failed. detail is a list of problems for schema errors, or a string for semantic checks performed by the endpoint.

{"detail":[{"loc":["body","name"],"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

12 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