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

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",
    "rooms": [
        {
            "adults": 2,
            "child": 1,
            "childAges": [3]
        }
    ]
}
'

Request

{
    "hotelCodes": [
        "sxk9hmwc2ty8",
        "sxk9jv7y87jw35"
    ],
    "checkIn": "2025-04-09",
    "checkOut": "2025-04-11",
    "clientNationality": "DE",
    "feedId": "5494e857-b13c-45ab-baa6-103aae65f30b",
    "rooms": [
        {
            "adults": 2,
            "child": 1,
            "childAges": [3]
        }
    ]
}

Response

{
    "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",
                    "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.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"
        }
    ]
}

Request Details

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.
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.

Response Details

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.
hotels/rooms/mealType	string	Yes	Meal type in Etstur structure.
hotels/rooms/mealTypeCode	string	Yes	Meal type code in Etstur structure.
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.