Skip to main content
POST
Hotel search

Authorizations

x-api-key
string
header
required

Body

application/json

Hotel search request: places to stay in a location for a date range.

location
string
required

Where to stay: a city, neighborhood, landmark or address.

Required string length: 2 - 200
Examples:

"Lisbon"

"Shinjuku, Tokyo"

"near the Eiffel Tower"

check_in_date
string<date>
required

Check-in date, YYYY-MM-DD. Must not have passed.

check_out_date
string<date>
required

Check-out date, YYYY-MM-DD. At most 30 nights after check_in_date.

adults
integer
default:2

Adult guests.

Required range: 1 <= x <= 16
children_ages
integer[]

Age of each child guest, 0 to 17.

Maximum array length: 8
Required range: 0 <= x <= 17
rooms
integer
default:1

Rooms to book. Each room needs an adult. fast searches one room only.

Required range: 1 <= x <= 8
property_types
enum<string>[]

hotel (hotels, hostels, inns) and vacation_rental (homes and apartments). Defaults to both.

Minimum array length: 1
Available options:
hotel,
vacation_rental
min_price
number | null

Lowest nightly price, before taxes and fees, in currency.

Required range: x >= 0
max_price
number | null

Highest nightly price, before taxes and fees, in currency.

Required range: x > 0
min_rating
number | null

Lowest guest rating, out of 5. Properties without a rating are left out.

Required range: 1 <= x <= 5
hotel_classes
integer[]

Hotel star classes to keep, 1 to 5. Properties without a class are left out.

Maximum array length: 5
Required range: 1 <= x <= 5
free_cancellation
boolean
default:false

Only offers that state free cancellation.

sort
enum<string>
default:relevance

relevance (default), price (lowest nightly price first) or rating (highest first).

Available options:
relevance,
price,
rating
currency
string
default:USD

ISO 4217 currency of prices and price filters.

Pattern: ^[A-Za-z]{3}$
Examples:

"USD"

"EUR"

"JPY"

mode
enum<string> | null

advanced (default): many sources and offers.

Available options:
advanced
session_id
string | null

Session identifier that groups related calls made as part of a larger task. Echoed back in the response when nonempty; generated by the server if omitted, null, or empty.

Maximum string length: 1000
client_model
string | null

The model generating this request and consuming the results.

Example:

"claude-opus-4-7"

advanced_settings
AdvancedVerticalSearchSettings · object | null

Advanced configuration for result count.

Response

Successful Response

Hotel search response.

search_id
string
required

Search ID. Example: search_cad0a6d2dec046bd95ae900527d880e7

session_id
string
required

Session identifier, echoed back from the request when nonempty; otherwise generated by the server. Pass it to later calls made as part of the same task.

Example:

"session_8a911eb27c7a4afaa20d0d9dc98d07c0"

results
HotelSearchResult · object[]
required

Places to stay, in the order sort asks for.

warnings
Warning · object[] | null

Warnings for the search request, if any.

usage
UsageItem · object[] | null

Usage metrics for the search request.