ETG API V3
Affiliate API
Hotel search
Hotelpage

Hotelpage

https://api.worldota.net/api/b2b/v3/search/hp/
ℹ️
The call is required.

Hotel rates actualization.

This request is necessary to make a booking via API.

This request is not supposed to be made for each of the hotels found via region_id or IDs, but is supposed to be made only in case when the user chooses it.

The recommended storage time of retrieved rates is no longer than 1 hour. The actual period within which rates from this method are available for booking requests is longer, and can depend on many internal factors.

Request example 

curl --location 'https://api.worldota.net/api/b2b/v3/search/hp/' \
--header 'Content-Type: application/json' \
--data '{
    "checkin": "2024-04-25",
    "checkout": "2024-04-26",
    "residency": "gb",
    "language": "en",
    "guests": [
        {
            "adults": 2,
            "children": []
        }
    ],
    "id": "access_international_hotel_annex",
    "currency": "EUR"
}'

Request body

checkin String required
Check-in date, no later than 730 days from the day on which the request is made.
checkout String required
Check-out date, no later than 30 days from checkin date.
currency String optional

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

id Int required or optional

The unique hotel identifier.

ℹ️
  • Either this field or the hid field is required.
hid Int required or optional

The most preferred hotel ID.

ℹ️
  • Either this field or the id field is required.
  • The maximum length is 7 characters.
language String optional

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.
match_hash String optional

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.

residency String required or optional

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)

timeout Number optional

The maximum amount of time (in seconds) within which searched for rates will be returned.

ℹ️
  • The maximum value is 100.
guests Array[Object] optional

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.

adults Int required

Number of adult guests.

ℹ️
  • The minimum value is 1.
  • The maximum value is 6.
children [Int] optional

Age of children who will stay in the room.

ℹ️
  • Maximum number of children is 4.
  • The maximum age is 17.

Response

total_hotels Int optional
Total number of hotels.
hotels Array[Object] optional

Information about the found hotel and its rates.

id String required or optional

The unique hotel identifier.

ℹ️
  • Either this field or the hid field is required.
ℹ️
  • Either this field or the hid field is required.
hid Int required or optional

The most preferred hotel ID.

ℹ️
  • Either this field or the id field is required.
  • The maximum length is 7 characters.
ℹ️
  • Either this field or the id field is required.
  • The maximum length is 7 characters.
rates Array[Object] optional

List of available rates at the hotel.

allotment Int optional
Allotment.
amenities_data [String] optional

List of amenities in the room.

There is a request which returns all available room amenities and definitions (room_amenities key):

https://api.worldota.net/api/b2b/v3/hotel/static/

any_residency Boolean optional
Whether or not the rate is allowed to be booked by the guest with any kind of residency. Should be used by the partners that do not collect the real guest’s residency.
book_hash String optional

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.

daily_prices [Number] optional
Daily rate prices breakdown in the search currency.
deposit Object required

The deposit information of the order. Has a value if the rate payment_types.type field has the hotel value.

amount Number optional
The deposit amount.
currency_code String optional
The deposit amount currency code. Is the same as the charged (hotel) currency code.
is_refundable Boolean optional
Whether the deposit is refundable or not.
match_hash String optional

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 String optional

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 Object optional

No-show penalty information.

amount Number optional
Amount of the no-show penalty (in the hotel’s currency - currency_code).
currency_code String optional
Amount’s currency. Is the same as the charged (hotel’s) currency.
from_time String optional
Time (local timezone) from which amount would be charged for the no-show.
payment_options Object required

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.

payment_types String optional

Array with accepted payment option for the requested rate.

amount Number optional
Amount to be charged for the booking (in the contract’s currency - currency_code).
by String optional
Payment instrument.
cancellation_penalties String optional

Rate’s cancellation rules with commission information.

free_cancellation_before String optional

Date when free cancellation policy expires (may return null - no free cancellation).

Timezone is UTC+0.

policies String optional

Cancellation policies’ breakdown by time periods.

amount_charge Number optional
Cancellation penalty amount (in the charge/contract currency).
amount_show Number optional
Cancellation penalty amount (in the search currency).
end_at String optional

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.

start_at String optional

Date when this particular cancellation policy takes effect (null means that it is in effect till end_at).

Timezone is UTC+0.

currency_code String optional
Amount’s currency. Is the same as the charged (contract’s) currency.
is_need_credit_card_data Boolean optional
Whether or not credit card information is needed.
is_need_cvc Boolean optional
Whether or not a CVC code is needed.
show_amount Number optional
Rate price in the requested (show_currency_code) currency (not necessarily the sum in the charged/payment currency).
show_currency_code String optional
Requested currency (not necessarily the charged/payment currency).
tax_data Object optional

