POST/v1/hotels/search

Search available hotels

Searches available hotels by location, dates, occupancy and commercial filters, then applies company-level pricing rules.

Endpoint

Method	Path	Auth
`POST`	`/v1/hotels/search`	Required API key

Required headers:

Header	Description
`Authorization`	`Bearer <secret_key>`. The secret is shown only once when the credential is created.
`X-Travelandz-Id`	`<public_key>:<profile_code>`. The `profile_code` is the `dp_`-prefixed Developer Profile code shown in your dashboard. This binds the request to a profile and credential.
`Content-Type`	Use `application/json` for requests with a body.

Property	Type	Details	Required	Notes
`language`	`enum`	`en`, `es`, `zh`	No	Default en
`checkIn`	`string`	`Format: YYYY-MM-DD`	Yes	-
`checkOut`	`string`	`Format: YYYY-MM-DD`	Yes	-
`location`	`object`		Yes	-
`searchBy`	`enum`	`coords`	Yes	-
`latitude`	`number`		Yes	-
`longitude`	`number`		Yes	-
`searchRadius`	`number`		No	Minimum value: 1
`countryCode`	`string`	`Format: 2 digits`	Yes	-
`nationality`	`string`	`Format: 2 digits`	Yes	-
`maxHotels`	`number`		No	Maximum value: 2000
`minRate`	`number`		No	-
`maxRate`	`number`		No	-
`minCategory`	`enum`	`1`, `2`, `3`, `4`, `5`	No	-
`maxCategory`	`enum`	`1`, `2`, `3`, `4`, `5`	No	-
`refundable`	`enum`	`all`, `refundable`, `non-refundable`	Yes	-
`rooms`	`array`		Yes	-
`adults`	`number`		Yes	Minimum value: 1, Maximum value: 4
`children`	`number`		No	Minimum value: 0, Maximum value: 4
`childrenAges`	`array`		Yes	-
`childrenAges[]`	`number[]`		Yes	-

`currency`	`enum`	`EUR`, `USD`, `CNY`	No	Default EUR
`retrieveBookingLink`	`boolean`		No	Default false

Returns hotel results, availability, min rates and optional booking links.

Property	Type	Details	Required	Notes
`hotels`	`array`		Yes	-
`gdsprovider`	`number`		Yes	-
`offerLink`	`string`		No	-
`hotelId`	`string`		Yes	-
`code`	`string`		Yes	-
`name`	`string`		Yes	-
`description`	`object`		Yes	-
`lang`	`enum`	`en`, `es`, `zh`	Yes	-
`description`	`string`		Yes	-
`starRating`	`number`		Yes	-
`reviewCount`	`number`		No	-
`accommodationType`	`string`		Yes	-
`chain`	`string`		Nullable	-
`address`	`object`		Yes	-
`street`	`string`		No	-
`countryCode`	`string`		No	-
`country`	`string`		No	-
`destination`	`string`		No	-
`zone`	`string`		No	-
`location`	`object`		Yes	-
`type`	`string`		Yes	-
`coordinates`	`array`		Yes	-
`coordinates[]`	`number[]`	`Format: [longitude, latitude]`	Yes	-

`latitude`	`number`		Yes	-
`longitude`	`number`		Yes	-
`roomsNames`	`array`		Yes	-
`roomsNames[]`	`string[]`		Yes	-

`boardTypes`	`array`		Yes	-
`boardTypes[]`	`string[]`		Yes	-

`hasRefundableRooms`	`boolean`		Yes	-
`images`	`array`		Yes	-
`images[]`	`string[]`		Yes	-

`amenities`	`array`		Yes	-
`amenities[]`	`string[]`		Yes	-

`minPrice`	`number`		Yes	-
`roomCount`	`number`		No	-