Skip to content
Docs

OTA compare

Fan out across every source given an identifier.

POST/v1/ota/compare
30 creditsTry itHotel Direct Rates API overview →

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

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

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.

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

  • 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

  • booking_pagenamestring | null

    Booking slug. Omit to skip Booking entirely.

  • booking_countrystringdefault us

    Two-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 US

    Hotels.com point-of-sale; also picks its currency.

    One ofAUCADEEUFRGBIEITNLNZUS

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

    Expedia point-of-sale; also picks its currency.

    One ofCAUS

  • agoda_probe_min_staybooleandefault false

    Re-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/agoda probes 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'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. In a comparison it applies to Booking and Agoda, and becomes hotels_market/expedia_market when 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).

200 response
{
  "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 fields
    • search_parameters.enginestringrequired

      One ofota_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 fields
    • comparison.statusstringrequired

      One ofno_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 status is comparable and 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 comparable is 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 with status: error, not a failed request.

  • metaobjectrequired
    Show 3 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.

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

30 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