Skip to content
Docs

Offers

Per-OTA breakdown for one night.

POST/v1/offers
10+ creditsTry it10 (14 with require_rooms; failed requests are free)

Costs 10 credits, or 14 when require_rooms is set (up to three extra page fetches). A failed call is free. Much heavier than /v1/calendar, so use it for the dates that matter, not all of them.

Request

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

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.

  • tokenstringrequiredmin length 8

    Google property token. Get one from POST /v1/search — it is the token on each match. Looks like ChUIoben2Mv6-CYaCi9tLzA3czVwbjQQAQ.

  • check_instring (date)required

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

  • check_outstring (date) | null

    Alternative to nights; wins if both are given.

  • nightsintegerdefault 1min 1, max 30

    Ignored when check_out is given.

  • marketstring | null

    Market/country, e.g. US, MX, AU, GB. Sets gl and the default tax basis. Null when omitted.

    52 allowed values

    AE, AG, AR, AT, AU, BE, BR, BZ, CA, CH, CL, CN, CO, CZ, DE, DK, EG, ES, FI, FR, GB, GR, HK, HR, HU, ID, IE, IL, IN, IT, JP, KR, MX, MY, NL, NO, NZ, PE, PH, PL, PT, QA, RO, SA, SE, SG, TH, TR, TW, US, VN, ZA

  • currencystring | null

    ISO currency for the returned prices. It is part of the request, so it does not depend on where the request is served from.

    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

    Occupancy. Any value 1-8 works. Children are not supported by the calendar.

  • rates_include_taxboolean | null

    Which basis the summary price uses. Defaults to the market convention.

  • property_namestringdefault

    Improves official-site detection

  • include_metasearchbooleandefault false

    Include metasearch aggregators (Trivago, Vio, Kayak, Goseek) alongside real OTAs. Off by default: they resell other sources, so they inflate the offer count without adding inventory.

  • free_cancellation_onlybooleandefault false

    Only offers with a stated free-cancellation deadline

  • devicestringdefault iphone

    Render profile. Google returns a different offer list per device and desktop is the thinnest — iphone found 17 offers where desktop found 12 on the same property.

    One ofandroiddesktopiphone

  • coverageintegerdefault 1min 1, max 3

    Fetch this many device profiles and merge. Each one is an extra page fetch; 2 is the sensible maximum.

  • require_sourcesarray of string | null

    Sources to insist on; retries a thin answer. Defaults to official + Booking + Hotels.com + Expedia + Agoda. Pass [] to disable.

  • require_roomsbooleandefault false

    Fetch again (up to 3 extra pages) until an offer carries per-room detail. Google omits room detail from about half of its pages at random; carried_room_detail says which you got. A truthy value costs 14 credits instead of 10. A failed call is free either way.

Example request

curl -X POST "https://api.scrapercompany.com/v1/offers" \
  -H "x-api-key: $SCRAPERCOMPANY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "ChUIoben2Mv6-CYaCi9tLzA3czVwbjQQAQ",
    "check_in": "2027-01-15",
    "nights": 1,
    "market": "US",
    "currency": "USD"
  }'

Response

200 — Every OTA on the property for one night, with per-room detail. Metered responses carry x-credits-charged and x-credits-remaining headers (see credit headers).

