ScraperCompany · APIs · Pricing · Docs · llms.txt · Get an API key

Competitor rate shopping

Rate shopping for your comp set, 330 nights at a time

Pull forward rate calendars for every hotel in a competitive set, queue the whole set as one job, and receive a signed webhook when the rates are ready.

Built for revenue managers, hotel groups, pricing-engine builders, hospitality consultants.

Endpoints used

Your rank, every night

Five forward calendars from one job, drawn as one chart. Move across the nights to see where you sit.

Example · comp-set rate shopper

Where do we rank against our comp set each night?

  1. POST /v1/jobs
  2. GET /v1/jobs/{job_id}
  3. your chart

Your rank

3 of 5

Comp median

$360

Below median

10 of 30 nights

$150$275$400Apr 12Apr 19Apr 26May 3May 10

Fri, Apr 30 city-wide event

  1. 1 Saltmarsh Inn $307
  2. 2 Alder Hotel $344
  3. 3 Your hotel $351
  4. 4 The Kestrel $375
  5. 5 Linden House $394

Fictional hotels, illustrative rates. One job collects all five calendars.

What will our comp set charge for the next 90 nights?

Revenue decisions run on what the comp set will charge, night by night, months out. Rate-shopping tools sell that as a screen. If your pricing engine, BI stack or product needs the numbers, you need them as data.

Fetching one night per request makes a 90-night horizon 90 requests per competitor. A calendar returns the whole horizon at once, with base, taxes, fees and total kept apart so the numbers compare cleanly.

How teams build it

  1. 1 Resolve each competitor

    Find each hotel once by name and city and store its Google property token.

    POST /v1/search
  2. 2 Queue the comp set

    Submit up to 50 properties in one job with an idempotency key. The job is stored before the API answers and survives restarts.

    POST /v1/jobs
  3. 3 Collect the calendars

    Poll the job, or pass a callback URL and receive a signed webhook when it finishes. Each item is a forward calendar of up to 330 nights.

    GET /v1/jobs/{job_id}
  4. 4 Load and compare

    Every rate row says when and how it was observed, so day-over-day changes are traceable in your warehouse.

What you get back

Nightly rates
up to 330 nights per hotel per call, 90 by default
Price parts
base, taxes, fees and total kept apart on every night
Provenance
when and how each rate was observed
Webhooks
a signed callback when a comp-set job finishes
curl -X POST "https://api.scrapercompany.com/v1/calendar" \
  -H "x-api-key: $SCRAPERCOMPANY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "ChUIoben2Mv6-CYaCi9tLzA3czVwbjQQAQ",
    "market": "US",
    "currency": "USD",
    "days": 90
  }'
Response (trimmed)
{
  "token": "ChUIoben2Mv6-CYaCi9tLzA3czVwbjQQAQ",
  "market": "US",
  "collection_id": "ratecol_0123456789abcdef0123456789abcdef",
  "observed_at": "2026-08-07T01:23:45.678Z",
  "requested_days": 90,
  "coverage": 0.9333,
  "elapsed_s": 0.31,
  "calendar_elapsed_s": 0.14,
  "unpriced_dates": [
    "2027-01-16"
  ],
  "validation": {
    "ok": true,
    "errors": [],
    "warnings": []
  },
  "tax_profile": {
    "rate": 0.2032,
    "confidence": "high",
    "itemised": 84,
    "derived": 0
  },
  "vat_basis": "unknown",
  "rates": [
    {
      "stay_date": "2027-01-01",
      "rate": 332.01,
      "rate_base": 332.01,
      "rate_total": 424.48,
      "tax": 67.47,
      "fees": 25,
      "currency": "USD",
      "market": "US",
      "rates_include_tax": false,
      "adults": 2,
      "los": 1,
      "implied_tax_rate": 0.203217,
      "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",
        "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"
      }
    }
  ]
}

A revenue manager tracks 8 competitors for the next 90 nights, every morning

Illustrative scenario, not a customer

CallPer dayCredits eachCredits a day
Calendar job item, 8 hotels × 90 nights8864
Credits a month
1,920
Fits on
Starter
Plan price
$49 a month

30 days a month. Failed and empty requests cost nothing, so a bad day costs less. Compare plans

Common questions

Read next

How far ahead can I see rates?

One calendar call returns up to 330 nights for one hotel (90 by default), for 8 credits.

How many hotels fit in one job?

Up to 50. Each succeeded item is billed like a single calendar call; submitting and polling the job are free.

What if a night has no price?

Nights with no bookable price are listed in unpriced_dates, and coverage gives the share of nights that priced. A calendar where no night priced, such as a closed property, is not charged.

Can I retry safely after a timeout?

Yes. Every job submission carries an Idempotency-Key header. Reusing a key with the same body returns the original job instead of starting a new one.

What else teams build

Start with 50 free calls

Create an account and verify your email: your own API keys and a free trial of 50 calls or 14 days, whichever ends first, no card needed. Then buy a credit pack from $15 or pick a plan from $49 a month.

7,500 credits, one-time. No subscription. Or try it free: 50 calls, no card.