Skip to content
Docs

Booking.com rooms

Booking.com room types and rate plans for one stay window.

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

Fills the gap left by /v1/rooms: Google's entity page frequently carries no room detail for the Booking.com row, so this goes to Booking directly.

Prices come from the property page's room grid, enriched with room size and occupancy when Booking.com provides them.

Each rate plan carries tax_included / taxes_and_fees from the page JSON (amount wins even when the excludes list is empty), and partner_offer for TPI rows. Partner room_id is set only when the row reliably ties to a parent room; otherwise it is null.

Request

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

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, e.g. moxy-boston-downtown from booking.com/hotel/us/moxy-boston-downtown.html.

  • countrystringdefault us

    Two-letter segment before the slug in that URL.

    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

  • check_instring (date)required

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

  • nightsintegerdefault 1min 1, max 30

    Length of stay. Ignored when check_out is supplied.

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

  • 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

  • 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/rooms" \
  -H "x-api-key: $SCRAPERCOMPANY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pagename": "moxy-boston-downtown",
    "country": "us",
    "check_in": "2027-01-15",
    "nights": 1,
    "currency": "USD"
  }'

Response

200 — Room types with both rate plans — the cheap non-refundable one and the dearer free-cancellation one. Metered responses carry x-credits-charged and x-credits-remaining headers (see credit headers).

200 response
{
  "pagename": "moxy-boston-downtown",
  "hotel_id": "5375786",
  "property_name": "Moxy Boston Downtown",
  "check_in": "2027-02-10",
  "check_out": "2027-02-11",
  "nights": 1,
  "currency": "USD",
  "requested_currency": "USD",
  "returned_currency": "USD",
  "hotel_currency": "USD",
  "sold_out": false,
  "availability": "available",
  "is_soldout": false,
  "rendered": true,
  "catalogue_from_graphql": false,
  "adults": 2,
  "children": 0,
  "cheapest_rate": 250,
  "cheapest_rate_basis": "requested_occupancy",
  "cheapest_rate_any_occupancy": 250,
  "cheapest_public_rate": 250,
  "price_includes_tax": false,
  "rooms": [
    {
      "name": "Center Stage, Guest room, 1 Queen, City view",
      "room_id": "537578602",
      "beds": "1 queen bed",
      "room_size": 22,
      "max_persons": 2,
      "cheapest_rate": 250,
      "cheapest_rate_any_occupancy": 250,
      "rate_plans": [
        {
          "block_id": "537578602_191393531_0_42_0",
          "price": 250,
          "currency": "USD",
          "guests": 2,
          "fits_occupancy": true,
          "free_cancellation": false,
          "no_prepayment": false,
          "breakfast_included": false,
          "tax_included": false,
          "taxes_and_fees": 81.91,
          "rate_code": "191393531",
          "rate_category": "unknown",
          "rate_code_scope": "property",
          "price_source": "page_json",
          "hotel_currency": "USD",
          "hotel_price": 250,
          "member_rate": false,
          "public_price": 250,
          "partner_offer": false
        },
        {
          "block_id": "537578602_246436396_0_42_0",
          "price": 269,
          "currency": "USD",
          "guests": 2,
          "fits_occupancy": true,
          "free_cancellation": true,
          "no_prepayment": true,
          "breakfast_included": false,
          "tax_included": false,
          "taxes_and_fees": 85.01,
          "price_source": "page_json",
          "hotel_currency": "USD",
          "hotel_price": 269,
          "member_rate": false,
          "public_price": 269,
          "partner_offer": false
        }
      ]
    }
  ]
}