200 response
{
  "token": "ChUIoben2Mv6-CYaCi9tLzA3czVwbjQQAQ",
  "check_in": "2027-02-10",
  "check_out": "2027-02-11",
  "nights": 1,
  "adults": 2,
  "device": "iphone",
  "coverage": 2,
  "currency": "USD",
  "currency_matches_request": true,
  "rates_include_tax": false,
  "requested_market": "US",
  "lowest_price_per_night": 303.67,
  "rooms_total": 173,
  "carried_room_detail": true,
  "renders": 1,
  "name": "Hilton Chicago",
  "hotel_class": "4-star hotel",
  "hotel_class_stars": 4,
  "rating": 4.3,
  "reviews": 10686,
  "deal": "25% less than usual",
  "has_deal": true,
  "deal_description": "Great Deal",
  "price_insights": {
    "lowest_price": "$304",
    "price_level": "typical",
    "typical_price_range": {
      "low_price": "$304",
      "high_price": "$521"
    }
  },
  "sources": [
    "Official site",
    "Booking.com"
  ],
  "missing_sources": [],
  "refundable_offers": 2,
  "elapsed_s": 1.14,
  "warnings": [],
  "offers": [
    {
      "source": "Official site",
      "raw_source": "Hilton Chicago",
      "is_official": true,
      "nights": 1,
      "currency": "USD",
      "price_per_night": 499.44,
      "price_per_night_before_taxes": 420.05,
      "tax": 79.39,
      "total": 499.44,
      "has_free_cancellation": true,
      "free_cancellation_until": "2027-02-06",
      "free_cancellation_time": "23:59",
      "room_id": "rate-plan-42",
      "rate_plan_id": "rate-plan-42",
      "provenance": {
        "schema_version": 1,
        "observation_id": "rateobs_0123456789abcdef0123456789abcdef",
        "collection_id": "ratecol_0123456789abcdef0123456789abcdef",
        "observed_at": "2026-08-07T01:23:45.678Z",
        "source": "google_hotels_property_offers",
        "source_kind": "offer",
        "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"
      },
      "rooms": [
        {
          "name": "1 KING BED",
          "description": "1 bed",
          "beds": 1,
          "is_suite": false,
          "price_before_taxes": 420.06,
          "price_total": 499.45,
          "has_free_cancellation": true,
          "free_cancellation_until": "2027-02-06",
          "free_cancellation_time": "23:59",
          "link": "https://www.google.com/aclk?...",
          "thumbnail": "https://lh3.googleusercontent.com/...",
          "rate_plans": [
            {
              "price_before_taxes": 420.06,
              "price_total": 499.45,
              "link": "https://www.google.com/aclk?...",
              "free_cancellation_until": "2027-02-06",
              "free_cancellation_time": "23:59",
              "refundable": true,
              "rate_category": "unknown"
            },
            {
              "price_before_taxes": 455.06,
              "price_total": 541.1,
              "link": "https://www.google.com/aclk?...",
              "free_cancellation_until": "2027-02-06",
              "free_cancellation_time": "23:59",
              "refundable": true,
              "meal_plan": "breakfast",
              "rate_category": "unknown"
            }
          ]
        }
      ]
    }
  ]
}
Arrays are shortened to their first items.

