Search Accommodation

Optional supplier filter. REST accepts a single value (?provider=booking), comma-separated values (?provider=booking,vrbo), or repeated params (?provider=booking&provider=vrbo). MCP/tool callers should pass comma-separated values as a string. Accepted: booking, vrbo, expedia, hotelscom. Multiple values are OR-combined upstream — every returned listing is bookable by at least one of the requested suppliers. Omit the parameter to include every supplier. Note: combining ?provider= with ?hotelids= is only valid for a single supplier (the id-to-supplier mapping is otherwise ambiguous) and returns 400 otherwise.

🔎 ADDRESS METHOD: Human-readable address, place name, or point of interest (e.g., "Eiffel Tower", "Berliner Dom", "Colosseum"). Example: "Paris, France" or "Times Square, New York". For POIs, lat/lng + radius might be more efficient.

📍 LAT/LNG METHOD: Center point latitude for radial search. Range: -90 to 90. Use with lng. Example: 40.7128 for New York City.

📍 LAT/LNG METHOD: Center point longitude for radial search. Range: -180 to 180. Use with lat. Example: -74.0060 for New York City.

📍 LAT/LNG METHOD: Search radius in meters. Default: 10000 (10km) when using lat/lng search.

🗺️ BOUNDING BOX METHOD: North-East corner latitude. Range: -90 to 90. Use all four coordinates (nelng, swlat, swlng) for precise map-based searches. Preferred for map viewports.

🗺️ BOUNDING BOX METHOD: North-East corner longitude. Range: -180 to 180. Use with nelat, swlat, swlng.

🗺️ BOUNDING BOX METHOD: South-West corner latitude. Range: -90 to 90. Use with nelat, nelng, swlng.

🗺️ BOUNDING BOX METHOD: South-West corner longitude. Range: -180 to 180. Use with nelat, nelng, swlat.

Comma-separated list of accommodation IDs for direct lookup. When provided, location parameters are not required. Example: "12345,67890,11223".

Property type filter. Single value or comma-separated list.

Accepted values:

• hotel: traditional hotels only.
• rental: any non-hotel accommodation (the broad "vacation rental" bucket covering every concrete type below).
• Concrete types: palace, lodge, agritourism, riad, ryokan, villa, resort, pension, bed_and_breakfast, apartment, private_vacation_home, bungalow, tourist, all_inclusive, hostel, farm_stay, cabin, residence, house, condo, chalet, country_house, aparthotel, cottage.

Multiple values are OR-combined (e.g. villa,resort returns villas OR resorts). When rental is combined with concrete non-hotel types it absorbs them, since rental already covers every non-hotel value. Omit the parameter to include every type.

Check-in date in YYYY-MM-DD format. Example: 2024-01-31. Real calendar dates only. Explicit values must be today or later and no more than 2 years in the future. Optional — no default applied today.

Check-out date in YYYY-MM-DD format. Example: 2024-02-05. Real calendar dates only. Explicit values must be today or later, no more than 2 years in the future, and (when both are supplied) must be after checkin. Optional — no default applied today.

Number of adult guests (18+ years old). Must be a positive integer. Default: 2. Affects pricing and availability.

Number of children (under 18 years old). Must be zero or a positive integer. Default: 0. Some properties may have age restrictions.

Number of rooms/accommodations needed. Must be a positive integer. Default: 1.

Minimum per-night price filter in USD (before currency conversion). Only applied when supplied AND both checkin/checkout are present. Omit to disable the lower bound. Example: 100 for $100/night minimum.

Maximum per-night price filter in USD (before currency conversion). Only applied when supplied AND both checkin/checkout are present. Omit to disable the upper bound. Example: 500 for $500/night maximum.

Currency code for price display (ISO 4217 format). Prices are converted from USD to this currency. Examples: USD, EUR, GBP, JPY, CAD. Default: USD.

Minimum hotel star rating (0-5). Values greater than 0 return only properties at or above this star class; 0 is accepted as no filter.

Minimum guest review score (0-10). Values greater than 0 return only properties at or above this score; 0 is accepted as no filter.

Minimum number of guest reviews. Integer values greater than 0 filter out properties with fewer reviews than this threshold; 0 is accepted as no filter.

Page size: number of results returned per page. Range: 1-100. Default: 10.

1-indexed page number for pagination. Default: 1. Use with pageSize to walk through results.

Language code for localized content (ISO 639-1 two-letter format). Default: "en". Examples: en (English), fr (French), es (Spanish), de (German), ja (Japanese). Affects property names and descriptions.

Affiliate ID or Partner ID for tracking and attribution. Used for commission tracking and analytics. Provided by Stay22 upon partnership setup. No default (passed through from query only). When an API key is provided, the effective aid is determined by that key.

Campaign identifier for marketing attribution. Use to track performance of specific campaigns or traffic sources. Example: "summer-promo-2024". No default (passed through from query only).

Spatial clustering for map UIs. Defaults to false (flat list). Four modes:

• false (default; also when omitted) — flat list.
• auto — server decides: aggregates dense viewports into H3 clusters when useful, flat list when the viewport is too tight (<5 km diagonal) or unsuitable.
• true — force clustering whenever geometrically possible; clamps tight viewports to the deepest H3 resolution (r8, ~460 m hexes).
• top — one representative (the best-rated stay) per H3 cell directly in results[], tagged with cellId. With dates, only available representatives are returned (total then counts only those cells; without dates it is the candidate-cell count). Unlike auto/true, keeps clustering at tight zoom (up to r11) instead of going flat.

Structural blockers (ID lookups, center+radius without a bbox, no resolvable viewport) always return a flat list. auto/true responses include a clusters[] array alongside sparse results[] (disjoint); each cluster has count, location.bounds, location.coordinates, and a _links.expand URL.

Optional H3 resolution override for cluster=top (ignored for other modes). Range r0 (~1,000 km hexes) to r15 (~0.5 m hexes); out-of-range values are rejected with a 400. Sets cell size and forces top mode at any zoom. When omitted, the server derives a resolution from the viewport, keeping clustering down to ~r11 rather than going flat.

Optional H3 cell filter. Primarily used by cluster expand links.