Skip to main content
Search live hotel inventory and rates. REQUIRED:
  • destination: object with exactly one of { query }, { city_name (+ country_code) }, { latitude + longitude (+ radius_km) }, { place_id }, or { hotel_ids }
  • checkin, checkout: YYYY-MM-DD
  • occupancy: either { occupancies: [{ adults, children_ages? }, …] } (one entry per room) OR shorthand { adults, children?, rooms? }
OPTIONAL:
  • currency (ISO 4217), guest_nationality (ISO 3166-1 alpha-2)
  • filters: { min_rating, star_rating, min_reviews, hotel_type_ids, chain_ids, facility_ids, max_results }
EXAMPLES:
  1. Free-text city search: { “destination”: { “query”: “Paris” }, “checkin”: “2026-07-15”, “checkout”: “2026-07-18”, “adults”: 2 }
  2. Two-room family with kids: { “destination”: { “city_name”: “Barcelona”, “country_code”: “es” }, “checkin”: “2026-08-01”, “checkout”: “2026-08-05”, “occupancies”: [{ “adults”: 2 }, { “adults”: 1, “children_ages”: [5, 7] }] }
  3. Geo-radius search around a POI: { “destination”: { “latitude”: 41.4036, “longitude”: 2.1744, “radius_km”: 3 }, “checkin”: “2026-09-10”, “checkout”: “2026-09-12”, “adults”: 2 }
RESPONSE:
  • Each hotel includes basic metadata (name, address, star_rating, rating, main_photo) and a rooms[] list.
  • Each room has a rates[] list. Each rate has an offer_id (the htl_* token), board type, refund policy, and total_amount + currency.
NEXT STEP: Use the trip tool with add_item and the offer_id of the rate the user picks. Hotel items work alongside flight items in the same cart. Flow: hotel_search → trip(add_item) → trip(upsert_travelers) → book

​
Parameters

NameTypeRequiredDescription
destinationobjectYesDestination — provide exactly one shape: { query }, { city_name (+ optional country_code) }, { latitude + longitude (+ optional radius_km) }, { place_id }, or { hotel_ids }.
destination.querystringNoFree-text destination (city, region, POI, neighborhood). Use for natural-language destinations like “Paris” or “Tuscany”. Max 200 chars.
destination.city_namestringNoCity name (e.g. “Paris”). Pair with country_code for disambiguation.
destination.country_codestringNoISO 3166-1 alpha-2 country code (lowercase preferred, e.g. “fr”). Must be paired with city_name — other destination shapes ignore it.
destination.latitudenumberNoLatitude for geo-radius search. Pair with longitude.
destination.longitudenumberNoLongitude for geo-radius search. Pair with latitude.
destination.radius_kmnumberNoGeo-radius in km (default 5, max 50). Requires latitude+longitude — ignored with other destination shapes.
destination.place_idstringNoGoogle Places ID or upstream place identifier.
destination.hotel_idsarray<string>NoRe-shop a known set of hotel IDs (skips destination resolution).
checkinstringYesCheck-in date (YYYY-MM-DD).
checkoutstringYesCheck-out date (YYYY-MM-DD).
occupanciesarray<object>NoOne entry per room (structured). Use this when room composition matters. Example: [{ “adults”: 2 }, { “adults”: 1, “children_ages”: [5] }]. Do NOT combine with the shorthand fields (adults/children/rooms) — use one or the other.
adultsintegerNoShorthand: total adults across all rooms. Do NOT combine with occupancies[] — use one or the other.
childrenarray<integer>NoShorthand: ages of all children across all rooms.
roomsintegerNoShorthand: number of rooms (BFF auto-distributes adults + children).
currencystringNoISO 4217 currency code. Defaults to “USD”.
guest_nationalitystringNoGuest nationality (ISO 3166-1 alpha-2, lowercase). Affects rate availability + tax handling at search time. Separate from traveler nationality used for booking documents.
filtersobjectNoOptional filter overrides applied on top of the tenant default filter set.
filters.min_ratingnumberNoMinimum guest review rating (0-10 scale).
filters.star_ratingintegerNoMinimum star rating (1-5).
filters.min_reviewsintegerNoMinimum number of guest reviews.
filters.hotel_type_idsarray<string>NoFilter by hotel type IDs (e.g. boutique, resort).
filters.chain_idsarray<string>NoFilter by hotel chain IDs (e.g. “hilton”, “marriott”, “accor”, “ihg”).
filters.facility_idsarray<string>NoFilter by facility IDs (e.g. pool, gym, spa). Applied at connector search time, not post-filtered.
filters.max_resultsintegerNoMaximum number of hotels to return (default 50).