Booking.com availability

Check day-by-day availability for a known Booking.com listing — the booking calendar over any date window.

Setup

If $STAYINGAPI_KEY is not set, read references/auth-setup.md and follow it to get and store the key. A stay_test_ sandbox key works for evaluation at zero cost.

When to use this skill

DO use when the user asks:

• "Is this Booking.com listing free the first week of August?"
• "Show the calendar for this Booking.com place"

Do NOT use when:

• You do not yet have a listing id — search first
• The user wants a price, not open/closed dates — use the prices skill

Required headers

Every request needs:

• Authorization: Bearer $STAYINGAPI_KEY
• User-Agent: your agent's name (e.g. ClaudeCode/1.0).

Base URL: https://api.stayingapi.com/v1.

Tools

GET /v1/availability

Get day-by-day availability for a known listing (or a batch of listings) on one platform over a date window. Each day reports whether it is available, its minimum-night requirement, and whether check-in / check-out / booking is allowed.

Key parameters:

• platform — Required. vrbo | booking | airbnb | google. Single platform (not a fan-out endpoint). Use the API value, not the brand name — "booking", not "booking-com"; "google", not "google-hotels".
• listingId — A single listing id on platform.
• listingIds[] — A batch of listing ids on platform.
• url — Full listing URL (alternative to an id).
• startDate — Required. YYYY-MM-DD; not in the past.
• endDate — Required. After startDate; window ≤ 365 days.

MCP (no key pasted into the agent)

On an MCP-capable runtime, connect https://mcp.stayingapi.com/mcp (OAuth 2.1 + PKCE) and use: check_availability.

Platform × endpoint support

Not every endpoint supports every platform. Verified:

platform	search	availability	price	price-compare	listing	reviews
airbnb	yes	yes	yes	yes	yes	yes
booking	yes	yes	yes	yes	yes	yes
vrbo	yes	yes	yes	yes	yes	yes
google	yes	yes	yes	yes	no	no

GET /v1/listing/google/… and GET /v1/reviews?platform=google return 400 platform_not_enabled ("google is not enabled for this endpoint"). Use booking, airbnb or vrbo for listing detail and reviews; use google for search, price and cross-OTA price-compare.

The cross-OTA advantage

StayingAPI is cross-platform: Booking.com data comes back in the same unified schema as Airbnb, Vrbo and Google Hotels, so one integration covers them all. /v1/price-compare resolves a property through the Google Hotels backbone and returns the offers it exposes plus a StayingAPI-computed min and median over those offers, as first-class fields.

Coverage varies by property and by what the backbone returns: some properties come back with several OTA offers, others with a single aggregated-lowest offer (in which case min equals median and offers has one entry, sometimes a direct-supplier rate rather than an OTA). Read offers.length before describing a result as a multi-platform comparison.

Async & partial failures

A live call that has to scrape returns 202 with data.jobId, data.pollUrl and data.estimatedSeconds (the 202 itself charges 0). Poll GET /v1/jobs/{jobId} (free) until data.status is TERMINAL — completed or failed.

• completed → the payload is at data.result (the same schema the sync call returns; data itself is just {jobId, result, status}). meta carries partial, platformResults[] and warnings[]. A completed job may still return an empty result (data.result: []) — the reason is in meta.warnings[] (e.g. no_results), and empty results charge 0.
• failed → HTTP is still 200, not an HTTP error. The failure is nested at data.error (code, type, message, retryable). Detect it with data.status === "failed", not a top-level error. creditsCharged is 0, and meta carries only {requestId, creditsCharged, platforms} — do not read partial, platformResults or warnings on a failed job.

Pace your polling: honour the Retry-After header, back off between attempts, and cap the number of attempts. A tight loop hits 429 rate_limit_exceeded (120 requests/minute).

Known limitations

• Pagination: limit/cursor are accepted where documented, but availability depends on the endpoint and the upstream source — treat meta.pagination as authoritative and stop when hasMore is false or nextCursor is null.
• Externally-sourced ids: a Vrbo id obtained somewhere other than /v1/search may not resolve upstream and can produce a failed job (all_actors_failed). Prefer ids from /v1/search (platformListingId).
• Platform gaps: see the support matrix above — google has no listing or reviews endpoint.

Credits

Number-free by design — failed, empty and blocked calls are never billed, and stay_test_ sandbox calls are always free. Current costs: https://stayingapi.com/pricing · full contract: https://api.stayingapi.com/openapi.json.

Trademark

StayingAPI is an independent service and is not affiliated with, endorsed by, or sponsored by Booking.com. Booking.com is a trademark of its respective owner.

---

Get your free key → https://stayingapi.com/signup · Docs: https://stayingapi.com/docs