Skip to content
ScoutingAPI
Docs

Introduction

StayingAPI documentation

One accommodation data API for availability, search and cross-OTA price comparison across Airbnb, Booking.com, Vrbo and Google Hotels — one unified schema, REST + MCP, built for developers and AI agents.

Quickstart Try it liveDownload OpenAPI spec

Live vs sandbox — read this first

The sandbox and live share one schema and envelope, but they do not behave identically on the wire. Build against a stay_test_ key, then design for these live differences before you switch to stay_live_:

  • Live is asynchronous. Sandbox calls and live cache hits return 200 synchronously. A live call that has to scrape returns 202 with a data.jobId; you poll GET /v1/jobs/{jobId} (free) until it completes, then read the payload from data.result — not data.
  • Timing is real. A job usually finishes in tens of seconds but can run several minutes (240s+). Budget your polling wait accordingly.
  • Use the SDK to feel synchronous. The @stayingapi/sdk auto-polls a 202 to completion and returns the finished { data, meta } for you (raise its maxWaitMs for long live jobs).
  • Embedded prices are best-effort. A dated search or listing price can be null on a scrape miss even though the call still bills; use /v1/price for a guaranteed quote.
  • IDs are platform-native. platformListingId is numeric on Airbnb/Vrbo and a slug string (e.g. luxury-rooms-split) on Booking.com/Google — never assume numeric.
  • Cursor pagination applies to synchronous results. On an async-returned job, meta.pagination is null (see pagination & jobs).
  • Cache hits still bill at the full endpoint tier, and live credits unlock after email verification.

One unified schema

Airbnb, Booking.com, Vrbo and Google Hotels normalize to the same Property, Price, Availability and Review shapes — code once, query every platform.

Failed calls are free

Failed, empty, blocked and not-found calls are never billed. You only pay for data actually delivered — reliability, at the billing layer.

REST + native MCP

The same capabilities as seven REST endpoints and seven read-only MCP tools, so agents are a first-class, day-one audience.

See it — no sign-up

This is the flagship /v1/price-compare endpoint running against the deterministic sandbox: a real cross-OTA comparison with StayingAPI-computed min and median. Zero credits, no key required.

Try itsandbox · 0 credits · no sign-up
GET/v1/price-compare

Runs against the deterministic Google Hotels sandbox fixture — a real 200, zero credits.

Response

Run the call to see a live, deterministic sandbox response.

Copy as curl
curl -sS "https://api.stayingapi.com/v1/price-compare" \
  -H "Authorization: Bearer $STAYINGAPI_KEY"

Explore the docs

Core concepts

Response & error envelopeThe one canonical envelope every endpoint returns: success (200), async-accepted (202) and error (4xx/5xx), plus partial fan-out semantics.The unified schemaProperty, Availability, Price, PriceCompare and Review — the same normalized shapes across every platform, plus the amenity taxonomy and currency rules.Errors & the failed-calls-free ruleThe locked error-type catalog, the machine-stable sub-code list, and the guarantee that failed, empty, blocked and not-found calls are never billed.Pagination, rate limits & jobsCursor pagination, per-plan rate-limit headers, /v1 versioning policy, and the 202 → jobId async pattern for long scrapes.Credits & pricingHow credits are metered per endpoint tier, why cache hits still bill, and the failed-calls-are-free policy that makes reliability real at the billing layer.

Endpoints

SearchGET /v1/search — cross-platform property discovery by location, dates, occupancy and filters, merged into one unified result set.PriceGET /v1/price — a real price quote for one listing over specific dates and occupancy, in the currency you request.Price compareGET /v1/price-compare — the flagship cross-OTA price comparison for one property, with StayingAPI-computed min and median.AvailabilityGET /v1/availability — day-by-day availability for a known listing (or batch) on one platform over a date window.ListingGET /v1/listing/{platform}/{id} — full listing detail: amenities, photos, host, ratings, and an optional embedded live price.ReviewsGET /v1/reviews — normalized, paginated reviews for one listing, with native rating scales preserved.AccountGET /v1/account — programmatic plan, credit balance, key environment and per-plan rate limit. Synchronous, free, works for live and sandbox keys.Async jobsGET /v1/jobs/{jobId} — poll a long-running scrape returned as a 202. Polling is always free; the work is billed once, on success.

Base URLs

REST lives at https://api.stayingapi.com/v1; the MCP server at https://mcp.stayingapi.com. Every response is application/json; charset=utf-8, camelCase, HTTPS only.

Ready to build?

Get a free key — 300 credits, no credit card. Sandbox keys work instantly; live credits unlock after a one-click email verification.

Get your free key