Search

POST

/api/v1/generic-api-service/royal/hotel/search

The search endpoint is used to return a list of hotels suitable for a certain date range and number of people in a given destination.

curl --location 'https://test-api.etscore.com/api/v1/generic-api-service/royal/hotel/search' \
--header 'Accept-Language: en-US' \
--header 'X-Currency: EUR' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
    "hotelCodes": [
        "sxk9hmwc2ty8",
        "sxk9jv7y87jw35"
    ],
    "checkIn": "2025-04-09",
    "checkOut": "2025-04-11",
    "clientNationality": "DE",
    "feedId": "5494e857-b13c-45ab-baa6-103aae65f30b",
    "allPricesFlag": true,
    "rooms": [
        {
            "adults": 2,
            "child": 1,
            "childAges": [3]
        }
    ]
}
'

JSON

{

"totalHotelCount": 2,

"hotels": [

0: {

"hotelCode": "sxk9jv7y87jw35",

"hotelName": "Hilton İstanbul Kozyatağı",

"suggested": true,

"rooms": [

0: {

"pax": {

"adult": 2,

"child": 1,

"childAges": [

0: 3

]

"totalPrice": 222.13,

"nightlyPrices": [

0: {

"date": "2025-04-09",

"amount": 111.07,

"currency": "EUR"

1: {

"date": "2025-04-10",

"amount": 111.07,

"currency": "EUR"

}

"refundable": true,

"cancellationPolicies": [

0: {

"amount": 0,

"currency": "EUR",

"toDate": "2025-04-09T16:00:00",

"fromDate": "2025-03-13T14:30:21.641041"

1: {

"amount": 222.13,

"currency": "EUR",

"toDate": "2025-04-09T16:00:00",

"fromDate": "2025-04-09T16:00:00"

}

"roomType": "Twin, City View, ",

"roomCode": "4216",

"roomCapacity": 2,

"rateId": "71282",

"mealType": "Room Only",

"mealTypeCode": "RO",

"bedTypes": [

0: {

"id": 2714,

"name": "Double Bed"

}

"taxes": [

"fees": [

"restrictions": [

]

}

"destinationCodes": [

0: {

"id": 549,

"type": "COUNTRY",

"typeId": 0,

"name": "Türkiye"

1: {

"id": 740,

"type": "REGION",

"typeId": 0,

"name": "Marmara Bölgesi"

2: {

"id": 795,

"type": "CITY",

"typeId": 0,

"name": "İstanbul"

3: {

"id": 1303,

"type": "TOWN",

"typeId": 0,

"name": "İstanbul Anadolu Yakası"

4: {

"id": 328335,

"type": "CUSTOMREGION",

"typeId": 0,

"name": "Kadıköy"

}

"geoLocation": {

"lat": 40.9871309,

"lon": 29.0854914

"hotelRankingScore": 0,

"certificateNote": "Turizm İşletme Belgesi",

"certificateNumber": "12709"

1: {

"hotelCode": "sxk9hmwc2ty8",

"hotelName": "Pasaport Pier Otel Kadıköy",

"suggested": false,

"rooms": [

0: {

"pax": {

"adult": 2,

"child": 1,

"childAges": [

0: 3

]

"totalPrice": 110.44,

"nightlyPrices": [

0: {

"date": "2025-04-09",

"amount": 55.23,

"currency": "EUR"

1: {

"date": "2025-04-10",

"amount": 55.23,

"currency": "EUR"

}

"refundable": false,

"cancellationPolicies": [

"roomType": "Family , City View, ",

"roomCode": "72617",

"mealType": "Room Only",

"mealTypeCode": "RO",

"taxes": [

"fees": [

"restrictions": [

]

}

"destinationCodes": [

0: {

"id": 549,

"type": "COUNTRY",

"typeId": 0,

"name": "Türkiye"

1: {

"id": 740,

"type": "REGION",

"typeId": 0,

"name": "Marmara Bölgesi"

2: {

"id": 795,

"type": "CITY",

"typeId": 0,

"name": "İstanbul"

3: {

"id": 1303,

"type": "TOWN",

"typeId": 0,

"name": "İstanbul Anadolu Yakası"

4: {

"id": 328335,

"type": "CUSTOMREGION",

"typeId": 0,

"name": "Kadıköy"

}

"geoLocation": {

"lat": 40.987321,

"lon": 29.02419099999999

"hotelRankingScore": 0,

"certificateNote": "Basit Konaklama Belgesi",

"certificateNumber": "2022-34-0664"

}

]

}

Name	Type	Required	Description
hotelCodes	string-list	Yes	'hotelCodes' parameter enables a search for the hotel(s) to be searched. If a destination search is to be made, your destinations must be mapped with the Etstur structure, so that these hotels can be searched.
checkIn	string	Yes	'checkIn' parameter refers to the day of check-in to the hotel. It should be sent in the format 'yyyy-MM-dd'.
checkOut	string	Yes	'checkout' parameter refers to the day of departure from the hotel. It should be sent in yyyy-MM-dd format. The date to be sent in the checkout parameter must be after the date to be sent in the checkin parameter.
clientNationality	string	Yes	The country of the guests who will be included in the reservation. It must be sent as a 2-digit country code. If the reservation includes guests from more than one country, the country of the first guest of the reservation must be sent.
feedId	UUID	Yes	'feedId' parameter refers to pricetype(B2B,B2C). The unique feed ID provided must be submitted.
allPricesFlag	Boolean	No	Determines whether all available room prices or only the best available price will be returned for the hotel. If set to true, all room prices are returned. If set to false, only the best (lowest) price is returned. If the field is not provided, all room prices will be returned by default.
rooms	object-array	Yes	It is the information of the room to be reserved. Currently, only 1 room can be reserved per 1 reservation. When the multi-room feature is provided, it will be seen in the document.
rooms/adults	int	Yes	The number of adults that can be accommodated. It can take a value between 1 and X.
rooms/child	int	No	The number of children that can be accommodated. It can take a value between 1 and X.
rooms/childAges	int-array	No	If there are children in the reservation, age of the children must be sent. It can take values between 0 and X.

Name	Type	Required	Description
totalHotelCount	int	Yes	It is the number of hotels that return availability as a result of the search.
hotels	object-array	Yes	Information of the hotels with availability as a result of the search is returned with the Hotels object.
hotels/hotelCode	string	Yes	Hotel code returned as a result of the search is displayed with the 'hotelCode' parameter.
hotels/hotelName	string	Yes	Hotel name returned as a result of the search is displayed with the 'hotelName' parameter.
hotels/destinations	object-array	Yes	The destinations where the hotel is located are placed in the 'destinationCode' object.
hotels/destinations/id	int	Yes	Destination id in Etstur structure.
hotels/destinations/type	string	Yes	Destination type in Etstur structure.
hotels/destinations/typeId	int	Yes	Destination typeId in Etstur structure.
hotels/destinations/name	string	Yes	Destination name in Etstur structure.
hotels/currency	string	Yes
hotels/rooms	object-array	Yes	Information about the cheapest room of the hotel is returned with the 'Rooms' object.
hotels/rooms/pax	object-array	Yes	Information about the guests in the room.
hotels/rooms/pax/adult	int	Yes	The number of adults that can be accommodated.
hotels/rooms/pax/child	int	No	The number of children that can be accommodated.
hotels/rooms/pax/childAges	int-array	No	If there are children in the reservation, age of the children must be sent.
hotels/rooms/totalPrice	decimal	Yes	Total price of the room.
hotels/rooms/nightlyPrices	object-array	Yes	An object that allows the room's nightly prices to be displayed separately and Price must be big decimal type.
hotels/rooms/nightlyPrices/date	string	Yes	Date of the day, date format must be yyyy-MM-dd
hotels/rooms/nightlyPrices/amount	decimal	Yes	Price amount of the day
hotels/rooms/nightlyPrices/currency	string	Yes	Information in which currency the reservation amount is in is returned with the 'currency' parameter.
hotels/rooms/roomType	string	Yes	Room type in Etstur structure.
hotels/rooms/roomCode	string	Yes	Room code in Etstur structure. This value is unique within the context of a specific hotel but is not globally unique across all hotels.
hotels/rooms/roomCapacity	Int	No	Indicates the total number of guests (both adults and children) that can be accommodated in the room.
hotels/rooms/rateId	Int	No	Unique identifier of the rate associated with the room.This field may not be returned in all responses.
hotels/rooms/mealType	string	Yes	Meal type in Etstur structure.
hotels/rooms/mealTypeCode	string	Yes	Meal type code in Etstur structure.
hotels/rooms/bedTypes	Object-Array	No	List of bed types available in the room.
hotels/rooms/bedTypes/id	Int	No	Unique identifier of the bed type.
hotels/rooms/bedTypes/name	String	No	Name of the bed type (e.g., Double Bed, Twin Bed)
hotels/rooms/taxes	object-array	No	If there is a tax related to accommodation, it will be included in this field.
hotels/rooms/taxes/type	string	No	Tax type
hotels/rooms/taxes/price	decimal	No	Tax amount
hotels/rooms/taxes/currency	string	No	Tax currency
hotels/rooms/taxes/description	string	No	Tax description
hotels/rooms/taxes/included	boolean	No	Information whether the tax price is included in the total amount. Included if it is True and not included if it is False.
hotels/rooms/fees	object-array	No	If there is an extra fee related to accommodation, it will be included in this field.
hotels/rooms/fees/type	string	No	Fee type
hotels/rooms/fees/price	decimal	No	Fee amount
hotels/rooms/fees/currency	string	No	Fee currency
hotels/rooms/fees/description	string	No	Fee description
hotels/rooms/fees/included	boolean	No	Information whether the extra fee is included in the total amount. Included if it is True and not included if it is False.
hotels/rooms/refundable	boolean	Yes	Information about whether the reservation is cancelled. Refundable if it is True, nonrefundable if it is False.
hotels/geoLocation/lat	decimal	Yes	Latitude information of hotel.
hotels/geoLocation/lon	decimal	Yes	Longitude information of hotel.

Errors specific to this endpoint (55 codes). Gateway and authentication errors apply to every endpoint and are listed in the Error Codes reference.

ValidationThe request is missing a required field, contains an invalid value or breaks a business rule.

Group	Code	Message	Description
Validation	0904055	No parameter found !	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904056	Hotel code parameter and url cannot be empty, please enter valid limit value.	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904057	Room request parameters cannot be empty, please enter valid request value.	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904058	Check-in parameter cannot be empty, please enter valid check-in value.	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904059	Check-out parameter cannot be empty, please enter valid check-out value.	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904060	Check-in check-out parameters are not valid, please enter valid range	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904061	Adult count cannot be empty, please enter valid adult count value.	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904062	Adult count parameter can be min 1 and max 10, please enter valid value.	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904063	Child count cannot be empty, please enter valid child count value.	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904064	Child count parameter can be min 0 and max 4, please enter valid value.	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904065	If child count is not empty, child ages cannot be empty, please enter valid value(s).	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904066	Value cannot be negative.	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904067	Children count and child ages are not matched.	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904068	Any child age cannot be {0} or older , please enter valid value(s). Child ages:{1}	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904069	Infant count parameter can be min 0 and max 2, please enter valid value.	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904070	Hotel id list and url cannot be empty.	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904071	Client nationality cannot be empty, please enter valid value.	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904072	Client nationality must be two character code of country.	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904073	Checkin and Checkout date range cannot be greater than {0} days.	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904079	Transactions cannot be made with undefined currency information.	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904093	The channel type defined for the given feed could not be found.	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904094	The sales type defined for the given feed could not be found.	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904095	The channel type defined in the feed and the API channel type are incompatible.	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904096	Sales channel has been deleted or its status is inactive.	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904098	Hotel search id information cannot be empty.	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904099	FeedId cannot be empty.	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904131	The feed is not active.	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904158	Paxes field cannot be empty, please enter a valid value.	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904161	Hotel code cannot exceed 50 characters: {0}	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904162	Minimum room count must be at least {0}.	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904163	Maximum room count cannot be more than {0}.	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904166	Hotel codes cannot be null !	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904168	Hotel codes size must be between {0} and {1} !	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904185	Location id information cannot be empty.	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904186	Hotel limit parameter cannot be empty, please enter valid limit value.	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904187	Hotel offset parameter cannot be empty, please enter valid offset value.	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904203	Provided hotel codes are invalid. Please enter valid hotel codes.	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.
Validation	0904230	The feed generated for hotel searches for rotation purposes cannot be used.	Returned during a hotel Search request when the request contains missing or invalid data or breaks a business rule. Fix the request using the message details and send it again. Retrying the same request will fail again.

No availabilityThe request is valid, but no hotels, rooms or results match the given criteria.

Group	Code	Message	Description
No availability	0904074	There is no hotel founded by the given location parameters.	Returned during a hotel Search request when no results match the given criteria. Not a failure. Inform the user and try different dates, occupancy or destination.
No availability	0904075	No hotel found for the given dates.	Returned during a hotel Search request when no results match the given criteria. Not a failure. Inform the user and try different dates, occupancy or destination.
No availability	0904076	There is no availability on the requested dates due to hotel restrictions.	Returned during a hotel Search request when no results match the given criteria. Not a failure. Inform the user and try different dates, occupancy or destination.
No availability	0904077	There is no availability at a hotel that matches your search criteria.	Returned during a hotel Search request when no results match the given criteria. Not a failure. Inform the user and try different dates, occupancy or destination.
No availability	0904100	As a result of the search, no hotel available for sale was found.	Returned during a hotel Search request when no results match the given criteria. Not a failure. Inform the user and try different dates, occupancy or destination.
No availability	0904152	Hotel search response from etsrooms was not found.	Returned during a hotel Search request when no results match the given criteria. Not a failure. Inform the user and try different dates, occupancy or destination.
No availability	0904153	Content suggestion response was not found.	Returned during a hotel Search request when no results match the given criteria. Not a failure. Inform the user and try different dates, occupancy or destination.
No availability	0904154	Hotel search content response was not found.	Returned during a hotel Search request when no results match the given criteria. Not a failure. Inform the user and try different dates, occupancy or destination.
No availability	0904155	No hotels found due to provider restrictions.	Returned during a hotel Search request when no results match the given criteria. Not a failure. Inform the user and try different dates, occupancy or destination.
No availability	0904156	No hotels found due to restrictions applied before search.	Returned during a hotel Search request when no results match the given criteria. Not a failure. Inform the user and try different dates, occupancy or destination.

Not foundThe referenced record (hotel, reservation, feed, search id, etc.) could not be found.

Group	Code	Message	Description
Not found	0904054	Hotel search request not found.	Returned during a hotel Search request when the referenced record cannot be found. Verify the identifier you sent, or repeat the previous step to obtain a fresh one.
Not found	0904097	Invalid feed ID provided. Please check and try again.	Returned during a hotel Search request when the referenced record cannot be found. Verify the identifier you sent, or repeat the previous step to obtain a fresh one.
Not found	0904167	Hotel codes not found !	Returned during a hotel Search request when the referenced record cannot be found. Verify the identifier you sent, or repeat the previous step to obtain a fresh one.
Not found	0904172	There is no provider country definition in the searched hotels.	Returned during a hotel Search request when the referenced record cannot be found. Verify the identifier you sent, or repeat the previous step to obtain a fresh one.
Not found	0904184	No matching provider found for the hotel search.	Returned during a hotel Search request when the referenced record cannot be found. Verify the identifier you sent, or repeat the previous step to obtain a fresh one.

AuthThe bearer token is missing, invalid or expired, or the account is not authorized for the operation.

Group	Code	Message	Description
Auth	0904078	Transactions cannot be made with test hotels.	Returned during a hotel Search request when the request is not properly authenticated or authorized. Get a new token from the Authentication endpoint and check the Authorization header. Contact Etscore if access is still denied.

SystemAn unexpected server-side or upstream provider problem occurred.

Group	Code	Message	Description
System	0904053	Hotel list cannot be fetched from etsrooms.	Returned during a hotel Search request when an unexpected server-side or provider-side problem occurs. Retry with exponential backoff. If it persists, contact Etscore support with the error code and request time.

Error groups

Group	Meaning	Recommended action
Validation	The request is missing a required field, contains an invalid value or breaks a business rule.	Fix the request using the message details and send it again. Retrying the same request will fail again.
No availability	The request is valid, but no hotels, rooms or results match the given criteria.	Not a failure. Inform the user and try different dates, occupancy or destination.
Not found	The referenced record (hotel, reservation, feed, search id, etc.) could not be found.	Verify the identifier you sent, or repeat the previous step to obtain a fresh one.
Auth	The bearer token is missing, invalid or expired, or the account is not authorized for the operation.	Get a new token from the Authentication endpoint and check the Authorization header. Contact Etscore if access is still denied.
System	An unexpected server-side or upstream provider problem occurred.	Retry with exponential backoff. If it persists, contact Etscore support with the error code and request time.