Information about taxes in the rate.

taxes Object optional

List of taxes, information about which is available for these rates.

amount Number optional
Amount of the tax.
currency_code String optional
Currency in which the amount is specified.
included_by_supplier Boolean optional
Shows if the tax is included in the rate by the supplier; if the tax is not included, it is supposed to be paid at the hotel (in the specified currency).
name String optional

Tax identifier at Emerging Travel Group.

There is a request which returns all available taxes and definitions (taxes key):

https://api.worldota.net/api/b2b/v3/hotel/static/

type String optional
Payment type.
vat_data Object optional

The rate VAT information.

amount Number optional
The VAT amount.
applied Boolean optional
Whether the VAT is applied or not.
currency_code String optional

The currency code in the ISO 4217 format.

ℹ️
  • The length is 3 characters.
  • The possible values:
    • AED.
    • AFN.
    • ALL.
    • AMD.
    • ANG.
    • AOA.
    • ARS.
    • AUD.
    • AWG.
    • AZN.
    • BAM.
    • BBD.
    • BDT.
    • BGN.
    • BHD.
    • BIF.
    • BMD.
    • BND.
    • BOB.
    • BOV.
    • BRL.
    • BSD.
    • BTN.
    • BWP.
    • BYR.
    • BYN.
    • BZD.
    • CAD.
    • CDF.
    • CHE.
    • CHF.
    • CHW.
    • CLF.
    • CLP.
    • CNY.
    • COP.
    • COU.
    • CRC.
    • CUC.
    • CUP.
    • CVE.
    • CZK.
    • DJF.
    • DKK.
    • DOP.
    • DZD.
    • EGP.
    • ERN.
    • ETB.
    • EUR.
    • FJD.
    • FKP.
    • GBP.
    • GEL.
    • GHS.
    • GIP.
    • GMD.
    • GNF.
    • GTQ.
    • GYD.
    • HKD.
    • HNL.
    • HRK.
    • HTG.
    • HUF.
    • IDR.
    • ILS.
    • INR.
    • IQD.
    • IRR.
    • ISK.
    • JMD.
    • JOD.
    • JPY.
    • KES.
    • KGS.
    • KHR.
    • KMF.
    • KPW.
    • KRW.
    • KWD.
    • KYD.
    • KZT.
    • LAK.
    • LBP.
    • LKR.
    • LRD.
    • LSL.
    • LTL.
    • LVL.
    • LYD.
    • MAD.
    • MDL.
    • MGA.
    • MKD.
    • MMK.
    • MNT.
    • MOP.
    • MRO.
    • MUR.
    • MVR.
    • MWK.
    • MXN.
    • MXV.
    • MYR.
    • MZN.
    • NAD.
    • NGN.
    • NIO.
    • NOK.
    • NPR.
    • NZD.
    • OMR.
    • PAB.
    • PEN.
    • PGK.
    • PHP.
    • PKR.
    • PLN.
    • PYG.
    • QAR.
    • RON.
    • RSD.
    • RUB.
    • RWF.
    • SAR.
    • SBD.
    • SCR.
    • SDG.
    • SEK.
    • SGD.
    • SHP.
    • SLL.
    • SOS.
    • SRD.
    • SSP.
    • STD.
    • SVC.
    • SYP.
    • SZL.
    • THB.
    • TJS.
    • TMT.
    • TND.
    • TOP.
    • TRY.
    • TTD.
    • TWD.
    • TZS.
    • UAH.
    • UGX.
    • USD.
    • USN.
    • USS.
    • UYI.
    • UYU.
    • UZS.
    • VEF.
    • VND.
    • VUV.
    • WST.
    • XAF.
    • XAG.
    • XAU.
    • XBA.
    • XBB.
    • XBC.
    • XBD.
    • XCD.
    • XDR.
    • XFU.
    • XOF.
    • XPD.
    • XPF.
    • XPT.
    • XSU.
    • XTS.
    • XUA.
    • YER.
    • ZAR.
    • ZMW.
    • ZWL.
included Boolean optional
Whether the VAT is included or not.
value Number optional
⚠️
DEPRECATED

The VAT amount in the currency of this object currency_code field value.

rg_ext Object optional

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

balcony Integer required
Balcony.
bathroom Integer required
Bathroom.
bedding Integer required
Bedding.
bedrooms Integer required
Bedrooms.
capacity Integer required
Capacity.
class Integer required
Class.
club Integer required
Club.
family Integer required
Family.
floor Integer required
Floor.
quality Integer required
Quality.
sex Integer required
Sex.
view Integer required
View.
room_data_trans Object optional

