Hotel Search

Search live hotel inventory and rates.

CONTINUATION:
- To load more from a prior result, send { next_handle } by itself: it continues the same search. Do not repeat destination, dates, occupancy, currency, sort_by, filters, user_intent or trip_id.

FIRST SEARCH REQUIRED:
- destination: object, two distinct modes. Mode A (rate lookup): { hotel_name (+ optional country_code, city_name) } or { hotel_ids }. Mode B (hotel search): { query }, { city_name + country_code }, or { latitude + longitude (+ radius_km) }.
- checkin, checkout: the user's stay dates in YYYY-MM-DD. Check-in must be today or later at the hotel; send timezone (the user's IANA time zone) so a stay that starts tonight is accepted. Check-out must be after check-in.

OCCUPANCY (state it whenever the user gave a party):
- either { occupancies: [{ adults, children_ages? }, ...] } (one entry per room) OR shorthand { adults, children?, rooms? }, not both.
- When the user stated no party at all, you may search without one: the search then runs for 2 adults per room (1 room unless rooms says otherwise) and search_criteria.occupancy.source is "server_default". Tell the user the prices are for 2 adults in 1 room, and confirm the real party before trip(add_item), search again if it differs. A booking is priced for the party of the search.

TWO MODES, pick deliberately:

MODE A (rate lookup, the user named a specific hotel):
- { hotel_name }: free-text hotel name ("Hotel Calimala", "The St. Regis Rome", "Hôtel Costes"). The server matches the name against its hotel catalog. ALWAYS pair with country_code AND city_name when known, lookup precision drops sharply on common names without scope. Returns 422 HOTEL_NAME_LOW_CONFIDENCE if no candidate scores ≥ 0.7; see "ERROR HANDLING" below.
- { hotel_ids }: re-shop a known set (from a prior search result).
In Mode A: property filters (min_rating, min_star_rating, max_star_rating, min_reviews, hotel_type_ids, chain_ids, facility_ids) do not apply: the named hotel is priced as if they were not sent (the user named the property). The same holds when a query is read as one hotel (destination_resolution.shape hotel_name). filters.max_budget_per_night applies. filters.max_results does not limit Mode A: every named hotel that has rates is returned. The response includes nearby_alternatives, up to 40 hotels within ~3km of the matched property, in the same response shape so the user can compare.

MODE B (hotel search, the user is exploring a destination):
- { query }: a natural-language destination (city, POI, island or region). The platform parses it once into city + country or coordinates and applies shared location normalization; raw query text is never sent to a supplier.
- { city_name + country_code }: when the user named a city, even if ambiguous. Best when the destination has a primary city ("Mahón, ES" for Menorca; "Florence, IT" for Tuscany). Spell the city as an English-language booking site would, "Munich"/"Florence"/"Rome"/"Vienna", NOT "München"/"Firenze"/"Roma"/"Wien", but keep the local form where that IS the international one ("Regensburg", "Nürnberg", "Lyon"), and never an archaic exonym ("Leghorn", "Ratisbon"). When the user wrote the city in another language, translate it for this field only; keep their spelling when you talk back to them.
- { latitude + longitude + radius_km }: when exact coordinates and the desired area are already known; radius_km is the half-side of the square searched, up to 50.

ERROR HANDLING, 422 HOTEL_NAME_LOW_CONFIDENCE (Mode A only):
When { hotel_name } fuzzy lookup finds no candidate ≥ 0.7, the response body is:
  { "error": { "code": "HOTEL_NAME_LOW_CONFIDENCE", "message": "...", "top_candidates": [{hotel_id, name, city, score}], "suggested_retry": { "destination": {...} } } }
This is ACTIONABLE, not fatal. Pick one:
  1. Top candidate matches what the user meant (typo/spelling) → confirm with the user, then retry with { hotel_ids: ["<top.hotel_id>"] }.
  2. None of the candidates fit → ask the user "I couldn't pin down 'X', want me to search all hotels in <city> instead?" then retry with suggested_retry.destination.
  3. User likely meant a different city → ask to clarify, then retry hotel_name with corrected country_code/city_name.
Don't silently auto-pick a low-confidence candidate, booking the wrong hotel is worse than asking one clarifying question.

ERROR HANDLING, 422 DESTINATION_LOW_CONFIDENCE (Mode B city_name+country_code only):
When the city has no exact catalog match but close candidates exist, top_candidates are CITIES ({city, country_code, hotel_count, score}), not hotels: confirm an obvious typo and retry with that candidate's city_name + country_code (it resolves exactly), ask the user when several fit, and never report the city has no hotels.

destination_resolution comes back on every successful search and says HOW the destination resolved (exact / fuzzy / provider_matched / fallback_string); the text summary's opening "Searched: …" line, when present, means the match was fuzzy, fell back to a literal string, resolved to a different city than requested, or the platform located a place that is not a city (an island, region, district, landmark, station, address or airport). When destination_resolution.resolved_place is set, the platform located the place itself: tell the user that place, with its place_type when it is not a city, as where you searched. When destination_resolution.alternatives is set, the destination may name another place too (the same name in another country or state, the island rather than its town): name them, ask which one the user meant before booking, and search another by sending its latitude, longitude and radius_km.

