Hotel Search

Search live hotel inventory and nightly rates for a destination and stay window. It handles requests like “three nights in Lisbon next weekend for two adults” or “family room in Rome with one child in August”. Each result includes an htl_* offer token you can hand to the trip tool to start a booking.

Tool description (what the LLM sees)

Search live hotel inventory and rates.

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 }, { latitude + longitude (+ radius_km) }, or { place_id }.
- checkin, checkout: YYYY-MM-DD
- occupancy: either { occupancies: [{ adults, children_ages? }, ...] } (one entry per room) OR shorthand { adults, children?, rooms? }

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"). Server fuzzy-matches against a 1.74M-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: filters are ignored (user named the property), and the response includes nearby_alternatives, up to 5 hotels within ~2km 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 }: unambiguous cities or well-known POIs only ("Paris", "Times Square"). Provider AI search returns 0 for islands ("Menorca", "Santorini", "Mykonos"), regions ("Tuscany", "Provence", "Bavaria"), countries, archipelagos. Do NOT use { query } for those.
- { 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).
- { latitude + longitude + radius_km }: when the destination is an area, island, or region with no obvious primary city. radius_km up to 50.
- { place_id }: when you already have an upstream Place ID.
If the user names something non-city (an island, region, archipelago, neighborhood), DO NOT pass it as { query }, pick { city_name+country_code } or { latitude+longitude+radius_km }.

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.

OPTIONAL:
- currency (ISO 4217), guest_nationality (ISO 3166-1 alpha-2)
- 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.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; the search scans deeper automatically when few fit. Also applies in Mode A. Prefer it over post-filtering results yourself.

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. Island/region (use lat-lng + radius, NOT query):
   { "destination": { "latitude": 39.9496, "longitude": 4.1102, "radius_km": 30 }, "checkin": "2026-08-31", "checkout": "2026-09-09", "adults": 1 }

4. 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 }

5. Mode A, user named a specific hotel:
   { "destination": { "hotel_name": "Hotel Calimala", "country_code": "it", "city_name": "Florence" }, "checkin": "2026-07-15", "checkout": "2026-07-18", "adults": 2, "currency": "EUR" }

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) → checkout

PRICES: all monetary fields (rates[].total_amount, taxes_breakdown[].amount, cancellation_schedule[].amount) are already decimals in major units, display as-is, do NOT divide.

Parameters