Response fields

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

  • pagenamestringrequired
  • hotel_idstringrequired

    Empty string when the room catalogue was unavailable.

  • property_namestringrequired
  • check_instring (date)required
  • check_outstring (date)required
  • nightsintegerrequired
  • currencystringrequired

    The requested currency.

  • requested_currencystringrequired

    ISO 4217 code you asked for.

  • returned_currencystring | nullrequired

    ISO 4217 code the page priced in; null when it did not say.

  • hotel_currencystring | nullrequired

    The property's own currency (ISO 4217); null when not stated.

  • sold_outboolean | nullrequired
  • availabilitystringrequired

    available (a plan is priced), sold_out (Booking.com marks the property sold out) or error (see availability_reason).

    One ofavailablesold_outerror

  • is_soldoutboolean | nullrequired
  • availability_reasonstring | nullrequired

    Why the property is not available, in words (for example the page's room data was cut off, or rooms are listed but none is priced for these dates).

  • min_length_of_stayinteger | nullrequired
  • renderedbooleanrequired

    False when the page came back without a populated room grid.

  • catalogue_from_graphqlbooleanrequired

    Whether room size / occupancy enrichment was available.

  • adultsinteger | nullrequired

    Party size per room that cheapest_rate must seat.

  • childrenintegerrequired
  • cheapest_ratenumber | nullrequired

    Lowest price among plans that seat the party, in returned_currency.

  • cheapest_rate_basisstringrequired

    How cheapest_rate was chosen.

    One ofrequested_occupancyoccupancy_unknownno_plan_fitsnone

  • cheapest_rate_any_occupancynumber | nullrequired
  • cheapest_public_ratenumber | nullrequired

    Lowest price for the party that needs no sign-in: member plans count at their public_price.

  • price_includes_taxboolean | nullrequired

    True/False when every plan that says agrees; null otherwise. Check tax_included per plan.

  • collection_idstringrequired
  • observed_atstringrequired
  • roomsarray of objectrequired
    Show 8 child fields
    • rooms[].namestringrequired
    • rooms[].room_idstringrequired
    • rooms[].bedsstringrequired
    • rooms[].room_sizenumber | nullrequired
    • rooms[].max_personsinteger | nullrequired
    • rooms[].cheapest_ratenumber | nullrequired

      Lowest price in this room that seats the party.

    • rooms[].cheapest_rate_any_occupancynumber | nullrequired
    • rooms[].rate_plansarray of objectrequired
      Show 28 child fields
      • rooms[].rate_plans[].block_idstringrequired
      • rooms[].rate_plans[].pricenumber | nullrequired

        Stay total for this plan in currency. Taxes are included only when tax_included is true. Null when no price in currency could be read (see price_unavailable_reason); never a number in another currency.

      • rooms[].rate_plans[].currencystringrequired

        ISO 4217 code, per plan. The currency Booking.com actually priced in (normally the requested one).

      • rooms[].rate_plans[].guestsinteger | nullrequired

        Guests the plan is priced for (its occupancy).

      • rooms[].rate_plans[].max_childreninteger | nullrequired
      • rooms[].rate_plans[].fits_occupancyboolean | nullrequired

        Whether the plan seats the requested party; null when its occupancy is unknown.

      • rooms[].rate_plans[].free_cancellationbooleanrequired
      • rooms[].rate_plans[].no_prepaymentbooleanrequired
      • rooms[].rate_plans[].breakfast_includedbooleanrequired
      • rooms[].rate_plans[].non_refundablebooleanrequired
      • rooms[].rate_plans[].tax_includedboolean | nullrequired

        True: price includes taxes and fees. False: they come on top (taxes_and_fees). Null: the page did not say.

      • rooms[].rate_plans[].taxes_and_feesnumber | nullrequired

        Taxes and fees not included in price, in currency, when stated. Add to price for the payable total.

      • rooms[].rate_plans[].original_pricenumber | nullrequired

        Crossed-out pre-discount price, when shown.

      • rooms[].rate_plans[].price_sourcestring | nullrequired

        Where price was read: page_json (the page's price data), grid (room table, hotel currency equals requested), partner_display (Partner Offer row), grid_unverified, or null when unpriced.

        One ofpage_jsongridpartner_displaygrid_unverified

      • rooms[].rate_plans[].hotel_currencystring | nullrequired

        The property's own currency (ISO 4217), when the page names it.

      • rooms[].rate_plans[].hotel_pricenumber | nullrequired

        The same plan in hotel_currency, when known.

      • rooms[].rate_plans[].member_ratebooleanrequired

        True when price is a Genius member preview (sign-in needed).

      • rooms[].rate_plans[].public_pricenumber | nullrequired

        Price without sign-in: price for public plans, the pre-member-discount price for member plans; null when unknown.

      • rooms[].rate_plans[].partner_offerbooleanrequired

        A Booking.com Partner Offer row (sold by a partner company).

      • rooms[].rate_plans[].price_unavailable_reasonstring | nullrequired

        Why price is null, e.g. a grid price in the hotel currency or a Partner Offer row without a display price.

      • rooms[].rate_plans[].currency_notestring

        Present when Booking.com priced in a currency other than the requested one.

      • rooms[].rate_plans[].rate_codestring | null
      • rooms[].rate_plans[].rate_categorystring
      • rooms[].rate_plans[].rate_category_sourcestring | null
      • rooms[].rate_plans[].refundableboolean | null
      • rooms[].rate_plans[].meal_planstring | null
      • rooms[].rate_plans[].rate_code_scopestring | null
      • rooms[].rate_plans[].provenanceobjectrequired

        Where, when and how one normalized price was observed.

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":[{"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

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