Skip to content
Docs

Official site rates

Rates from the hotel's own booking engine.

POST/v1/official
4+ creditsTry itHotel Direct Rates API overview →4, or 19 for the few hotel sites that need more work to read; x-credits-charged shows what a call cost. Failed requests are free.

The hotel website is resolved to its booking page, then the booking engine is detected automatically: over 50 are supported, with more added regularly. The caller never chooses a vendor. `property_id is the rental or property key when property_ref ends in one: the part after the last slash. Other engines leave it null. property_ref itself is unchanged. Every rate carries access_type and the loyalty fields (loyalty_program, points, cash_component, member_discount_vs_public); the response's loyalty object summarises public vs member vs points for the property. Chain rates also carry the brand's own rate_code, a normalised rate_category (bar, rack, advance_purchase, member, points, package, promo, qualified, unknown) with its rate_category_source, and refundable / meal_plan` where the brand states them; every other engine is labelled from its rate names.

Request

POSThttps://api.scrapercompany.com/v1/official

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.

  • urlstringrequiredmin length 8

    The hotel's public homepage or property page. The API finds its booking link and detects the booking engine automatically; a direct booking URL is also accepted.

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

  • 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

  • qualified_ratesarray of stringmax items 3

    Also shop these eligibility-restricted rates where the hotel's engine offers them (Hilton, Marriott, Radisson): aaa, senior, government. They come back with access_type: "qualified" and rate_category: "qualified", never count as the public price, and add 1 credit per type the engine searched. qualified_rates in the response says which were searched.

Example request

curl -X POST "https://api.scrapercompany.com/v1/official" \
  -H "x-api-key: $SCRAPERCOMPANY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.ihg.com/intercontinental/hotels/us/en/new-york/nychc/hoteldetail",
    "check_in": "2027-01-15",
    "nights": 1,
    "currency": "USD"
  }'

Response

200 — Public, member and reward-night rates from the detected booking engine . Metered responses carry x-credits-charged and x-credits-remaining headers (see credit headers).

200 response
{
  "search_parameters": {
    "engine": "official_brand_ihg",
    "source_url": "https://www.ihg.com/intercontinental/hotels/us/en/new-york/nychc/hoteldetail",
    "booking_url": "https://www.ihg.com/intercontinental/hotels/us/en/new-york/nychc/hoteldetail",
    "check_in_date": "2027-04-08",
    "check_out_date": "2027-04-09",
    "adults": 2,
    "currency": "USD"
  },
  "engine": "brand_ihg",
  "source_url": "https://www.ihg.com/intercontinental/hotels/us/en/new-york/nychc/hoteldetail",
  "booking_url": "https://www.ihg.com/intercontinental/hotels/us/en/new-york/nychc/hoteldetail",
  "collection_id": "ratecol_0123456789abcdef0123456789abcdef",
  "observed_at": "2026-08-07T01:23:45.678Z",
  "property_ref": "NYCHC",
  "check_in": "2027-04-08",
  "check_out": "2027-04-09",
  "nights": 1,
  "currency": "USD",
  "sold_out": false,
  "cheapest_rate": 631,
  "cheapest_member_rate": 612.07,
  "member_rates_returned": 2,
  "rooms_returned": 1,
  "elapsed_s": 1,
  "rooms": [
    {
      "name": "Premium Room",
      "code": "CDXG",
      "max_occupancy": 2,
      "quantity": 9,
      "available": true,
      "cheapest_rate": 631,
      "rates": [
        {
          "currency": "USD",
          "rate_plan": "Reward Nights",
          "rate_code": "IVANI",
          "rate_category": "points",
          "rate_category_source": "brand_flag",
          "refundable": true,
          "access_type": "points",
          "loyalty_points": 123000,
          "loyalty_program": "IHG One Rewards",
          "points": 123000,
          "points_basis": "stay",
          "is_discounted": false
        },
        {
          "price": 79,
          "currency": "USD",
          "rate_plan": "Reward Nights (points + cash)",
          "rate_code": "IVANI",
          "rate_category": "points",
          "rate_category_source": "brand_flag",
          "refundable": true,
          "access_type": "points_and_cash",
          "loyalty_points": 113000,
          "loyalty_cash": 79,
          "loyalty_program": "IHG One Rewards",
          "points": 113000,
          "points_basis": "stay",
          "cash_component": 79,
          "is_discounted": false
        }
      ]
    }
  ],
  "loyalty": {
    "program": "IHG One Rewards",
    "exposed_unauthenticated": {
      "program": "IHG One Rewards",
      "member": true,
      "points": true,
      "points_and_cash": true,
      "login_required_for": []
    },
    "rates_by_access_type": {
      "public": 2,
      "member": 2,
      "points": 1,
      "points_and_cash": 2,
      "corporate": 0,
      "qualified": 0
    },
    "public_best": {
      "room": "Premium Room",
      "room_code": "CDXG",
      "rate_plan": "Early Saver Rate",
      "price": 631,
      "currency": "USD"
    },
    "member_best": {
      "room": "Premium Room",
      "room_code": "CDXG",
      "rate_plan": "Early Saver Member Exclusive",
      "price": 612.07,
      "currency": "USD",
      "discount_vs_public": {
        "amount": 18.93,
        "percent": 3,
        "public_price": 631,
        "public_rate_plan": "Early Saver Rate",
        "currency": "USD",
        "basis": "room_cheapest_public"
      }
    },
    "points_best": {
      "room": "Premium Room",
      "room_code": "CDXG",
      "rate_plan": "Reward Nights",
      "access_type": "points",
      "points": 123000,
      "points_basis": "stay"
    },
    "points_plus_cash_best": {
      "room": "Premium Room",
      "room_code": "CDXG",
      "rate_plan": "Reward Nights (points + cash)",
      "access_type": "points_and_cash",
      "points": 103000,
      "points_basis": "stay",
      "cash_component": 149,
      "currency": "USD"
    },
    "points_value_cents_per_point": {
      "value": 0.513,
      "unit": "cents_per_point",
      "derivation": "derived",
      "formula": "(public_cash - cash_component) / points * 100",
      "currency": "USD",
      "room": "Premium Room",
      "public_cash": 631,
      "public_rate_plan": "Early Saver Rate",
      "cash_component": 0,
      "points": 123000,
      "points_rate_plan": "Reward Nights",
      "points_access_type": "points",
      "public_price_basis": "stay"
    }
  }
}
Arrays are shortened to their first items.

