Hotels Search Engine Results Page
https://api.worldota.net/api/b2b/v3/search/serp/hotels/Search Engine Results Page (SERP) - this is for the preliminary search of a hotel with available accommodation that meets the given search conditions. It is not recommended to let the users choose the rates from this method (a full match with results from the Hotelpage request is not expected).
Request example
curl --location 'https://api.worldota.net/api/b2b/v3/search/serp/hotels/' \
--header 'Content-Type: application/json' \
--data '{
"checkin": "2020-06-25",
"checkout": "2020-06-26",
"residency": "gb",
"language": "en",
"guests": [
{
"adults": 2,
"children": []
}
],
"ids": [
"access_international_hotel_annex",
"rila_muam_castle_hotel",
"alama_hotel_multipurpose",
"prestige_hotel_limited",
"chimcherry_hotel_limited",
"green_suites_villa",
"kenfeli_international_palmbeach_hotel"
],
"currency": "EUR"
}'Request body
Currency of the rooms’ price in the response.
If no currency is specified or the default value is set, then the actual currency requested is the contract’s currency for prepay rates.
It influences show_amount and show_currency_amount only.
default: Contract’s currency
The language.
- The default value is the contract language.
- The possible values:
ar—Arabic.bg–Bulgarian.cs–Czech.de–German.el–Greek.en–English.es–Spanish.fr–French.he–Hebrew.hu–Hungarian.it–Italian.ja–Japanese.kk–Kazakh.ko–Korean.nl–Dutch.pl–Polish.pt–Portuguese.pt_PT–Portuguese (Portugal).ro–Romanian.ru–Russian.sq–Albanian.sr–Serbian.th–Thai.tr–Turkish.uk–Ukrainian.vi–Vietnamese.zh_CN–Simplified Chinese.
Guest’s (or multiple guests’) citizenship.
This is recommended for usage if there are doubts regarding a country’s/hotel’s policy towards citizens of a specific country.
Value’s standard = ISO 3166-1 alpha-2, the value shall be transferred in lower case, number of the value’s symbols = 2.
(could be required for some partners)
The maximum amount of time (in seconds) within which searched for rates will be returned.
- The maximum value is
100.
The list of guests in the rooms.
The maximum number of rooms per request, which is 9 (one object corresponds to one room).
In case of multiroom search, for each room equal pax numbers are highly recommended for usuge. If different pax numbers are required, we recommend that you make a separate request for each room.
Response
Information about the found hotel and its rates.
The unique hotel identifier.
- Either this field or the
hidfield is required.
- Either this field or the
hidfield is required.
The most preferred hotel ID.
- Either this field or the
idfield is required. - The maximum length is
7characters.
- Either this field or the
idfield is required. - The maximum length is
7characters.
List of available rates at the hotel.
List of amenities in the room.
There is a request which returns all available room amenities and definitions (room_amenities key):
Unique identifier of the rate. This value is passed to booking API method to identify a selected rate.
book_hash key’s value can be transferred via the Order Booking Form method within 6 hours after the corresponding rate was returned in the search results. Exceeding this limit will return an error with error.slug containing a “rate_not_found” value.
The deposit information of the order. Has a value if the rate payment_types.type field has the hotel value.
The match_hash field of the rate from the call made by the SERP mechanism.
Use this field if you are:
- Showing rates to the users from the call made by the SERP mechanism.
- Making a booking from these rates.
- Using this call response as actual data on the rate.
- Using this call response to actualize the exact rate from the calls made by the SERP mechanism.
Usage of this field can help the ETG collect analytics for SERP-HP matching.
Meal type in the rate.
There is a request which returns all available meals and definitions (meals key):
https://api.worldota.net/api/b2b/v3/hotel/static/
If there is no meal type provided by the rate’s source, nomeal value is displayed.
No-show penalty information.
Accepted payment options, with specified amount to be charged, transferred as an object with key-value pairs payment_options.payment_types.
Please note that for a reservation, namely the specified sum (with the given currency) shall be paid.
Array with accepted payment option for the requested rate.
currency_code).
Rate’s cancellation rules with commission information.
Date when free cancellation policy expires (may return null - no free cancellation).
Timezone is UTC+0.
Cancellation policies’ breakdown by time periods.
Date when this particular cancellation policy expires (null means all the time from start_at till check in).
Timezone is UTC+0.
If start_at == end_at == null then this particular cancellation policy has no time restrictions / is in effect all the time.
Information about taxes in the rate.
List of taxes, information about which is available for these rates.
Tax identifier at Emerging Travel Group.
There is a request which returns all available taxes and definitions (taxes key):
Type of hotel room.
rg_ext can be used to obtain extra information about the room from the hotel’s static information (room images, description etc.).
Structured room name in the selected language.
Response example
{
"data": {
"hotels": [
{
"id": "access_international_hotel_annex",
"rates": [
{
"match_hash": "m-d580b80f-4189-5020-ba37-b0a73f4b67a3",
"daily_prices": [
"24.10"
],
"meal": "nomeal",
"payment_options": {
"payment_types": [
{
"amount": "1905.00",
"show_amount": "24.00",
"currency_code": "RUB",
"show_currency_code": "EUR",
"by": "credit_card",
"is_need_credit_card_data": true,
"is_need_cvc": true,
"type": "now",
"tax_data": {},
"cancellation_penalties": {
"policies": [
{
"start_at": null,
"end_at": "2020-06-23T17:00:00",
"amount_charge": "0.00",
"amount_show": "0.00"
},
{
"start_at": "2020-06-23T17:00:00",
"end_at": null,
"amount_charge": "1905.00",
"amount_show": "24.00"
}
],
"free_cancellation_before": "2020-06-23T17:00:00"
}
}
]
},
"rg_ext": {
"class": 3,
"quality": 2,
"sex": 0,
"bathroom": 2,
"bedding": 3,
"family": 0,
"capacity": 2,
"club": 0
},
"room_name": "Standard Double room (double bed)",
"room_name_info": null,
"serp_filters": [
"has_bathroom"
],
"allotment": null,
"amenities_data": [
"double",
"non-smoking",
"private-bathroom",
"window"
],
"any_residency": true,
"deposit": {
"amount": "270.00",
"currency_code": "EUR",
"is_refundable": false
},
"no_show": {
"amount": "270.00",
"currency_code": "EUR",
"from_time": "12:00:00"
},
"room_data_trans": {
"main_room_type": "Standard Double room",
"main_name": "Standard Double room",
"bathroom": null,
"bedding_type": "double bed",
"misc_room_type": null
}
}
]
},
{
"id": "rila_muam_castle_hotel",
"rates": [
{
"match_hash": "m-854d6b9f-82ee-56d8-bd0e-e585edec3a89",
"daily_prices": [
"31.33"
],
"meal": "nomeal",
"payment_options": {
"payment_types": [
{
"amount": "2199.00",
"show_amount": "27.00",
"currency_code": "RUB",
"show_currency_code": "EUR",
"by": "credit_card",
"is_need_credit_card_data": true,
"is_need_cvc": true,
"type": "now",
"tax_data": {},
"cancellation_penalties": {
"policies": [
{
"start_at": null,
"end_at": "2020-06-23T15:00:00",
"amount_charge": "0.00",
"amount_show": "0.00"
},
{
"start_at": "2020-06-23T15:00:00",
"end_at": null,
"amount_charge": "2199.00",
"amount_show": "27.00"
}
],
"free_cancellation_before": "2020-06-23T15:00:00"
}
}
]
},
"rg_ext": {
"class": 3,
"quality": 2,
"sex": 0,
"bathroom": 2,
"bedding": 3,
"family": 0,
"capacity": 2,
"club": 0
},
"room_name": "Standard Double room (double bed) (bed type is subject to availability)",
"serp_filters": [
"has_bathroom"
],
"allotment": 2,
"amenities_data": [
"double",
"non-smoking",
"private-bathroom",
"window"
],
"any_residency": false,
"deposit": null,
"no_show": {
"amount": "25.00",
"currency_code": "USD",
"from_time": "12:00:00"
},
"room_data_trans": {
"main_room_type": "Standard Double room",
"main_name": "Standard Double room",
"bathroom": null,
"bedding_type": "double bed",
"misc_room_type": "bed type is subject to availability"
}
}
]
},
{
"id": "alama_hotel_multipurpose",
"rates": [
{
"match_hash": "m-96a3ba8c-a183-5cac-8e56-7a268612g0537",
"daily_prices": [
"29.95"
],
"meal": "nomeal",
"payment_options": {
"payment_types": [
{
"amount": "2367.00",
"show_amount": "29.00",
"currency_code": "RUB",
"show_currency_code": "EUR",
"by": "credit_card",
"is_need_credit_card_data": true,
"is_need_cvc": true,
"type": "now",
"tax_data": {},
"cancellation_penalties": {
"policies": [
{
"start_at": null,
"end_at": "2020-06-24T17:00:00",
"amount_charge": "0.00",
"amount_show": "0.00"
},
{
"start_at": "2020-06-24T17:00:00",
"end_at": null,
"amount_charge": "2367.00",
"amount_show": "29.00"
}
],
"free_cancellation_before": "2020-06-24T17:00:00"
}
}
]
},
"rg_ext": {
"class": 3,
"quality": 6,
"sex": 0,
"bathroom": 2,
"bedding": 3,
"family": 0,
"capacity": 2,
"club": 0
},
"room_name": "Deluxe Double room (double bed)",
"serp_filters": [
"has_bathroom"
],
"allotment": 23,
"amenities_data": [
"double",
"non-smoking",
"private-bathroom",
"window"
],
"any_residency": true,
"deposit": null,
"no_show": null,
"room_data_trans": {
"main_room_type": "Deluxe Double room",
"main_name": "Deluxe Double room",
"bathroom": null,
"bedding_type": "double bed",
"misc_room_type": null
}
}
]
},
{
"id": "prestige_hotel_limited",
"rates": [
{
"match_hash": "m-e8ada8a5-16e7-543c-8497-4e52d7yuu672",
"daily_prices": [
"24.10"
],
"meal": "nomeal",
"payment_options": {
"payment_types": [
{
"amount": "1905.00",
"show_amount": "24.00",
"currency_code": "RUB",
"show_currency_code": "EUR",
"by": "credit_card",
"is_need_credit_card_data": true,
"is_need_cvc": true,
"type": "now",
"tax_data": {},
"cancellation_penalties": {
"policies": [
{
"start_at": null,
"end_at": "2020-06-23T17:00:00",
"amount_charge": "0.00",
"amount_show": "0.00"
},
{
"start_at": "2020-06-23T17:00:00",
"end_at": null,
"amount_charge": "1905.00",
"amount_show": "24.00"
}
],
"free_cancellation_before": "2020-06-23T17:00:00"
}
}
]
},
"rg_ext": {
"class": 3,
"quality": 2,
"sex": 0,
"bathroom": 2,
"bedding": 3,
"family": 0,
"capacity": 2,
"club": 0
},
"room_name": "Standard Double room (double bed)",
"serp_filters": [
"has_bathroom"
],
"allotment": null,
"amenities_data": [
"double",
"non-smoking",
"private-bathroom",
"window"
],
"any_residency": true,
"deposit": null,
"no_show": null,
"room_data_trans": {
"main_room_type": "Standard Double room",
"main_name": "Standard Double room",
"bathroom": null,
"bedding_type": "double bed",
"misc_room_type": null
}
}
]
},
{
"id": "chimcherry_hotel_limited",
"rates": [
{
"match_hash": "m-63d0c135-ca74-58ef-82a7-959346bb55y1",
"daily_prices": [
"24.10"
],
"meal": "nomeal",
"payment_options": {
"payment_types": [
{
"amount": "1905.00",
"show_amount": "24.00",
"currency_code": "RUB",
"show_currency_code": "EUR",
"by": "credit_card",
"is_need_credit_card_data": true,
"is_need_cvc": true,
"type": "now",
"tax_data": {},
"cancellation_penalties": {
"policies": [
{
"start_at": null,
"end_at": "2020-06-23T17:00:00",
"amount_charge": "0.00",
"amount_show": "0.00"
},
{
"start_at": "2020-06-23T17:00:00",
"end_at": null,
"amount_charge": "1905.00",
"amount_show": "24.00"
}
],
"free_cancellation_before": "2020-06-23T17:00:00"
}
}
]
},
"rg_ext": {
"class": 3,
"quality": 2,
"sex": 0,
"bathroom": 2,
"bedding": 3,
"family": 0,
"capacity": 2,
"club": 0
},
"room_name": "Standard Double room (double bed)",
"serp_filters": [
"has_bathroom"
],
"allotment": null,
"amenities_data": [
"double",
"non-smoking",
"private-bathroom",
"window"
],
"any_residency": true,
"deposit": null,
"no_show": null,
"room_data_trans": {
"main_room_type": "Standard Double room",
"main_name": "Standard Double room",
"bathroom": null,
"bedding_type": "double bed",
"misc_room_type": null
}
}
]
},
{
"id": "green_suites_villa",
"rates": [
{
"match_hash": "m-8313f2e4-524a-566b-9f11-be838d62x3f3",
"daily_prices": [
"48.39"
],
"meal": "nomeal",
"payment_options": {
"payment_types": [
{
"amount": "3396.00",
"show_amount": "42.00",
"currency_code": "RUB",
"show_currency_code": "EUR",
"by": "credit_card",
"is_need_credit_card_data": true,
"is_need_cvc": true,
"type": "now",
"tax_data": {},
"cancellation_penalties": {
"policies": [
{
"start_at": null,
"end_at": "2020-06-23T15:00:00",
"amount_charge": "0.00",
"amount_show": "0.00"
},
{
"start_at": "2020-06-23T15:00:00",
"end_at": null,
"amount_charge": "3396.00",
"amount_show": "42.00"
}
],
"free_cancellation_before": "2020-06-23T15:00:00"
}
}
]
},
"rg_ext": {
"class": 3,
"quality": 8,
"sex": 0,
"bathroom": 2,
"bedding": 3,
"family": 0,
"capacity": 2,
"club": 0
},
"room_name": "Executive Double room (double bed) (bed type is subject to availability)",
"serp_filters": [
"has_bathroom"
],
"allotment": 13,
"amenities_data": [
"double",
"non-smoking",
"private-bathroom",
"window"
],
"any_residency": false,
"deposit": null,
"no_show": {
"amount": "39.00",
"currency_code": "USD",
"from_time": "12:00:00"
},
"room_data_trans": {
"main_room_type": "Executive Double room",
"main_name": "Executive Double room",
"bathroom": null,
"bedding_type": "double bed",
"misc_room_type": "bed type is subject to availability"
}
}
]
},
{
"id": "kenfeli_international_palmbeach_hotel",
"rates": [
{
"match_hash": "m-598117c2-ce0c-54ee-a1c4-f222d2877559",
"daily_prices": [
"18.86"
],
"meal": "nomeal",
"payment_options": {
"payment_types": [
{
"amount": "1491.00",
"show_amount": "18.00",
"currency_code": "RUB",
"show_currency_code": "EUR",
"by": "credit_card",
"is_need_credit_card_data": true,
"is_need_cvc": true,
"type": "now",
"tax_data": {},
"cancellation_penalties": {
"policies": [
{
"start_at": null,
"end_at": "2020-06-23T17:00:00",
"amount_charge": "0.00",
"amount_show": "0.00"
},
{
"start_at": "2020-06-23T17:00:00",
"end_at": null,
"amount_charge": "1491.00",
"amount_show": "18.00"
}
],
"free_cancellation_before": "2020-06-23T17:00:00"
}
}
]
},
"rg_ext": {
"class": 3,
"quality": 6,
"sex": 0,
"bathroom": 2,
"bedding": 3,
"family": 0,
"capacity": 2,
"club": 0
},
"room_name": "Deluxe Double room (double bed)",
"serp_filters": [
"has_bathroom"
],
"allotment": null,
"amenities_data": [
"double",
"non-smoking",
"private-bathroom",
"window"
],
"any_residency": true,
"deposit": null,
"no_show": null,
"room_data_trans": {
"main_room_type": "Deluxe Double room",
"main_name": "Deluxe Double room",
"bathroom": null,
"bedding_type": "double bed",
"misc_room_type": null
}
}
]
}
],
"total_hotels": 7
},
"debug": {
"request": {
"checkin": "2020-06-25",
"checkout": "2020-06-26",
"residency": "gb",
"language": "en",
"guests": [
{
"adults": 2,
"children": []
}
],
"ids": [
"access_international_hotel_annex",
"rila_muam_castle_hotel",
"alama_hotel_multipurpose",
"prestige_hotel_limited",
"chimcherry_hotel_limited",
"green_suites_villa",
"kenfeli_international_palmbeach_hotel"
],
"currency": "EUR"
},
"key_id": 1234,
"validation_error": null
},
"status": "ok",
"error": null
}Errors
Invalid JSON
The error field has the invalid_json_format value. The debug.validation_error field has the value specified in the headers below.
body_must_be_json
The passed JSON isn’t valid.
Invalid parameters or request body
For these, the error field has the invalid_params value. The debug.validation_error field has the value specified in the headers below.
number of ids should be less than or equal to X
The item number of the ids field must be between 1 and 300.
date should be ISO8601 (YYYY-MM-DD)
The passed checkin and checkout fields have an invalid format. The valid format is YYYY-MM-DD.
checkin date must be current or future date
The checkin field value is in the past. Provide the current or future date.
checkin date must be less than or equal to 730 days since today
The checkin field value should be no later than 730 days from the day of the request.
checkout date must be less than or equal to %d days since today
The checkout field value should be no later than 30 days from the checkin field value.
checkout date must be after checkin date
The checkout field value should be later than the checkin field value.
checkout cannot be later than X days since checkin
The checkout field value should be no later than 30 days from the checkin field value.
residency is required
The residency field is required.
residency must be one of X
The residency field has an invalid format. The valid format is in the ISO 3166-1 alpha-2.
unknown currency
The currency field has an invalid format. The valid format is in the ISO 4217.
early checkin date must be equal checkin date
The upsells.early_checkin.time field value should be the same as the checkin field value.
late checkout date must be equal checkout date
The upsells.late_checkout.time field value should be the same as the checkout field value.
early checkin must be in datetime format
The checkin field has an invalid format. The valid formats are:
2006-01-02.2006-01-02 15:04.2006-01-02T15:04.2006-01-02 15:04:05.2006-01-02T15:04:05.2006-01-02T15:04:05-07:00.2006-01-02T15:04:05Z07:00.
late checkout must be in datetime format
The checkout field has an invalid format. The valid formats are:
2006-01-02.2006-01-02 15:04.2006-01-02T15:04.2006-01-02 15:04:05.2006-01-02T15:04:05.2006-01-02T15:04:05-07:00.2006-01-02T15:04:05Z07:00.
guests number must be positive
The guests field value must be positive.
too many rooms, value should be no more than X
The item number of the guests field must be between 1 and 9.
adults number per room must be in range 1 to X inc
The adults field value must be between 1 and 6.
children number per room must be not greater then X
The children field value must be between 1 and 4.
child's age must be in range 0 to X incl
The age field value must be between 0 and 17.
Internal search error
The error field has the сore_search_error value. The debug.validation_error field has the null value.
The error occurs if the ETG has an internal search error. The number of recurrent identical requests must be limited.