Vrbo — complete toolkit

The everything skill for Vrbo: search, availability, listing detail, price, cross-OTA price comparison and reviews — one key, one schema. Install the focused skills instead when you want a minimal tool surface.

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:

• Any Vrbo data task — the agent picks the right call

Do NOT use when:

• You want the smallest possible tool surface — install a focused 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/search

Discover properties matching a location, dates, occupancy and filters across one or more platforms. Results from every requested platform are normalized to the same Property shape and merged into a single, cursor-paginated list. This is the breadth / funnel endpoint — and the clearest demonstration of "one schema, every platform".

Key parameters:

• location — Required. Place name ("Split, HR") or "lat,lng".
• checkIn — YYYY-MM-DD; required if checkOut given; not in the past.
• checkOut — YYYY-MM-DD; required if checkIn given; must be after checkIn.
• adults — ≥ 1.
• children — ≥ 0.
• childAges[] — Length must equal children. Coarsened for Vrbo/Airbnb.
• platforms[] — Drives fan-out + per-platform billing.

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.

GET /v1/listing/{platform}/{id}

Full normalized detail for one listing: amenities (canonical taxonomy), photos, host, geo, ratings, and — when you pass dates — an embedded live price. The detail body is cached 24 h; any embedded live price is cached at the 1 h price TTL and composed at read time, so a stale price never rides on fresh detail.

Key parameters:

• platform — Required. vrbo | booking | airbnb | google.
• id — Required. Platform-native listing id (case-sensitive, verbatim from source). A bare booking.com slug needs a country — without one it returns 400 needs_country (booking slugs are not globally unique).
• country — ISO-3166 alpha-2 (booking). Disambiguates a bare booking slug without the %2F-encoded /hotel/{cc}/{slug} id — e.g. ?country=co.
• checkIn — Pairs with checkOut; presence embeds a best-effort live price (may be null; the call still bills).
• checkOut — Must be after checkIn.
• adults — ≥ 1 (only used with dates).

GET /v1/price

Quote one listing for specific dates and occupancy. Pass the platform-native platformListingId returned by /v1/search — numeric on Airbnb and Vrbo, a slug string on Booking.com and Google (e.g. "abramovic2") — or a full listing URL. On a live key the response is always a real numeric price or a typed error — never a wrong property's price. Note this guarantee covers live calls: sandbox (stay_test_) responses are canned fixtures and may echo a different listing, dates or occupancy than you requested, so do not assert identity against a sandbox response.

Key parameters:

• platform — Required. vrbo | booking | airbnb | google.
• listingId — Required. Platform-native id from /v1/search platformListingId — numeric (Airbnb/Vrbo) or a slug string (Booking.com/Google). Or pass a url.
• checkIn — Required. YYYY-MM-DD; not in the past.
• checkOut — Required. Must be after checkIn.
• adults — ≥ 1.
• children — ≥ 0.

GET /v1/price-compare

Rate-shop one property in a single call, resolved through the Google Hotels backbone. The response carries the offers the backbone exposes for that property plus StayingAPI-computed min and median over those offers as first-class fields, so you can read the cheapest rate without re-deriving it. Coverage varies by property: some resolve to several OTA offers, others to a single aggregated-lowest offer (then offers has one entry, min equals median, and the entry may be a direct-supplier rate rather than an OTA). Read offers.length before presenting a result as a multi-platform comparison — the schema does not guarantee more than one.

Key parameters:

• name — Property name to resolve.
• googleHotelId — Precise Google Hotels id.
• location — Disambiguating place / "lat,lng".
• checkIn — Required. YYYY-MM-DD; not in the past.
• checkOut — Required. Must be after checkIn.
• adults — ≥ 1.

GET /v1/reviews

Normalized, paginated reviews for one listing on one platform. Native rating scales are preserved and echoed alongside each rating (TripAdvisor/Airbnb/Vrbo use 5; Booking.com/Expedia/Hotels.com use 10) — never silently rescaled.

Key parameters:

• platform — Required. vrbo | booking | airbnb. Note google is NOT enabled for reviews (400 platform_not_enabled). Use the API value, not the brand name — "booking", not "booking-com".
• listingId — Listing id on platform.
• url — Full listing URL.
• limit — 1–100.
• cursor — Opaque base64 cursor.
• language — ISO-639-1 filter.

Filter results to Vrbo by passing platforms=vrbo to the search call.

MCP (no key pasted into the agent)

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

Platform × endpoint support

Not every endpoint supports every platform. Verified:

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: Vrbo data comes back in the same unified schema as Airbnb, Booking.com 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 Vrbo. Vrbo is a trademark of its respective owner.

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