Response fields

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

  • search_parametersobjectrequired
    Show 7 child fields
    • search_parameters.enginestringrequired

      official_ + engine id.

    • search_parameters.source_urlstringrequired
    • search_parameters.booking_urlstringrequired
    • search_parameters.check_in_datestring (date)required
    • search_parameters.check_out_datestring (date)required
    • search_parameters.adultsintegerrequired
    • search_parameters.currencystringrequired
  • enginestringrequired

    Detected engine id.

  • source_urlstringrequired
  • booking_urlstringrequired
  • detected_bystringrequired

    How the engine was detected, e.g. url, redirect, booking_link, html_fingerprint.

  • discovery_pagesintegerrequired
  • wrapper_resolutionsintegerrequired
  • discovery_cache_hitbooleanrequired
  • discovery_elapsed_snumberrequired
  • collection_idstringrequired
  • observed_atstringrequired
  • property_refstringrequired

    Engine-native property id (may be empty).

  • check_instring (date)required
  • check_outstring (date)required
  • nightsintegerrequired
  • currencystringrequired
  • sold_outbooleanrequired
  • cheapest_ratenumber | nullrequired

    Cheapest public rate across available rooms.

  • cheapest_member_ratenumber | nullrequired
  • member_rates_returnedintegerrequired
  • rooms_returnedintegerrequired
  • elapsed_snumberrequired
  • roomsarray of objectrequired
    Show 7 child fields
    • rooms[].namestringrequired
    • rooms[].codestringrequired
    • rooms[].max_occupancyinteger | nullrequired
    • rooms[].quantityinteger | nullrequired
    • rooms[].availablebooleanrequired
    • rooms[].cheapest_ratenumber | nullrequired

      Cheapest PUBLIC rate in rates.

    • rooms[].ratesarray of objectrequired
      Show 14 child fields
      • rooms[].rates[].pricenumber | nullrequired

        Headline price for the stay on the engine's own basis.

      • rooms[].rates[].price_totalnumber | nullrequired
      • rooms[].rates[].reference_pricenumber | nullrequired
      • rooms[].rates[].taxnumber | nullrequired
      • rooms[].rates[].feesnumber | nullrequired
      • rooms[].rates[].original_pricenumber | nullrequired
      • rooms[].rates[].currencystringrequired
      • rooms[].rates[].rate_planstringrequired
      • rooms[].rates[].tax_inclusiveboolean | nullrequired

        Null means the engine did not state a basis, not that tax is excluded.

      • rooms[].rates[].access_typestringrequired

        public, member, points_and_cash or points.

      • rooms[].rates[].loyalty_pointsinteger | nullrequired
      • rooms[].rates[].loyalty_cashnumber | nullrequired
      • rooms[].rates[].is_discountedbooleanrequired
      • rooms[].rates[].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 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

From 4 credits per successful call (4, or 19 for the few hotel sites that need more work to read; x-credits-charged shows what a call cost. Failed requests are free.). 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