Name	Type	Required	Description
`destination`	`object`	Yes	Destination, provide exactly one shape. Two distinct modes: MODE A (rate lookup, you know which hotel): • { hotel_ids } to re-shop a known set. • { hotel_name, country_code?, city_name? } when the user named a specific property. Server resolves via fuzzy lookup; returns 422 HOTEL_NAME_LOW_CONFIDENCE if no candidate scores ≥ 0.7. MODE B (hotel search, you’re exploring): • { query } for unambiguous cities/POIs only (“Paris”, “Times Square”). Provider AI search returns 0 for islands/regions/countries/archipelagos. • { city_name + country_code } for ambiguous city names or when the user named a primary city (“Mahón, ES” for Menorca). • { latitude + longitude + radius_km } for islands, regions, neighborhoods, anywhere { query } returns 0. • { place_id } when you already have an upstream Place ID. In Mode A, filters (min_rating / star / facility / chain / hotel_type / max_results) are ignored, the user already named the property. Best practice: don’t combine filters with hotel_ids or hotel_name.
`destination.query`	`string`	No	Free-text destination, use ONLY for unambiguous cities or well-known POIs (e.g. “Paris”, “Times Square”). Provider-side AI search reliably returns 0 results for islands (“Menorca”, “Santorini”), regions (“Tuscany”, “Provence”), countries, archipelagos, and other non-city geographies. For those: prefer { city_name + country_code } when a primary city is implied (e.g. “Mahón, ES” for Menorca), or { latitude + longitude + radius_km } to cover an area. Max 200 chars.
`destination.city_name`	`string`	No	City name (e.g. “Paris”). In Mode B: pair with country_code as the destination. In Mode A (with hotel_name): pair with hotel_name to narrow the fuzzy-lookup scope.
`destination.country_code`	`string`	No	ISO 3166-1 alpha-2 country code (lowercase preferred, e.g. “fr”). Must be paired with city_name OR hotel_name. In Mode B it disambiguates the city; in Mode A it narrows the fuzzy lookup.
`destination.latitude`	`number`	No	Latitude for geo-radius search. Pair with longitude.
`destination.longitude`	`number`	No	Longitude for geo-radius search. Pair with latitude.
`destination.radius_km`	`number`	No	Geo-radius in km (default 5, max 50). Requires latitude+longitude, ignored with other destination shapes.
`destination.place_id`	`string`	No	Google Places ID or upstream place identifier.
`destination.hotel_ids`	`array<string>`	No	Mode A, re-shop a known set of hotel IDs (skips destination resolution).
`destination.hotel_name`	`string`	No	Mode A, free-text hotel name when the user named a specific property they want to book (e.g. “Hotel Calimala”, “The St. Regis Rome”, “Hôtel Costes”). Server runs a fuzzy trigram match over the 1.74M-hotel catalog; uses the top hit when its confidence is ≥ 0.7 (auto-pick safe). If no candidate clears that threshold, returns HTTP 422 with error.code = HOTEL_NAME_LOW_CONFIDENCE + top_candidates + suggested_retry, the agent should confirm a candidate with the user or fall back to the suggested city destination. ALWAYS pair with country_code and city_name when known; lookup precision drops sharply on common names without scope.
`checkin`	`string`	Yes	Check-in date (YYYY-MM-DD).
`checkout`	`string`	Yes	Check-out date (YYYY-MM-DD).
`occupancies`	`array<object>`	No	One entry per room (structured). PREFERRED whenever the party is larger than 2 adults or has children, it removes ambiguity about how guests are split across rooms. Example: [{ “adults”: 2 }, { “adults”: 1, “children_ages”: [5] }]. Do NOT combine with the shorthand fields (adults/children/rooms), use one or the other.
`occupancies[].adults`	`integer`	Yes	Adult travelers in this room (12+).
`occupancies[].children_ages`	`array<integer>`	No	Ages of children in this room (0-17). Required for child pricing.
`adults`	`integer`	No	Shorthand: total adults across all rooms. Use ONLY when there is no ambiguity (1 or 2 adults = single room). For 3+ adults, or odd splits, ask the user how they want to split rooms and pass occupancies[] instead, e.g. 4 adults → [{adults:2},{adults:2}] (double + double) vs a single 4-sleeper is a meaningfully different search. If the user does not clarify, the server defaults to 2-adults-per-room (remainder in the last room), so every 4-adult request becomes two double rooms. Do NOT combine with occupancies[], use one or the other.
`children`	`array<integer>`	No	Shorthand: ages of all children across all rooms. If children are present, prefer occupancies[] so the caller controls which room each child goes in (ages affect pricing and some providers reject invalid age/room combinations).
`rooms`	`integer`	No	Shorthand: number of rooms (BFF auto-distributes adults + children). Use when the user named a room count but not the per-room split.
`currency`	`string`	No	ISO 4217 currency code (e.g. “EUR”, “USD”, “GBP”, “JPY”). ALWAYS set this, omitting it falls back to USD which is rarely what users actually want. Infer from the strongest signal available: (1) the user’s explicit ask (“show me prices in pounds”), (2) the conversation language/locale (French → EUR, Japanese → JPY, German → EUR, Spanish/Catalan/Italian/Portuguese → EUR, English UK → GBP, English US → USD), (3) the destination country (Italy/France/Germany → EUR, UK → GBP, Japan → JPY, US → USD). When in doubt between two plausible currencies, prefer the one matching the user’s likely home country.
`guest_nationality`	`string`	No	Guest nationality (ISO 3166-1 alpha-2, uppercase, e.g. “FR”). Affects rate availability + tax handling at search time. Separate from traveler nationality used for booking documents.
`filters`	`object`	No	Optional filter overrides applied on top of the tenant default filter set.
`filters.min_rating`	`number`	No	Minimum guest review rating (0-10 scale).
`filters.min_star_rating`	`integer`	No	Minimum star rating (1-5). Pair with max_star_rating to bound a range.
`filters.max_star_rating`	`integer`	No	Maximum star rating (1-5). Pair with min_star_rating to bound a range.
`filters.min_reviews`	`integer`	No	Minimum number of guest reviews.
`filters.hotel_type_ids`	`array<string>`	No	Filter by hotel type IDs (e.g. boutique, resort).
`filters.chain_ids`	`array<string>`	No	Filter by hotel chain. Each entry is a brand slug (e.g. “accor”, “hilton”) OR a numeric LiteAPI chain_id. Slugs are expanded to all sub-brands (e.g. “accor” → Accor, ibis, Novotel, Mercure, Pullman, Sofitel, …). Unknown brands are ignored (the search still runs).
`filters.facility_ids`	`array<string>`	No	Filter by facility IDs (e.g. pool, gym, spa). Applied at connector search time, not post-filtered.
`filters.max_results`	`integer`	No	Maximum number of hotels to return per page (default 50).
`filters.offset`	`integer`	No	Pagination offset, skip this many hotels at the upstream search (default 0).
`filters.max_budget_per_night`	`number`	No	Keep only hotels whose CHEAPEST per-night price (per room, in the request currency) fits this budget; qualifying hotels keep all their rates. The search automatically scans deeper into the catalog when too few hotels fit. Also applies in Mode A (rate lookup). Prefer a larger max_results over offset paging when set.
`trip_id`	`string`	No	Existing trip_id to associate this search with. Unified (cart-widget) tool only, the DevPlatform variant accepts the field for schema consistency but ignores it (no widget surface). Forward whenever the user is mid-trip-build (you have seen a trip_id in a recent trip(…) tool result and the user has NOT pivoted to a different trip context, e.g. a new origin OR destination city or unrelated request). Drop on pivot. Echoed back in the result so the cart widget can append the next selection to the same trip.
`user_intent`	`string`	No	The end user’s current request in their own words, e.g. “find a cheap flight to Tokyo in mid-June”. Pass it as-is when short; otherwise condense the goal and constraints into 1-2 sentences. Strip personal identifiers (names, emails, phone numbers, addresses, payment details), replace them with placeholders like “[name]”. Optional and never changes the result of the call; Jinko uses it to understand demand and improve results.

