Stored rates

Request#

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

Parameters#

• tokenstringrequiredmin length 8

  Google property token whose rates have already been collected into stored rates (for example by a POST /v1/jobs batch).

• startstring (date) | null

  Inclusive first stay date.

• endstring (date) | null

  Inclusive last stay date.

• limitintegerdefault 500min 1, max 2000

Example request#

curl "https://api.scrapercompany.com/v1/rates/stored?token=ChUIoben2Mv6-CYaCi9tLzA3czVwbjQQAQ" \
  -H "x-api-key: $SCRAPERCOMPANY_API_KEY"

Response#

200 — Latest stored rates; this endpoint performs no live collection.

{
  "source": "google_hotels",
  "source_property_id": "ChUIoben2Mv6-CYaCi9tLzA3czVwbjQQAQ",
  "count": 1,
  "last_observed_at": "2026-08-07 03:08:24.123+00",
  "last_success_at": "2026-08-07 03:08:25.456+00",
  "age_seconds": 42,
  "freshness": "fresh",
  "rates": [
    {
      "property_name": "Hilton Chicago",
      "stay_date": "2028-12-30",
      "occupancy_key": "adults=2",
      "los": 1,
      "rate": 332.01,
      "rate_base": 307.01,
      "rate_before_taxes_with_fees": 332.01,
      "rate_total": 399.48,
      "tax": 67.47,
      "fees": 25,
      "currency": "USD",
      "market": "US",
      "rates_include_tax": false,
      "observed_at": "2026-08-07 03:08:24.123+00",
      "last_changed_at": "2026-08-07 03:08:24.123+00",
      "collection_id": "ratecol_0123456789abcdef0123456789abcdef",
      "observation_id": "rateobs_0123456789abcdef0123456789abcdef",
      "provenance": {
        "schema_version": 1,
        "observation_id": "rateobs_0123456789abcdef0123456789abcdef",
        "collection_id": "ratecol_0123456789abcdef0123456789abcdef",
        "observed_at": "2026-08-07T01:23:45.678Z",
        "source": "google_hotels_calendar",
        "source_kind": "calendar",
        "collector": "scrapingme.google_calendar",
        "source_property_id": "ChUIoben2Mv6-CYaCi9tLzA3czVwbjQQAQ",
        "requested_market": "US",
        "requested_currency": "USD",
        "returned_currency": "USD",
        "egress_mode": "direct",
        "price_basis": "room_base_before_taxes_and_fees",
        "derivation": "normalized_upstream"
      }
    }
  ]
}

Response fields#

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

• sourcestringrequired

  One ofgoogle_hotels

• source_property_idstringrequired

  The requested token.

• countintegerrequired
• last_observed_atstring | nullrequired

  Timestamp string, e.g. 2026-08-10 14:05:00.123456+00.

• last_success_atstring | nullrequired

  Timestamp string, e.g. 2026-08-10 14:05:00.123456+00.

• age_secondsinteger | nullrequired
• freshnessstringrequired

  fresh <= 24 h, stale <= 48 h, expired older, missing when never collected.

  One ofmissingfreshstaleexpired

• ratesarray of objectrequired
  Show 19 child fieldsHide child fields

  • rates[].property_namestringrequired
  • rates[].stay_datestring (date)required
  • rates[].occupancy_keystringrequired

    e.g. adults=2

  • rates[].losintegerrequired
  • rates[].ratenumber | nullrequired
  • rates[].rate_basenumber | nullrequired
  • rates[].rate_before_taxes_with_feesnumber | nullrequired
  • rates[].rate_totalnumber | nullrequired
  • rates[].taxnumber | nullrequired
  • rates[].feesnumber | nullrequired
  • rates[].currencystringrequired
  • rates[].marketstring | nullrequired
  • rates[].rates_include_taxbooleanrequired
  • rates[].min_length_of_stayinteger | nullrequired
  • rates[].observed_atstringrequired

    Timestamp string, e.g. 2026-08-10 14:05:00.123456+00.

  • rates[].last_changed_atstringrequired

    Timestamp string, e.g. 2026-08-10 14:05:00.123456+00.

  • rates[].collection_idstringrequired
  • rates[].observation_idstringrequired
  • rates[].provenanceobjectrequired

    Provenance of one calendar row.

    Show 17 child fieldsHide child fields

    • rates[].provenance.schema_versionintegerrequired

      Provenance schema version (currently 1).

    • rates[].provenance.observation_idstringrequired

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

    • rates[].provenance.collection_idstringrequired

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

    • rates[].provenance.observed_atstringrequired

      UTC observation time, ISO-8601.

    • rates[].provenance.sourcestringrequired

      Upstream source, e.g. google_hotels_calendar.

    • rates[].provenance.source_kindstringrequired

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

    • rates[].provenance.collectorstringrequired

      Identifier of the collector that produced the price.

    • rates[].provenance.source_property_idstringrequired

      Property identifier at the source.

    • rates[].provenance.requested_marketstring | nullrequired
    • rates[].provenance.requested_currencystring | nullrequired
    • rates[].provenance.returned_currencystring | nullrequired
    • rates[].provenance.egress_modestringrequired

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

    • rates[].provenance.price_basisstringrequired

      What the price represents, e.g. room_base_before_taxes_and_fees.

    • rates[].provenance.derivationstringrequired

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

    • rates[].provenance.upstream_rate_idstring | nullrequired

      Source-native rate/room id when available.

    • rates[].provenance.derived_fieldsarray of stringrequired

      Fields computed by ScraperCompany rather than read from the source.

    • rates[].provenance.mainstreamobject

      Present only when mainstream figures were added (basis: mainstream).

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.