Search stay solutions (SSE stream)

Stream stay solutions for a destination and date range. Accepts either an authenticated bearer token or a guest session token. When the requested stay exceeds the configured maximum nights, the stream terminates with event: error and code MAX_NIGHTS_EXCEEDED (message includes the allowed maximum). Other provider failures use PROVIDER_ERROR.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params

POST body for /v1/stays/search.

Occupancy can be specified in two ways:

  • Explicit rooms — supply rooms with per-room adult counts and child
    ages. When rooms is provided it takes precedence over passengers.
  • Simple traveler count — omit rooms and supply passengers
    (or rely on its default of one adult). build_stay_search_params then
    derives a single room from passengers.adults and
    passengers.children.

Destination can be specified in one of two mutually exclusive ways:

  • Place destination — supply destination (a place identifier such
    as "milan-IT"). This is the standard city/region search.
  • Property destination — supply property (a
    :class:StayPropertyDestination object from the autocomplete). Mercury
    resolves the property's city to a place identifier, searches that city,
    and streams only the solution matching the exact propertyId.

Exactly one of destination or property must be provided; supplying
both or neither returns 422 UNPROCESSABLE_ENTITY with a field-level
error.

length ≥ 1

Place identifier for the destination (e.g. milan-IT). Mutually exclusive with property; exactly one must be provided.

StayPropertyDestination | null

Named-property destination from the autocomplete. Mutually exclusive with destination; exactly one must be provided.

date
required

Check-in date as YYYY-MM-DD. Must be today or a future date.

date
required

Check-out date as YYYY-MM-DD. Must be after checkIn.

array | null

Per-room occupancy configurations. When provided, takes precedence over passengers. Omit to use passengers for a single-room search.

passengers
object

Traveler counts used to derive a single room when rooms is not provided. Ignored when rooms is supplied. infants has no stay-occupancy equivalent and is always excluded from room derivation.

enum

Booking profile context. Use 'personal' for personal-rate results or 'business' for business-rate results.

ISO country code (e.g. IT) for rate eligibility.

Headers
string
enum
Defaults to application/json

Generated from available response content types

Allowed:
Responses

401

Unauthenticated

403

Provider refused the property-destination lookup (resolved deny, only when the request supplies property)

503

Provider unavailable

Language
Credentials
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json