Skip to main content
POST
Search live hotel inventory and rates
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.
Read hotel prices from the *_money fields. rates[].total_amount_money, taxes_breakdown[].amount_money and cancellation_schedule[].amount_money carry value in minor units with its decimal_places, the same shape as every other money field: divide value by 10 ** decimal_places, or show display. A cancellation step expressed as a percentage or a number of nights carries percent or nights instead. The older total_amount, amount and currency fields are deprecated and hold major units. A room’s capacity is room_capacity; the deprecated max_occupancy repeats the requested occupancy. See Money & prices.

Authorizations

​
X-API-Key
string
header
required

Body

application/json
​
next_handle
string
required

Opaque continuation handle returned by a prior hotel_search. Send this field by itself; the search session keeps destination, dates, occupancy, currency and filters.

Minimum string length: 1
Example:

"hp_example_2"

Response

Matching hotels

​
hotels
object[]
​
nearby_alternatives
object[]

Other hotels near the one a hotel_name search matched, priced for the same dates and occupancy, so they can be compared without a second search. Same shape as hotels, and not counted in total. Present only on a hotel_name search that found usable neighbours.

​
total
number
Example:

87

​
search_handle
string
deprecated

Deprecated: use next_handle instead. The identifier of the search session on its own, which no endpoint accepts. next_handle carries the session and the next page, has_more says whether there is one and expires_at when the session ends.

Example:

"hs_example"

​
next_handle
string | null

Opaque handle for the next page. Send it by itself to hotel_search. The next page serves the hotels this answer held, then asks the hotel source for the next ones, and widens a city or default radius when its area has none left. Null means the search has nothing left.

Example:

"hp_example_2"

​
has_more
boolean

Whether this fixed search session has another page.

​
expires_at
string<date-time>

RFC 3339 expiry for the search session and its page handles.

Example:

"2027-01-15T10:30:00Z"

​
search_context
object

Normalized first-request stay and occupancy frozen by the search session and repeated on every page. trip_id only associates the search with a trip for display.

​
warnings
string[]

Non-fatal advisories, e.g. budget-filter outcomes or ignored filters.

​
destination_resolution
object

How the request’s destination resolved into these hotels. Present on every successful search. Rendering rule for an agent or tool: say something ONLY when there is something to say — match is fuzzy or fallback_string, resolved_city differs from requested_city, or the platform located a place that is not a city (place_type other than city), or alternatives is present. exact and provider_matched otherwise need no header line of their own. When resolved_place is present, name it as the place searched, with place_type when it is not a city, instead of resolved_city. When alternatives is present, name them too and let the user pick before booking.

​
empty_reason
enum<string>

Why hotels is empty. Absent whenever hotels is non-empty.

Available options:
no_availability_for_dates,
destination_not_found,
catalog_exhausted,
all_dropped_by_budget,
no_catalog_match,
all_dropped_by_star_filter,
all_dropped_by_rating_filter
Example:

"no_availability_for_dates"