Examples

Simple city search, 2 adults, 3 nights in Paris:

{
  "name": "hotel_search",
  "arguments": {
    "destination": { "query": "Paris" },
    "checkin": "2026-07-15",
    "checkout": "2026-07-18",
    "adults": 2
  }
}

Two rooms, kids in one:

{
  "name": "hotel_search",
  "arguments": {
    "destination": { "city_name": "Barcelona", "country_code": "ES" },
    "checkin": "2026-08-01",
    "checkout": "2026-08-05",
    "occupancies": [
      { "adults": 2 },
      { "adults": 1, "children_ages": [5, 7] }
    ]
  }
}

Near a coordinate with filters:

{
  "name": "hotel_search",
  "arguments": {
    "destination": {
      "latitude": 48.8566,
      "longitude": 2.3522,
      "radius_km": 3
    },
    "checkin": "2026-07-15",
    "checkout": "2026-07-18",
    "adults": 2,
    "filters": {
      "min_rating": 8,
      "min_star_rating": 4,
      "facility_ids": ["pool", "wifi"],
      "max_results": 20
    }
  }
}

Each hotel’s rooms[].rates[] includes a offer_id starting with htl_. Pass it as a trip_item_token to trip(add_item), hotels coexist with flight items in the same trip.

Introduction

Flights

Hotels

Cart & Payment

Parameters

Examples

​Parameters

​Examples

Parameters

Examples