Response fields

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

  • tokenstringrequired
  • check_instring (date)required
  • check_outstring (date)required
  • nightsintegerrequired
  • adultsintegerrequired
  • devicestringrequired
  • coverageintegerrequired

    Device profiles fetched (echo of the request).

  • currencystring | nullrequired

    Currency the page actually priced in.

  • currency_matches_requestbooleanrequired
  • requested_marketstringrequired
  • egress_marketstring | nullrequired

    Market the seller list is verified for, or null when unverified.

  • egress_geo_locked_okbooleanrequired
  • price_insights_market_verifiedbooleanrequired
  • rates_include_taxbooleanrequired

    Basis used for lowest_price_per_night.

  • lowest_price_per_nightnumber | nullrequired
  • rooms_totalintegerrequired
  • namestringrequired
  • hotel_classstringrequired
  • hotel_class_starsinteger | nullrequired
  • ratingnumber | nullrequired
  • reviewsinteger | nullrequired
  • dealstring | nullrequired
  • deal_descriptionstring | nullrequired
  • has_dealbooleanrequired
  • price_insightsobjectrequired
    Show 4 child fields
    • price_insights.lowest_pricestring | nullrequired

      As Google displays it, e.g. $304.

    • price_insights.price_levelstring | nullrequired
    • price_insights.price_level_codeinteger | nullrequired
    • price_insights.typical_price_rangeobject | nullrequired
      Show 2 child fields
      • price_insights.typical_price_range.low_pricestring | nullrequired
      • price_insights.typical_price_range.high_pricestring | nullrequired
  • sourcesarray of stringrequired

    Distinct sellers in offers.

  • missing_sourcesarray of stringrequired

    Required sources not offered after retry.

  • refundable_offersintegerrequired
  • elapsed_snumberrequired
  • warningsarray of stringrequired
  • offersarray of objectrequired
    Show 21 child fields
    • offers[].sourcestringrequired

      Normalized seller name, e.g. Booking.com, Official site.

    • offers[].raw_sourcestringrequired

      Seller name exactly as Google rendered it.

    • offers[].is_officialbooleanrequired
    • offers[].currencystring | nullrequired
    • offers[].nightsintegerrequired
    • offers[].room_idstring | nullrequired

      Seller-native room / rate-plan id.

    • offers[].price_per_nightnumber | nullrequired

      All-in price per night.

    • offers[].price_per_night_before_taxesnumber | nullrequired
    • offers[].totalnumber | nullrequired

      All-in price for the stay window.

    • offers[].taxnumber | nullrequired
    • offers[].feesnumber | nullrequired
    • offers[].has_free_cancellationbooleanrequired
    • offers[].free_cancellation_untilstring | nullrequired
    • offers[].free_cancellation_timestring | nullrequired
    • offers[].discount_remarksarray of stringrequired

      Member/loyalty remarks shown beside the offer.

    • offers[].has_member_ratebooleanrequired
    • offers[].roomsarray of objectrequired
      Show 11 child fields
      • offers[].rooms[].namestringrequired
      • offers[].rooms[].descriptionstringrequired
      • offers[].rooms[].linkstring | nullrequired
      • offers[].rooms[].price_before_taxesnumber | nullrequired
      • offers[].rooms[].price_totalnumber | nullrequired
      • offers[].rooms[].is_suitebooleanrequired
      • offers[].rooms[].bedsinteger | nullrequired
      • offers[].rooms[].has_free_cancellationbooleanrequired
      • offers[].rooms[].free_cancellation_untilstring | nullrequired
      • offers[].rooms[].free_cancellation_timestring | nullrequired
      • offers[].rooms[].thumbnailstring | nullrequired
    • offers[].headline_price_totalnumber | nullrequired
    • offers[].headline_price_before_taxesnumber | nullrequired
    • offers[].price_derived_from_roombooleanrequired
    • offers[].provenanceobjectrequired

      Where, when and how one normalized price was observed.

      Show 13 child fields
      • offers[].provenance.schema_versionintegerrequired

        Provenance schema version (currently 1).

      • offers[].provenance.observation_idstringrequired

        Deterministic id of this price observation (rateobs_...).

      • offers[].provenance.collection_idstringrequired

        Id shared by every price from one upstream fetch (ratecol_...).

      • offers[].provenance.observed_atstringrequired

        UTC observation time, ISO-8601.

      • offers[].provenance.sourcestringrequired

        Upstream source, e.g. google_hotels_calendar.

      • offers[].provenance.source_kindstringrequired

        Kind of source, e.g. calendar, offer, ota_calendar, official.

      • offers[].provenance.source_property_idstringrequired

        Property identifier at the source.

      • offers[].provenance.requested_marketstring | nullrequired
      • offers[].provenance.requested_currencystring | nullrequired
      • offers[].provenance.returned_currencystring | nullrequired
      • offers[].provenance.price_basisstringrequired

        What the price represents, e.g. room_base_before_taxes_and_fees.

      • offers[].provenance.derivationstringrequired

        How the figure was derived, e.g. normalized_upstream.

      • offers[].provenance.upstream_rate_idstring | nullrequired

        Source-native rate/room id when available.

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
404Not Found

The property, stay, job or record was not found.

{"detail":"job not found"}
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

10 credits (14 with require_rooms) per successful call. Failed calls cost 0.

Questions about this page?

Send the page link and your question, and the team will answer.

Email support