Competitor rate shopping
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 forRevenue managersHotel groupsPricing-engine buildersHospitality consultants
Endpoints used
See it in action
Five forward calendars from one job, drawn as one chart. Move across the nights to see where you sit.
Example · comp-set rate shopper
Your rank
3 of 5
Comp median
$360
Below median
10 of 30 nights
Fri, Apr 30city-wide event
The problem
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.
Workflow
Find each hotel once by name and city and store its Google property token.
POST /v1/searchSubmit up to 50 properties in one job with an idempotency key. The job is stored before the API answers and survives restarts.
POST /v1/jobsPoll 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}Every rate row says when and how it was observed, so day-over-day changes are traceable in your warehouse.
Output
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
}'{
"token": "ChUIoben2Mv6-CYaCi9tLzA3czVwbjQQAQ",
"market": "US",
"collection_id": "ratecol_0123456789abcdef0123456789abcdef",
"observed_at": "2026-08-07T01:23:45.678Z",
"requested_days": 90,
"coverage": 0.9333,
"wire_bytes": 29804,
"elapsed_s": 0.31,
"calendar_elapsed_s": 0.14,
"unpriced_dates": [
"2029-01-12"
],
"validation": {
"ok": true,
"errors": [],
"warnings": []
},
"tax_profile": {
"rate": 0.2032,
"confidence": "high",
"itemised": 84,
"derived": 0
},
"rates": [
{
"stay_date": "2028-12-28",
"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",
"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"
}
}
]
}Worked example
Illustrative scenario, not a customer
| Call | Per day | Credits each | Credits a day |
|---|---|---|---|
| Calendar job item, 8 hotels × 90 nights | 8 | 5 | 40 |
30 days a month. Failed and empty requests cost nothing, so a bad day costs less. Compare plans
FAQ
Read next
One calendar call returns up to 330 nights for one hotel (90 by default), for 5 credits.
Up to 50. Each succeeded item is billed like a single calendar call; submitting and polling the job are free.
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.
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.
Tell us which properties, sources and engines you need. Our team sets up your account, and you create and rotate API keys yourself. The API is free during the beta.