OTA compare
Fan out across every source given an identifier.
Fail-soft per source: this returns 200 with per-source status even when one OTA is blocked, because losing three good answers to one bad one is worse than a partial result the caller can see. comparison.comparable is false for a single priced source, mixed currencies or mixed price bases; those minima and spreads are not calculated.
Request
https://api.scrapercompany.com/v1/ota/compareAuthenticate 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.
- check_instring (date)required
First night of the stay,
YYYY-MM-DD. - check_outstring (date) | null
Departure date. An alternative to
nights— if both are given, this wins. - nightsintegerdefault
1min 1, max 30Length of stay. Ignored when
check_outis supplied. - adultsintegerdefault
2min 1, max 8Adults in the room. Two is the hotel default; pass one for a hostel, which is priced per bed. Any value 1-8 works.
- currencystringdefault
USDISO 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
- booking_pagenamestring | null
Booking slug. Omit to skip Booking entirely.
- booking_countrystringdefault
usTwo-letter segment before the slug in the Booking 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
- hotels_property_idstring | null
Hotels.com numeric id from
POST /v1/ota/hotels/search. Omit to skip Hotels.com. - hotels_marketstringdefault
USHotels.com point-of-sale; also picks its currency.
One of
AUCADEEUFRGBIEITNLNZUS - agoda_property_idstring | null
Agoda numeric id from
POST /v1/ota/agoda/search. Omit to skip Agoda. - expedia_property_idstring | null
Expedia numeric id from
POST /v1/ota/expedia/search. Omit to skip Expedia. - expedia_marketstringdefault
USExpedia point-of-sale; also picks its currency.
One of
CAUS - agoda_probe_min_staybooleandefault
falseRe-ask a sold-out Agoda stay at 2..7 nights to tell a minimum-stay restriction from a sell-out (Agoda reports both as sold out). Up to six extra Agoda calls per sold-out row, so off by default here;
POST /v1/ota/agodaprobes by default. - 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'spoint_of_saleblock says whether that country was actually served; when it was not, the price is the default market's. Omit for the previous behaviour. In a comparison it applies to Booking and Agoda, and becomeshotels_market/expedia_marketwhen those are not given and the source sells that point-of-sale.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/compare" \
-H "x-api-key: $SCRAPERCOMPANY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"check_in": "2027-01-15",
"nights": 1,
"currency": "USD",
"booking_pagename": "moxy-boston-downtown",
"booking_country": "us",
"hotels_property_id": "38766175",
"hotels_market": "US",
"agoda_property_id": "8795952",
"expedia_property_id": "38766175",
"expedia_market": "US"
}'Response
200 — One night per source. Fail-soft: a blocked OTA is a row with a status. Each row carries `availability` (available, sold_out, min_stay, unavailable_dates, blocked, not_found, error) and `is_soldout`; here Expedia states a 7-night minimum stay and Hotels.com was blocked. Metered responses carry x-credits-charged and x-credits-remaining headers (see credit headers).
{
"search_parameters": {
"engine": "ota_compare",
"check_in_date": "2027-02-10",
"check_out_date": "2027-02-11",
"adults": 2,
"currency": "USD",
"booking_pagename": "moxy-boston-downtown",
"agoda_property_id": "8795952"
},
"comparison": {
"status": "comparable",
"comparable": true,
"identifiers": {
"booking": "moxy-boston-downtown",
"agoda": "8795952"
},
"lowest_price": 285,
"lowest_source": "booking",
"spread": 47,
"prices": {
"booking": 285,
"agoda": 332
},
"currencies": {
"booking": "USD",
"agoda": "USD"
},
"price_provenance": {},
"reason": "Sources price on different bases (booking_display_average, total_including_taxes_and_fees); the headline minimum mixes them. Compare within `by_price_basis`.",
"price_basis_consistent": false,
"by_price_basis": {
"booking_display_average": {
"sources": [
"booking"
],
"currencies": [
"USD"
],
"lowest_source": "booking",
"lowest_price_per_night": 285
},
"total_including_taxes_and_fees": {
"sources": [
"agoda"
],
"currencies": [
"USD"
],
"lowest_source": "agoda",
"lowest_price_per_night": 332
}
}
},
"sources": {
"booking": {
"status": "ok",
"price_per_night": 285,
"currency": "USD",
"availability": "available",
"is_soldout": false,
"price_basis": "booking_display_average"
},
"agoda": {
"status": "ok",
"price_per_night": 332,
"currency": "USD",
"availability": "available",
"is_soldout": false,
"price_basis": "total_including_taxes_and_fees"
},
"expedia": {
"status": "no_price",
"currency": "USD",
"availability": "min_stay",
"is_soldout": false,
"availability_reason": "This property requires you to stay at least 7 nights.",
"min_length_of_stay": 7
},
"hotels": {
"status": "error",
"error": "ExpediaBlocked: HTTP 429",
"availability": "blocked",
"is_soldout": false,
"availability_reason": "ExpediaBlocked: HTTP 429"
}
},
"availability": {
"booking": "available",
"agoda": "available",
"expedia": "min_stay",
"hotels": "blocked"
},
"meta": {
"requested": 4,
"ok": 2,
"elapsed_s": 15.89
}
}Response fields
Fields marked required are always present; others appear when they apply.
- search_parametersobjectrequired
Show 9 child fieldsHide child fields
- search_parameters.enginestringrequired
One of
ota_compare - search_parameters.check_in_datestring (date)required
- search_parameters.check_out_datestring (date)required
- search_parameters.adultsintegerrequired
- search_parameters.currencystringrequired
Requested currency; used by Booking.com and Agoda. Hotels.com and Expedia price in their market's currency.
- search_parameters.booking_pagenamestring
Present only when supplied.
- search_parameters.hotels_property_idstring
Present only when supplied.
- search_parameters.agoda_property_idstring
Present only when supplied.
- search_parameters.expedia_property_idstring
Present only when supplied.
- comparisonobjectrequired
Show 12 child fieldsHide child fields
- comparison.statusstringrequired
One of
no_pricessingle_sourcemixed_currencycomparable - comparison.comparablebooleanrequired
True when at least two sources priced in one currency.
- comparison.reasonstring | nullrequired
Why the prices are not (fully) comparable. Null only when
statusiscomparableand every price shares one basis; when bases differ it says the headline minimum mixes them. - comparison.identifiersobjectrequired
Echo of the identifiers used, keyed
booking/hotels/agoda/expedia(supplied ones only). - comparison.lowest_pricenumber | nullrequired
Null when nothing priced or currencies are mixed. May span different price bases; see
price_basis_consistent. - comparison.lowest_sourcestring | nullrequired
- comparison.spreadnumber | nullrequired
Highest minus lowest price per night; non-null only when
comparableis true. - comparison.pricesobjectrequired
Source -> price per night (priced sources only).
- comparison.currenciesobjectrequired
Source -> upper-case currency code (priced sources only).
- comparison.price_basis_consistentbooleanrequired
True when every priced source shares one price basis (also true when at most one priced).
- comparison.by_price_basisobjectrequired
Priced sources grouped by price basis (keys as in
sources.<name>.price_basis), so like is compared with like. Empty when nothing priced. - comparison.price_provenanceobjectrequired
Source -> provenance of the compared price (priced sources only).
- sourcesobjectrequired
One entry per requested source (
booking,hotels,agoda,expedia). Fail-soft: a failed source is an entry withstatus: error, not a failed request. - metaobjectrequired
Show 3 child fieldsHide child fields
- meta.requestedintegerrequired
- meta.okintegerrequired
Sources that returned a price.
- meta.elapsed_snumberrequired
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? |
|---|---|---|
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 {"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","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 {"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.
- Export your key:
export SCRAPERCOMPANY_API_KEY=sk_...(no key yet? start a free trial). - Copy the cURL example above and run it in a terminal.
Questions about this page?
Send the page link and your question, and the team will answer.