SANITY-CHECK THE CITY GROUP (Mode B city_name, an "exact" match can still be the wrong group):
destination_resolution.catalog_hotel_count is how many properties the matched city group holds. A count in the single or low double digits for a city you would expect to be large does NOT mean the city is small, it means you matched a near-empty duplicate group. "Roma" holds 3 properties where "Rome" holds 20,706; "Firenze" holds 1 where "Florence" holds 6,986; "Wien" holds 7 where "Vienna" holds 4,580. Treat it as a DESTINATION problem: retry with the English-booking-site spelling, or with { latitude + longitude + radius_km }.
This overrides empty_reason. "no_availability_for_dates" is computed against the matched group alone, so a wrong-spelling match reports a sold-out city that actually has thousands of rooms, never tell the user a city is full, or that only N hotels exist there, on the strength of a small group.

FIRST SEARCH OPTIONAL:
- currency (ISO 4217), guest_nationality (ISO 3166-1 alpha-2)
- sort_by: "recommended" (default) or "lowest" (cheapest per night first). Mode B only.
- filters: { min_rating, min_star_rating, max_star_rating, min_reviews, hotel_type_ids, chain_ids, facility_ids, max_results, max_budget_per_night }
- filters.facility_ids / filters.hotel_type_ids take NAMES ("pool", "spa", "parking"; "hostel", "ryokan", "chalet"), the accepted names are listed on each parameter. For a facility the user requires, send that one name. A name outside the list is rejected with the accepted names. Every property filter of a destination search is applied as sent.
- filters.max_budget_per_night: per-night per-room price cap (request currency) for "under $150/night" asks. Hotels whose CHEAPEST rate fits are kept with ALL their rates, on every page. Also applies in Mode A.

DESTINATION AND OCCUPANCY EXAMPLES:
Add checkin and checkout for the user's actual stay to each example below.
1. Free-text city search:
   { "destination": { "query": "Paris" }, "adults": 2 }

2. Two-room family with kids:
   { "destination": { "city_name": "Barcelona", "country_code": "es" },
     "occupancies": [{ "adults": 2 }, { "adults": 1, "children_ages": [5, 7] }] }

3. Island/region with known coordinates:
   { "destination": { "latitude": 39.9496, "longitude": 4.1102, "radius_km": 30 }, "adults": 1 }

4. Geo-radius search around a POI:
   { "destination": { "latitude": 41.4036, "longitude": 2.1744, "radius_km": 3 }, "adults": 2 }

5. Mode A, user named a specific hotel:
   { "destination": { "hotel_name": "Hotel Calimala", "country_code": "it", "city_name": "Florence" }, "adults": 2, "currency": "EUR" }

RESPONSE:
- The text result is a summary, not JSON: hotels shown (with the total available when known), the price range and refundable split, then each hotel's stars, rating, cheapest price, rate count and hotel_id, and the rates an agent needs to choose a hotel: the cheapest rate of each board and refund-terms combination, cheapest first, one line per rate ending in trip_item_token=<htl_* token> with that rate's price, board and refund terms on the same line. A hotel's dearer rates at the same board and refund terms are not printed; a closing line counts them. Every rate, listed or not, is in structuredContent with its token.
- structuredContent carries the full payload: each hotel with basic metadata (name, address, star_rating, rating, main_photo), a rooms[] list of room metadata (room_id, room_name, description, max_occupancy; rates[] is empty) and the hotel's bookable rates, once each, in offers[]: each offer has a trip_item_token (the htl_* token), board type, refund policy, cancellation schedule, taxes, total_amount_money and room_rates[] naming the room it prices (room_id, room_name, occupancy_number, occupancy). On a search of 2 or more rooms each offer's room_rates[] names the room slot it prices, one token per room, the same token repeated for identical rooms, or, when one offer covers every room, every room it books with its one token.
- Order: hotels come in the order sort_by names, by default the hotel source's recommended order, or cheapest per night first with sort_by "lowest". Each hotel carries distance_km, its straight-line distance from the search center. When user_intent is given, hotels are re-ranked by how well each hotel matches the stated intent and carry recommendation_score (0 to 1; not a guest rating); the summary prints it on the hotel's "AI ranking" line. structuredContent also carries search metadata.
- structuredContent.search_criteria states what the prices were produced under, on every response (success, empty, error): destination (as sent, and resolved as the platform reported it), stay (checkin, checkout, nights), occupancy (rooms, adults, children_ages, source: request | server_default | session), currency (and whether it was defaulted), filters (requested, and as sent to the platform search, ids where the platform takes ids; every property filter of a destination search is applied as sent, and a named hotel's applied filters leave the property filters out), and on an empty page relax_first (what to change first, in order). The summary's "Priced for:" line repeats the party, currency and filters: read them back to the user with the prices.
- Empty page: do not repeat the same call. Change one thing per call in the order relax_first gives (the "Relax first:" line) before telling the user there is nothing.
- Short page: a "Coverage:" line says how many hotels have rates for the area and dates, e.g. 1 hotel. A short list is not a paging gap: widen the radius, shift the dates or try a nearby city. filters.offset is rejected once a search returned search_handle; page with next_handle instead.
- Error: the text names the retry policy, whether the SAME request is worth retrying once and after how many seconds (also structuredContent.retry_after_seconds when known), or whether the request has to change. One retry at most, never a loop; if it fails again, tell the user.

NEXT STEP: Use the trip tool with add_item and the trip_item_token (htl_* token) of the rate the user picks. Hotel items work alongside flight items in the same trip.

Flow: hotel_search → trip(add_item) → trip(upsert_travelers) → checkout

PRICES: rate prices, in the summary and in structuredContent, are totals for the stay.