# Search hotels (/docs/api-reference/hotels/search)

`POST /v1/hotels/search`

Searches hotels by location or hotel IDs and returns their bookable rates for the stay.

Send `searchCriteria.location` or `searchCriteria.hotelIds`; a non-empty `hotelIds` wins and
`location` is then ignored. `checkIn`, `checkOut`, `rooms` and `guestNationality`
are required: rates are priced for the occupancy, child ages and guest market sent here. A stay longer than
30 nights returns 400 / 10001 with reason `MAX_STAY_EXCEEDED` at `checkOut`. The body rejects an
unknown member at every level, `filters`, `searchCriteria.location` and `rooms[]` included,
and the route takes no query parameters: either gives 400 / 10001.
            
Returns `{ items, pagination, nextCursor, details }`. Each item is a hotel: `id`, `name`,
`countryCode`, `category` (always null), `logoUrl` (the main image), `description`, its
`offers`, and `details` with the star rating, address, coordinates, images, amenity groups and
contact. Each offer is one rate: an opaque `publicId`, a `name` such as "Deluxe King, Breakfast,
Free cancellation", a `price` for the whole stay (all rooms and nights), and the rate terms in
`details`, including `expiresAt`. Pass an offer's
`publicId` to quote or order before it expires. The hotel's `id` is not an offer; send it in
`searchCriteria.hotelIds` to search that hotel again. A hotel without an orderable offer is not
listed. `details.availableFilters` holds the amenity filter values of a `cityCode` search.
            
Location searches are paged: `limit` is 1–50 (default 20) and the next page is requested by sending
the response's `nextCursor` back as `cursor` with the same body; a null `nextCursor` is the
last page. A page can hold fewer hotels than `limit`, even none, while `nextCursor` is not null:
keep paging until it is null. `pagination` is `{ currentCount, limit, hasMore }`: the walk states
no page number and no total. To keep pages small, each hotel on a page has one offer, its cheapest rate,
with empty `nightlyPrices` and `surcharges`, and no description and one image. A
`hotelIds` search returns every rate of those hotels with the full detail, as one complete page; an
empty `items` there means none of those hotels has an orderable offer.
            
Errors: an ID that is not a hotel ID returns 400 / 21000; an unknown or expired hotel ID 400 / 11004;
503 / 21003 when offers are temporarily unavailable (retry the search); 502, 504 or 503 with
21007–21009 when the hotel system fails, times out or is unavailable.

## Request body

- `application/json`: `HotelSearchRequest`
- `text/json`: `HotelSearchRequest`
- `application/*+json`: `HotelSearchRequest`

## Responses

### 200

OK

- `text/plain`: `HotelSearchResult`
- `application/json`: `HotelSearchResult`
- `text/json`: `HotelSearchResult`

### 400

Invalid partner request or model validation failure.

- `application/json`: `ErrorResponse`

### 429

Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.

- `application/json`: `ErrorResponse`

### 503

Service Unavailable

- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`

The full schemas are in the OpenAPI specification at /openapi.json.