Structured room name in the selected language.

bathroom String optional

Room’s bathroom information.

null means private bathroom.

bedding_type String optional
Room’s bedding information.
main_name String optional
Room name.
main_room_type String optional
Room name.
misc_room_type String optional
Additional room information.
room_name String optional
Room name in the selected language.
room_name_info Object optional
The optional object that may help resolve certain matching problems. To get access to the object, contact your account manager.
serp_filters [String] required
⚠️
DEPRECATED

List of amenities at the hotel.

Response example 

{
  "data": {
    "hotels": [
      {
        "id": "access_international_hotel_annex",
        "rates": [
          {
            "book_hash": "h-689f63c7-6663-5148-a7ce-01b007frt2zz",
            "match_hash": "m-d580b80f-4189-5020-ba37-b0a73f4b67a3",
            "daily_prices": [
              "23.60"
            ],
            "meal": "nomeal",
            "payment_options": {
              "payment_types": [
                {
                  "amount": "98.60",
                  "show_amount": "22.10",
                  "currency_code": "PLN",
                  "show_currency_code": "EUR",
                  "by": null,
                  "is_need_credit_card_data": false,
                  "is_need_cvc": false,
                  "type": "deposit",
                  "vat_data": {
                    "included": false,
                    "amount": "0.00",
                    "currency_code": "EUR",
                    "value": "0.00"
                  },
                  "tax_data": {},
                  "perks": {},
                  "commission_info": {
                    "show": {
                      "amount_gross": "26.00",
                      "amount_net": "22.10",
                      "amount_commission": "3.90"
                    },
                    "charge": {
                      "amount_gross": "116.00",
                      "amount_net": "98.60",
                      "amount_commission": "17.40"
                    }
                  },
                  "cancellation_penalties": {
                    "policies": [
                      {
                        "start_at": null,
                        "end_at": "2020-04-24T17:00:00",
                        "amount_charge": "0.00",
                        "amount_show": "0.00",
                        "commission_info": {
                          "show": {
                            "amount_gross": "0.00",
                            "amount_net": "0.00",
                            "amount_commission": "0.00"
                          },
                          "charge": {
                            "amount_gross": "0.00",
                            "amount_net": "0.00",
                            "amount_commission": "0.00"
                          }
                        }
                      },
                      {
                        "start_at": "2020-04-24T17:00:00",
                        "end_at": null,
                        "amount_charge": "98.60",
                        "amount_show": "22.10",
                        "commission_info": {
                          "show": {
                            "amount_gross": "26.00",
                            "amount_net": "22.10",
                            "amount_commission": "3.90"
                          },
                          "charge": {
                            "amount_gross": "116.00",
                            "amount_net": "98.60",
                            "amount_commission": "17.40"
                          }
                        }
                      }
                    ],
                    "free_cancellation_before": "2020-04-24T17:00:00"
                  },
                  "recommended_price": {
                    "amount": "107.40",
                    "show_amount": "24.20",
                    "currency_code": "PLN",
                    "show_currency_code": "EUR"
                  }
                }
              ]
            },
            "bar_rate_price_data": null,
            "rg_ext": {
              "class": 3,
              "quality": 2,
              "sex": 2,
              "bathroom": 2,
              "bedding": 3,
              "family": 0,
              "capacity": 2,
              "club": 0
            },
            "room_name": "Standard Double (double bed)",
            "room_name_info": null,
            "serp_filters": [
              "has_bathroom"
            ],
            "sell_price_limits": null,
            "allotment": 5,
            "amenities_data": [
              "double",
              "non-smoking",
              "private-bathroom",
              "window"
            ],
            "any_residency": false
          }
        ],
        "bar_price_data": null,
        "deposit": {
          "amount": "135.00",
          "currency_code": "EUR",
          "is_refundable": false
        },
        "no_show": {
          "amount": "135.00",
          "currency_code": "EUR",
          "from_time": "12:00:00"
        },
        "room_data_trans": {
          "main_room_type": "Standard Double",
          "main_name": "Standard Double",
          "bathroom": null,
          "bedding_type": "double bed",
          "misc_room_type": null
        }
      }
    ]
  },
  "debug": {
    "request": {
      "checkin": "2020-04-25",
      "checkout": "2020-04-26",
      "residency": "gb",
      "language": "en",
      "guests": [
        {
          "adults": 2,
          "children": []
        }
      ],
      "id": "access_international_hotel_annex",
      "currency": "EUR"
    },
    "key_id": 1234,
    "validation_error": null
  },
  "status": "ok",
  "error": null
}
AutocompletePrebook