Offers

Request#

Authenticate with your API key in the x-api-key header (see Authentication).

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. Omit to derive it from currency.

  18 allowed values

  AG, AT, AU, BE, BZ, CA, CH, DE, ES, FR, GB, IE, IT, MX, NL, NZ, PT, US

• currencystring | null

  ISO currency for the returned prices.

  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: number of adults, 1-8. Children are not supported by the Google 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. Costs one ~3 MB page each; 2 is the sensible maximum.

• require_sourcesarray of string | null

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

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": "2026-11-30",
    "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).

{
  "token": "ChUIoben2Mv6-CYaCi9tLzA3czVwbjQQAQ",
  "check_in": "2029-02-05",
  "check_out": "2029-02-06",
  "nights": 1,
  "adults": 2,
  "device": "iphone",
  "coverage": 2,
  "currency": "USD",
  "currency_matches_request": true,
  "rates_include_tax": false,
  "requested_market": "US",
  "egress_market": "US",
  "egress_geo_locked_ok": true,
  "price_insights_market_verified": true,
  "lowest_price_per_night": 303.67,
  "rooms_total": 173,
  "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,
  "wire_bytes": 4381263,
  "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": "2029-02-01",
      "free_cancellation_time": "23:59",
      "room_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",
        "collector": "scrapingme.google_property",
        "source_property_id": "ChUIoben2Mv6-CYaCi9tLzA3czVwbjQQAQ",
        "requested_market": "US",
        "requested_currency": "USD",
        "returned_currency": "USD",
        "egress_mode": "market_proxy",
        "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": "2029-02-01",
          "free_cancellation_time": "23:59",
          "link": "https://www.google.com/aclk?...",
          "thumbnail": "https://lh3.googleusercontent.com/..."
        }
      ]
    }
  ]
}

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 fieldsHide 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 fieldsHide 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
• wire_bytesintegerrequired
• elapsed_snumberrequired
• warningsarray of stringrequired
• offersarray of objectrequired
  Show 21 child fieldsHide 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 fieldsHide 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 15 child fieldsHide 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.collectorstringrequired

      Identifier of the collector that produced the price.

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

      How the request reached the source, e.g. direct.

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

Try it#

1. Export your key: export SCRAPERCOMPANY_API_KEY=sk_... (no key yet? request access).
2. Copy the cURL example above and run it in a terminal.
3. Or open the interactive playground on api.scrapercompany.com, paste your key and pick this endpoint.