Endpoint reference

Search

Cross-platform property discovery, merged into one schema.

GET/v1/search

Cross-platform property discovery, merged into one schema.

Creditsper result · min 5 / platform

Cache TTL30 minutes

ReturnsProperty[]

ShapeFan-out

Live calls are asynchronous — you poll for the result

The sample response below is the synchronous shape you get from the sandbox (a stay_test_ key) and from live cache hits. A live (stay_live_) call that has to scrape returns HTTP 202 with a data.jobId instead of blocking. Poll GET /v1/jobs/{jobId} (always free) until data.status is completed, then read the payload below from data.result (not data); the reconstructed meta — credits, platformResults, warnings — sits at the top level. Jobs usually finish in tens of seconds but can run several minutes (240s+), so budget your wait. The @stayingapi/sdk auto-polls a 202 to completion and hands you this exact synchronous-looking envelope — the simplest way to consume the API. See the response envelope for all three shapes.

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".

Parameters

Request parameters
Parameter	Type	Required	Default	Notes
`location`	`string`	Yes	—	Place name ("Split, HR") or "lat,lng". Required.
`checkIn`	`date`	No	—	YYYY-MM-DD; required if checkOut given; not in the past.
`checkOut`	`date`	No	—	YYYY-MM-DD; required if checkIn given; must be after checkIn.
`adults`	`integer`	No	`2`	≥ 1.
`children`	`integer`	No	`0`	≥ 0.
`childAges[]`	`integer[]`	No	—	Length must equal children. Coarsened for Vrbo/Airbnb.
`rooms`	`integer`	No	`1`	≥ 1. Meaningful for hotel platforms.
`propertyType[]`	`enum[]`	No	—	hotel \| apartment \| house \| villa \| cottage \| other.
`amenities[]`	`enum[]`	No	—	Canonical amenity taxonomy. Airbnb amenity/pool is post-filtered.
`minBedrooms`	`integer`	No	—	≥ 0.
`priceMin`	`number`	No	—	≥ 0, in currency.
`priceMax`	`number`	No	—	≥ priceMin.
`minGuestRating`	`number`	No	—	Normalized to the response ratingScale.
`platforms[]`	`enum[]`	No	`vrbo,booking,airbnb,google`	Drives fan-out + per-platform billing.
`limit`	`integer`	No	`10`	1–40.
`cursor`	`string`	No	—	Opaque base64 cursor from a previous page.
`sort`	`enum`	No	`recommended`	recommended \| price_asc \| price_desc \| rating_desc.
`currency`	`string`	No	`USD`	ISO-4217; pass-through + echo.

Request & response

/v1/search

Request

GET /v1/search?location=Split,HR&checkIn=2026-07-13&checkOut=2026-07-20&adults=2&platforms=airbnb,booking&limit=20
Host: api.stayingapi.com
Authorization: Bearer stay_live_…
Accept: application/json

Response

{
  "data": [
    {
      "id": "stays_booking_abramovic2",
      "platform": "booking",
      "platformListingId": "abramovic2",
      "url": "https://www.booking.com/hotel/hr/abramovic2.html",
      "name": "Apartments Abramović",
      "propertyType": "apartment",
      "location": { "lat": 43.51, "lng": 16.44, "city": "Split", "country": "HR" },
      "starRating": null,
      "guestRating": 9.1, "ratingScale": 10, "reviewCount": 142,
      "maxOccupancy": 4, "bedrooms": 2, "bathrooms": 1,
      "amenities": ["pool", "kitchen", "air_conditioning", "wifi"],
      "host": { "name": "Marko", "isSuperhost": false },
      "price": { "currency": "USD", "nightlyPrice": 303, "totalPrice": 2122, "nights": 7 }
    }
    // … more Property objects
  ],
  "meta": {
    "requestId": "req_8sf…",
    "platforms": ["airbnb", "booking"],
    "cached": false, "partial": false,
    "creditsCharged": 56, "currency": "USD",
    "pagination": { "limit": 20, "cursor": null, "nextCursor": "eyJ…", "hasMore": true },
    "platformResults": [
      { "platform": "airbnb", "status": "ok", "creditsCharged": 36, "cached": false, "count": 18 },
      { "platform": "booking", "status": "ok", "creditsCharged": 20, "cached": true, "count": 20 }
    ],
    "warnings": []
  }
}

Code samples

The same call in every language that matters — all returning the identical unified schema.

GET /v1/search

curl -sS "https://api.stayingapi.com/v1/search?location=Split,HR&checkIn=2026-07-13&checkOut=2026-07-20&platforms=airbnb,booking&limit=20" \
  -H "Authorization: Bearer $STAYINGAPI_KEY"

Try it

Run this endpoint against the deterministic sandbox right now — a real 200, zero credits, no sign-up. The credit cost of the equivalent live call is per result · min 5 / platform.

Try itsandbox · 0 credits · no sign-up

GET/v1/search

locationcheckIncheckOutplatformslimitAPI key (optional)

Runs against the deterministic Airbnb + Booking sandbox fixtures — 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/search" \
  -H "Authorization: Bearer $STAYINGAPI_KEY"

Workflows using this

Ready-made automations built on /v1/search — an importable n8n workflow + a portable AI-agent skill each.

STR market scan → Google Sheet dataset — Scan a short-term-rental market — discover listings across platforms, price the top N for your dates, and append a normalized row-per-listing dataset to a Google Sheet.
New-inventory monitor → CRM lead feed — Re-run a saved search on a schedule, diff it against the last run, and sync only the newly-listed properties into a CRM or Sheet as leads.
Agent-native scouting via MCP — Connect StayingAPI as a Claude/Cursor MCP connector and scout stays, compare prices and check availability conversationally — no keys pasted.
Event / peak-date demand radar — Watch supply and prices around an event or peak date-window in a city and get alerted when demand tightens.

Notes & gotchas

Default sort is round-robin "recommended"

When sort is omitted, each platform's native order is preserved and the per-platform lists are merged round-robin (one from each platform in turn), with ties broken by guestRating descending.

Partial fan-out never fails the request

If one platform is blocked while another succeeds, you get HTTP 200 with meta.partial = true, only the successful platforms in data, and the failed platform charged 0 credits. Check meta.platformResults[] to see each leg.

Dated price is best-effort

When you pass checkIn/checkOut, each Property carries an embedded price for those dates — best-effort. A per-listing price scrape can miss, so price may be null or absent on some results even though the leg still bills. Read price defensively; use /v1/price for a guaranteed single-listing quote.