Room Search
POST
/api/v1/generic-api-service/royal/room/search
The room search endpoint is used to display information about the hotel's available rooms that are listed in the hotels list.
- cURL
- Request
- Response
- Request Details
- Response Details
- Errors
curl --location 'https://test-api.etscore.com/api/v1/generic-api-service/royal/room/search' \
--header 'Accept-Language: en-EN' \
--header 'X-Currency: EUR' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
"hotelCode": "sxk9jv7y87jw35",
"checkIn": "2025-04-09",
"checkOut": "2025-04-11",
"feedId": "5494e857-b13c-45ab-baa6-103aae65f30b",
"clientNationality": "DE",
"rooms": [
{
"adults": 2,
"child": 1,
"childAges": [3]
}
]
}
'
{
"hotelCode": "sxk9jv7y87jw35",
"checkIn": "2025-04-09",
"checkOut": "2025-04-11",
"feedId": "5494e857-b13c-45ab-baa6-103aae65f30b",
"clientNationality": "DE",
"rooms": [
0: {
"adults": 2,
"child": 1,
"childAges": [
0: 3
]
}
]
}
{
"hotelCode": "sxk9jv7y87jw35",
"hotelName": "Hilton İstanbul Kozyatağı",
"roomSearchId": "d2fa4b5c-6c93-4f47-93a6-9222ea2df77e",
"suggested": true,
"hotelRankingScore": 0,
"destinations": [
0: {
"id": 328335,
"type": "CUSTOMREGION",
"typeId": 5,
"name": "Kadıköy"
},
1: {
"id": 1303,
"type": "REGION",
"typeId": 2,
"name": "İstanbul Anadolu Yakası"
},
2: {
"id": 795,
"type": "CITY",
"typeId": 3,
"name": "İstanbul"
},
3: {
"id": 740,
"type": "REGION",
"typeId": 2,
"name": "Marmara Bölgesi"
},
4: {
"id": 549,
"type": "COUNTRY",
"typeId": 1,
"name": "Türkiye"
}
],
"rooms": [
0: {
"pax": {
"adult": 2,
"child": 1,
"childAges": [
0: 3
]
},
"roomType": "Twin, City View, ",
"roomCode": "4216",
"roomCapacity": 2,
"bedTypes": [
0: {
"id": 2713,
"name": "Tek Kişilik Yatak"
}
],
"rates": [
0: {
"rateId": "230886",
"totalPrice": 222.13,
"nightlyPrices": [
0: {
"date": "2025-04-09",
"amount": 111.07,
"currency": "EUR"
},
1: {
"date": "2025-04-10",
"amount": 111.07,
"currency": "EUR"
}
],
"priceCode": "500017|sxk9jv7y87jw35|20|2025-04-09|2025-04-11|3|Sales|3923471yxvqa08xw6092h0dwjvmjrtwb6|2sc8facr6qw2v0o9g51yok6xjr6umzq6",
"cancellationPolicies": [
0: {
"amount": 0,
"currency": "EUR",
"toDate": "2025-04-09T16:00:00",
"fromDate": "2025-03-13T14:33:43.832628"
},
1: {
"amount": 222.13,
"currency": "EUR",
"toDate": "2025-04-09T16:00:00",
"fromDate": "2025-04-09T16:00:00"
}
],
"mealType": "Bed & Breakfast",
"mealTypeCode": "BB",
"taxes": [
],
"fees": [
],
"refundable": true,
"restrictions": [
]
},
1: {
"rateId": "173642",
"totalPrice": 222.13,
"nightlyPrices": [
0: {
"date": "2025-04-09",
"amount": 111.07,
"currency": "EUR"
},
1: {
"date": "2025-04-10",
"amount": 111.07,
"currency": "EUR"
}
],
"priceCode": "500017|sxk9jv7y87jw35|20|2025-04-09|2025-04-11|3|Sales|39234726bk8q0h02ob02bkxup0yssm0q6|2sc8facr6qw2v0o9g51yok6xjr6umzq6",
"cancellationPolicies": [
0: {
"amount": 0,
"currency": "EUR",
"toDate": "2025-04-09T16:00:00",
"fromDate": "2025-03-13T14:33:43.836638"
},
1: {
"amount": 222.13,
"currency": "EUR",
"toDate": "2025-04-09T16:00:00",
"fromDate": "2025-04-09T16:00:00"
}
],
"mealType": "Room Only",
"mealTypeCode": "RO",
"taxes": [
],
"fees": [
],
"refundable": true,
"restrictions": [
]
}
]
},
1: {
"pax": {
"adult": 2,
"child": 1,
"childAges": [
0: 3
]
},
"roomType": "King, City View, ",
"roomCode": "4212",
"roomCapacity": 2,
"bedTypes": [
0: {
"id": 638,
"name": "Geniş Çift Kişilik"
}
],
"rates": [
0: {
"rateId": "230892",
"totalPrice": 242.31,
"nightlyPrices": [
0: {
"date": "2025-04-09",
"amount": 121.16,
"currency": "EUR"
},
1: {
"date": "2025-04-10",
"amount": 121.16,
"currency": "EUR"
}
],
"priceCode": "500017|sxk9jv7y87jw35|20|2025-04-09|2025-04-11|3|Sales|3923473r3paoelwkthd2vs4hbgrezfqs6|2sc8facr6qw2v0o9g51yok6xjr6umzq6",
"cancellationPolicies": [
0: {
"amount": 0,
"currency": "EUR",
"toDate": "2025-04-09T16:00:00",
"fromDate": "2025-03-13T14:33:43.851681"
},
1: {
"amount": 242.31,
"currency": "EUR",
"toDate": "2025-04-09T16:00:00",
"fromDate": "2025-04-09T16:00:00"
}
],
"mealType": "Bed & Breakfast",
"mealTypeCode": "BB",
"taxes": [
],
"fees": [
],
"refundable": true,
"restrictions": [
]
},
1: {
"rateId": "173649",
"totalPrice": 242.31,
"nightlyPrices": [
0: {
"date": "2025-04-09",
"amount": 121.16,
"currency": "EUR"
},
1: {
"date": "2025-04-10",
"amount": 121.16,
"currency": "EUR"
}
],
"priceCode": "500017|sxk9jv7y87jw35|20|2025-04-09|2025-04-11|3|Sales|39234715fuof6bbo6tq2fs1uasi1xveh6|2sc8facr6qw2v0o9g51yok6xjr6umzq6",
"cancellationPolicies": [
0: {
"amount": 0,
"currency": "EUR",
"toDate": "2025-04-09T16:00:00",
"fromDate": "2025-03-13T14:33:43.855337"
},
1: {
"amount": 242.31,
"currency": "EUR",
"toDate": "2025-04-09T16:00:00",
"fromDate": "2025-04-09T16:00:00"
}
],
"mealType": "Room Only",
"mealTypeCode": "RO",
"taxes": [
],
"fees": [
],
"refundable": true,
"restrictions": [
]
}
]
},
2: {
"pax": {
"adult": 2,
"child": 1,
"childAges": [
0: 3
]
},
"roomType": "Deluxe King Room, City View, ",
"roomCode": "4210",
"roomCapacity": 3,
"bedTypes": [
0: {
"id": 2714,
"name": "Çift Kişilik Yatak"
}
],
"rates": [
0: {
"rateId": "173643",
"totalPrice": 262.5,
"nightlyPrices": [
0: {
"date": "2025-04-09",
"amount": 131.25,
"currency": "EUR"
},
1: {
"date": "2025-04-10",
"amount": 131.25,
"currency": "EUR"
}
],
"priceCode": "500017|sxk9jv7y87jw35|20|2025-04-09|2025-04-11|3|Sales|392347sqbgwk1w0c8m1y3sk6ekohs1w6|2sc8facr6qw2v0o9g51yok6xjr6umzq6",
"cancellationPolicies": [
0: {
"amount": 0,
"currency": "EUR",
"toDate": "2025-04-09T16:00:00",
"fromDate": "2025-03-13T14:33:43.840232"
},
1: {
"amount": 262.5,
"currency": "EUR",
"toDate": "2025-04-09T16:00:00",
"fromDate": "2025-04-09T16:00:00"
}
],
"mealType": "Room Only",
"mealTypeCode": "RO",
"taxes": [
],
"fees": [
],
"refundable": true,
"restrictions": [
]
},
1: {
"rateId": "230888",
"totalPrice": 262.5,
"nightlyPrices": [
0: {
"date": "2025-04-09",
"amount": 131.25,
"currency": "EUR"
},
1: {
"date": "2025-04-10",
"amount": 131.25,
"currency": "EUR"
}
],
"priceCode": "500017|sxk9jv7y87jw35|20|2025-04-09|2025-04-11|3|Sales|3923473d1qg6ofj82mg25xqn37jn6k4l6|2sc8facr6qw2v0o9g51yok6xjr6umzq6",
"cancellationPolicies": [
0: {
"amount": 0,
"currency": "EUR",
"toDate": "2025-04-09T16:00:00",
"fromDate": "2025-03-13T14:33:43.843855"
},
1: {
"amount": 262.5,
"currency": "EUR",
"toDate": "2025-04-09T16:00:00",
"fromDate": "2025-04-09T16:00:00"
}
],
"mealType": "Bed & Breakfast",
"mealTypeCode": "BB",
"taxes": [
],
"fees": [
],
"refundable": true,
"restrictions": [
]
}
]
},
3: {
"pax": {
"adult": 2,
"child": 1,
"childAges": [
0: 3
]
},
"roomType": "Executive Room, City View, ",
"roomCode": "4209",
"roomCapacity": 2,
"bedTypes": [
0: {
"id": 2714,
"name": "Çift Kişilik Yatak"
}
],
"rates": [
0: {
"rateId": "230887",
"totalPrice": 363.47,
"nightlyPrices": [
0: {
"date": "2025-04-09",
"amount": 181.74,
"currency": "EUR"
},
1: {
"date": "2025-04-10",
"amount": 181.74,
"currency": "EUR"
}
],
"priceCode": "500017|sxk9jv7y87jw35|20|2025-04-09|2025-04-11|2-3|Sales|39234721daxl4bbyuub26wa2udfg7kkk6|2sc8facr6qw2v0o9g51yok6xjr6umzq6",
"cancellationPolicies": [
0: {
"amount": 0,
"currency": "EUR",
"toDate": "2025-04-09T16:00:00",
"fromDate": "2025-03-13T14:33:43.828214"
},
1: {
"amount": 363.47,
"currency": "EUR",
"toDate": "2025-04-09T16:00:00",
"fromDate": "2025-04-09T16:00:00"
}
],
"mealType": "Bed & Breakfast",
"mealTypeCode": "BB",
"taxes": [
],
"fees": [
],
"refundable": true,
"restrictions": [
]
},
1: {
"rateId": "173644",
"totalPrice": 363.47,
"nightlyPrices": [
0: {
"date": "2025-04-09",
"amount": 181.74,
"currency": "EUR"
},
1: {
"date": "2025-04-10",
"amount": 181.74,
"currency": "EUR"
}
],
"priceCode": "500017|sxk9jv7y87jw35|20|2025-04-09|2025-04-11|2-3|Sales|3923472wmxbffmi7a7h20e44c780jn1h6|2sc8facr6qw2v0o9g51yok6xjr6umzq6",
"cancellationPolicies": [
0: {
"amount": 0,
"currency": "EUR",
"toDate": "2025-04-09T16:00:00",
"fromDate": "2025-03-13T14:33:43.847595"
},
1: {
"amount": 363.47,
"currency": "EUR",
"toDate": "2025-04-09T16:00:00",
"fromDate": "2025-04-09T16:00:00"
}
],
"mealType": "Room Only",
"mealTypeCode": "RO",
"taxes": [
],
"fees": [
],
"refundable": true,
"restrictions": [
]
}
]
}
],
"hotelImportantNotes": [
]
}
| Name | Type | Required | Description |
|---|---|---|---|
| hotelCode | string | Yes | 'Code of the hotel that is clicked and directed to the details after the search is made. |
| 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. |
| Name | Type | Required | Description |
|---|---|---|---|
| hotelCode | string | Yes | Code of the selected hotel. |
| hotelName | string | Yes | Name of the selected hotel. |
| roomSearchId | string | Yes | During the room search, this key will keep the response data in the cache. It will be in the Book request and produced by us. |
| destinations | object-array | Yes | The destinations where the hotel is located are placed in the 'destinationCode' object. |
| destinations/id | int | Yes | Destination id in Etstur structure. |
| destinations/type | string | Yes | Destination type in Etstur structure. |
| destinations/typeId | int | Yes | Destination typeId in Etstur structure. |
| destinations/name | string | Yes | Destination name in Etstur structure. |
| rooms | object-array | Yes | The 'rooms' object returns information about all of the hotel's rooms. |
| rooms/pax | object | Yes | Information about the guests that can be accommodated. |
| rooms/pax/adult | object | Yes | The number of adults that can be accommodated. |
| rooms/pax/child | int | No | The number of cildren that can be accommodated. |
| rooms/pax/childAges | int | No | If there are children in the reservation, age of the children must be sent. |
| rooms/roomType | string | Yes | Room type in Etstur structure. |
| rooms/roomCode | string | Yes | Room code in Etstur structure. |
| rooms/rates | object-array | Yes | Structure that enables the display of room plans at various rates. |
| rooms/rates/totalPrice | decimal | Yes | Total price of the room. |
| rooms/rates/nightlyPrices | object-array | Yes | An object that allows the room's nightly prices to be displayed separately and Price must be big decimal type. |
| rooms/rates/nightlyPrices/date | string | Yes | Date of the day, date format must be yyyy-MM-dd |
| rooms/rates/nightlyPrices/amount | decimal | Yes | Price amount of the day |
| rooms/rates/nightlyPrices/currency | string | Yes | Information in which currency the reservation amount is in is returned with the 'currency' parameter. |
| rooms/rates/priceCode | string | Yes | Unique value generated for that price in each room search by us. The validity period of the price code is 30 minutes. |
| rooms/rates/cancellationPolicies | object-array | No | Object to return information for cancellation policies. |
| rooms/rates/cancellationPolicies/amount | decimal | No | Penalty amount to be paid |
| rooms/rates/cancellationPolicies/currency | string | No | Penalty amount currency to be paid |
| rooms/rates/cancellationPolicies/toDate | string | No | Cancellation policy is valid for UTC+03:00 time zone. |
| rooms/rates/cancellationPolicies/fromDate | string | No | Cancellation policy is valid for UTC+03:00 time zone. |
| rooms/rates/mealType | string | Yes | Meal type in Etstur structure. |
| rooms/rates/mealTypeCode | string | Yes | Meal type code in Etstur structure. |
| rooms/rates/taxes | object-array | No | If there is a tax related to accommodation, it will be included in this field. |
| rooms/rates/taxes/type | string | No | Tax type |
| rooms/rates/taxes/price | decimal | No | Tax amount |
| rooms/rates/taxes/currency | string | No | Tax currency |
| rooms/rates/taxes/description | string | No | Tax description |
| rooms/rates/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. |
| rooms/rates/fees | object-array | No | If there is an extra fee related to accommodation, it will be included in this field. |
| rooms/rates/fees/type | string | No | Fee type |
| rooms/rates/fees/price | decimal | No | Fee amount |
| rooms/rates/fees/currency | string | No | Fee currency |
| rooms/rates/fees/description | string | No | Fee description |
| rooms/rates/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. |
| rooms/rates/refundable | boolean | Yes | Information about whether the reservation is cancelled. Refundable if it is True, nonrefundable if it is False. |
Errors specific to this endpoint (3 codes). Gateway and authentication errors apply to every endpoint and are listed in the Error Codes reference.
No availabilityThe request is valid, but no hotels, rooms or results match the given criteria.
| Group | Code | Message | Description |
|---|---|---|---|
| No availability | 0904080 | Hotel room not found | Returned during Room Search or when its result is used for booking when no results match the given criteria. Not a failure. Inform the user and try different dates, occupancy or destination. |
| No availability | 0904082 | Room search failed because of the restriction implementation. | Returned during Room Search or when its result is used for booking when no results match the given criteria. Not a failure. Inform the user and try different dates, occupancy or destination. |
TimeoutThe request or the search session expired before it could be completed.
| Group | Code | Message | Description |
|---|---|---|---|
| Timeout | 0904081 | The time has expired to continue the process, please search for a room and try again. | Returned during Room Search or when its result is used for booking when the operation or the session has expired. Restart the flow from the indicated step (for example, run Room Search again). |
Error groups
| Group | Meaning | Recommended action |
|---|---|---|
| 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. |
| Timeout | The request or the search session expired before it could be completed. | Restart the flow from the indicated step (for example, run Room Search again). |