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
- Request
- Response
- Request Details
- Response Details
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]
}
]
}
'
{
"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]
}
]
}
{
"totalHotelCount": 2,
"hotels": [
{
"hotelCode": "sxk9jv7y87jw35",
"hotelName": "Hilton İstanbul Kozyatağı",
"suggested": true,
"rooms": [
{
"pax": {
"adult": 2,
"child": 1,
"childAges": [
3
]
},
"totalPrice": 222.13,
"nightlyPrices": [
{
"date": "2025-04-09",
"amount": 111.07,
"currency": "EUR"
},
{
"date": "2025-04-10",
"amount": 111.07,
"currency": "EUR"
}
],
"refundable": true,
"cancellationPolicies": [
{
"amount": 0,
"currency": "EUR",
"toDate": "2025-04-09T16:00:00",
"fromDate": "2025-03-13T14:30:21.641041"
},
{
"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": [
{
"id": 2714,
"name": "Double Bed"
}
],
"taxes": [],
"fees": [],
"restrictions": []
}
],
"destinationCodes": [
{
"id": 549,
"type": "COUNTRY",
"typeId": 0,
"name": "Türkiye"
},
{
"id": 740,
"type": "REGION",
"typeId": 0,
"name": "Marmara Bölgesi"
},
{
"id": 795,
"type": "CITY",
"typeId": 0,
"name": "İstanbul"
},
{
"id": 1303,
"type": "TOWN",
"typeId": 0,
"name": "İstanbul Anadolu Yakası"
},
{
"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"
},
{
"hotelCode": "sxk9hmwc2ty8",
"hotelName": "Pasaport Pier Otel Kadıköy",
"suggested": false,
"rooms": [
{
"pax": {
"adult": 2,
"child": 1,
"childAges": [
3
]
},
"totalPrice": 110.44,
"nightlyPrices": [
{
"date": "2025-04-09",
"amount": 55.23,
"currency": "EUR"
},
{
"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": [
{
"id": 549,
"type": "COUNTRY",
"typeId": 0,
"name": "Türkiye"
},
{
"id": 740,
"type": "REGION",
"typeId": 0,
"name": "Marmara Bölgesi"
},
{
"id": 795,
"type": "CITY",
"typeId": 0,
"name": "İstanbul"
},
{
"id": 1303,
"type": "TOWN",
"typeId": 0,
"name": "İstanbul Anadolu Yakası"
},
{
"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. |