Availability Search

15min

Request

The table below describes the elements present in a request along with details around their implementation. Please take special note of required fields.

Endpoint:





Element Group

Element Name

Type

Required

Element Description

availabilityRequest

availabilityRequest

Group

Yes

XML Header

availabilityRequest

cancelpolicy

Attribute

Yes

Set to ‘Y’ to have cancellation policies included in the output.

availabilityRequest

hotelcontent

Attribute

No

Static Data in XML Responses - optional (V1, V2) see change log below.

availabilityRequest

hotelfees

Attribute

No

Set to ‘Y’ to have hotel fees included in the response.

availabilityRequest

Control

Group

Yes



Control

username

Element

Yes

The username assigned to you

Control

password

Element

Yes

The password assigned to you

availabilityRequest

checkIn

Element

Yes

Guest Arrival Date (DD-MMM-YYYY)

availabilityRequest

checkout

Element

Yes

Guest Departure Date (DD-MMM-YYYY)

availabilityRequest

noOfRooms

Element

Yes

Number of rooms requested.

availabilityRequest

noOfNights

Element

Yes

Number of nights to be searched.

availabilityRequest

Country

Element

No

Country Code provided by Bonotel.

availabilityRequest

State

Element

No

State Code provided by Bonotel.

availabilityRequest

City

Element

No

City Code provided by Bonotel.

availabilityRequest

hotelCodes

Group

Yes

List of hotel codes to be searched.

hotelCodes

hotelCode

Element

Yes

Hotel code to be searched – one per hotelCode element.

availabilityRequest

roomsInformation

Group

Yes



roomsInformation

roomInfo

Group



Contains room information for all rooms selected. This will repeat up to the number of rooms.

roomInfo

roomTypeId

Element

Yes

The room type id of the room selected. For all room types use "0".

roomInfo

bedTypeId

Element

Yes

The bed type id of the room selected. For all bed types, use "0". This value correlates with occupancy and does not imply bedding.

roomInfo

adultsNum

Element

Yes

Number of Adults per room

roomInfo

childNum

Element

Yes

Number of Children per room.

roomInfo

childAges

Group

No

If Children are provided, the ages of the children are repeated.

childAges

childAge

Element

Yes

Each Child’s age.



Example 1: Hotel Code Search (2 rooms with child)

XML


Example 2: Multiple Hotel Code Search

XML


Example 3: City Code Search

Legacy support is provided to allow for searching by Bonotel-defined city codes. However, customers are strongly encouraged to migrate to a multiple hotel code search based on standardized geographic definitions. We are planning on retiring support for city code searching by mid-2025.

XML


Requesting Hotel Fees in Availability Request

Requesting hotel fees from your availability request requires one small addition to the root XML element, which is: hotelfees="Y". Our system will then return zero or more hotel fees per room in the following format. Here is the root element of availability request with the attribute for hotel fees:

<availabilityRequest cancelpolicy="Y" hotelfees="Y">



Response

Hotel Information

Element Group

Element Name

Type

Req.

Element Description

availabilityResponse



Group

Yes

XML root element, The Availability response contains the available hotel list.

availabilityResponse

Status

Attribute

Yes

Availability request was successful or not. Y or N.

availabilityResponse

Errors

Group

No



Errors

Code

Element

No

Error code provided by Bonotel.

Errors

description

Element

No

A message describing the error.

availabilityResponse

hotelList

Group

Yes

List of available hotels.

hotelList

Hotel

Group

Yes



Hotel

hotelCode

Element

Yes

Internal hotel code assigned by Bonotel.

Hotel

Name

Element

Yes

Name of the Hotel.

Hotel

Address

Element

Yes

Address

Hotel

City

Element

Yes

City of the Hotel.

Hotel

stateProvince

Element

No

If the hotel in USA, Canada or Australia

Hotel

Country

Element

No



Hotel

postalCode

Element

No

Postal Code / Zip code.

Hotel

rateCurrencyCode

Element

No

Currency Code

Hotel

shortDescription

Element

No

Short Description, may contain HTML

Hotel

starRating

Element

No

Star Rating – example: 4star

Hotel

thumbNailUrl

Element

No

Thumbnail image URL of the hotel.

Hotel

hotelUrl

Element

No

Retired element - Do Not Use

Hotel

maintenance

Element

No

If any noteworthy maintenance applies, a description about the maintenance is included.

Hotel

bookingPolicy

Element

No

Retired element - Do Not Use

Hotel

roomInformation

Group

Yes

List of available rooms.

Room Information

Element Group

Element Name

Type

Req.

Element Description

roomInformation

roomNo

Element

Yes

The room occupancy number that matches the request’s occupancy. E.g. If this room can accommodate the first rooms occupancy set sent via the request then the roomNo will be "1".

roomInformation

roomCode

Element

Yes

An internal code assigned for this room by Bonotel. This is a unique code for the room with a certain combination of roomTypeCode and bedTypeCode. This is of type numeric.

roomInformation

roomTypeCode

Element

Yes

An internal code assigned for this room type by Bonotel. This is of type numeric

roomInformation

roomType

Element

Yes

The room type description. E.g. "King Room".

roomInformation

roomDescription

Element

Yes

Element is NULL – we do not have this content to provide.

roomInformation

bedTypeCode

Element

Yes

The bed type code. This is of type numeric.

roomInformation

bedType

Element

Yes

The bed type description. E.g. "Double" – this value correlates to occupancy and does not imply bedding.

roomInformation

stdAdults

Element

No

Standard no of adults that can be accommodated in this room.

roomInformation

promotionCode

Element

No

If any promotions apply, that promotion code or description. e.g. 3rd Night Free

Element Group

Element Name

Type

Required

Element Description

roomInformation

confirmationType

Element

Yes

Always CON for confirmed – no longer supporting on request

roomInformation

confirmationConditions

Group

No

Modification limitations - no longer supporting modifications via the API.

confirmationConditions

Condition

Element

No

Text string for the type – see below listing of descriptions – for example: no modification of stay period

Condition

Type

Attribute

No

Possible values: "NM-SP" : no modification of stay period "NM-AR" : no modification of add room "NM-CR" : no modification of change room "NM-GD" : no modification of guest detail

Condition

Value

Attribute

No

N/A

roomInformation

roomBookingPolicy

Group

No

Information of applicable policies per room. Only be returned if cancelpolicy="Y" was in the root XML element of your request

roomInformation

policyFrom

Element

No

Do not use – we use this to select the policy to serve.

roomInformation

policyTo

Element

No

Do not use – we use this to select the policy to serve.

roomInformation

amendmentType

Element

No

The type of the amendment which the policy is setup for (either it’s a modification policy "Modify" or a cancelation policy "Cancel")

roomInformation

policyBasedOn

Element

No

Not necessary to use, we provide the total cancel fee in policyFee.

roomInformation

policyBasedOnValue

Element

No

Not necessary to use, we provide the total cancel fee in policyFee.

roomInformation

stayDateRequirement

Element

No

Do not use – we use this to select the policy to serve.

roomInformation

arrivalRange

Element

No

To be used with arrivalRangeValue and the check-in date of the booking to identify the start date of the cancel policy. Possible values: ‘Less Than’ or ‘ANY’

roomInformation

arrivalRangeValue

Element

No

To be used with arrivalRange. This is the number of nights before the check-in, defining when the cancel policy will apply. When arrivalRange is ANY, arrivalRangeValue will be 0 – which means the policy applies on any date, even the date of booking.

roomInformation

policyFee

Element

No

Calculated cancellation Fee under the policy.

roomInformation

noShowBasedOn

Element

No

Not necessary to use, we provide the total cancel fee in noShowPolicyFee.

roomInformation

noShowBasedOnValue

Element

No

Not necessary to use, we provide the total cancel fee in noShowPolicyFee.

roomInformation

noShowPolicyFee

Element

No

Calculated no show fee under the policy

roomInformation

rateInformation

Group

Yes



Rate Information

Element Group

Element Name

Type

Req.

Element Description

rateInformation

ratePlanCode

Element

Yes

The rate plan code. This is of type numeric.

rateInformation

ratePlan

Element

Yes

The rate plan name.

Element Group

Element Name

Type

Yes

Element Description

rateInformation

avarageRate

Element





rateInformation

totalRate

Element

Yes

Total rate for this room including taxes.

rateInformation

dailyRates

Group

Yes



dailyRates

nightlyRate

Group

Yes

Each night’s rate for this room including taxes.

nightlyRate

Date

Attribute

Yes

The date which the rate is applicable to.

nightlyRate

dailyCondition

Attribute

Yes

Always blank.

nightlyRate

stdAdultRate

Element

Yes

The standard adult rate (including taxes) for this night for this room.

nightlyRate

additionalAdultRate

Element

No

The additional adult rate (including taxes) for this night for this room if any.

nightlyRate

Total

Element

Yes

Nightly total for this room (including taxes).

nightlyRate

rateCode

Element

No

Rate Code for the rate. This is a specific code assigned by Bonotel.

rateInformation

taxInformation

Group

Yes



taxInformation

Tax

Group

Yes

Tax applied to the total rate.

Tax

taxName

Attribute

Yes

Name of the specific tax applied.

Tax

taxAmount

Element

Yes

Value of the tax applied.



hotelFees

Group

No

Grouping of all hotel fees for a given room

hotelFees

hotelFee

Group

No

Each hotel fee is within a hotelFee group

hotelFee

feeType

Element

No

There can be 0 or more hotelFee elements regardless of feeType. Values = Amenity, Cleaning, National Park Entrance, Resort, Security Deposit

hotelFee

feeMethod

Element

No

Values = Inclusive, Exclusive

hotelFee

requiredFee

Element

No

Values = Yes, No

hotelFee

feeAssign

Element

No

Values = Per Person, Per Room

hotelFee

feeFrequency

Element

No

Values = Per Stay, Per Night

hotelFee

feeBasedOn

Element

No

Values = PER, VAL (for percent, value)

hotelFee

feeBasedOnValue

Element

No

Decimal value: 00.00

hotelFee

salesTax

Element

No

If sales tax is included, the tax rate is listed.

hotelFee

conditions

Element

No

String - payment or fee conditions. Max length = 100 char

hotelFee

feeTotal

Element

No

Decimal value: 00.00 – the total fee as based on the fee rules

Availability Response - Hotel Fee XML Elements

  • Hotel Fees are returned per room.
  • Each room can have zero or more hotel fees regardless of the fee type. Some resort fees may be taxes sent by the hotel along with their dynamic rates.
  • The Hotel Fees are located here in our availability response:

availabilityResponse\hotelList\hotel\roomInformation\rateInformation\hotelFees

Below is a sample of the hotel fees elements that we return. In this case we are returning a resort fee that is required and exclusive for a total of $32.48 for the stay for the room it is listed under. We recommend only extracting and using the bold elements:

<hotelFees> <hotelFee> <feeType>Resort</feeType> <feeMethod>Exclusive</feeMethod> <requiredFee>Yes</requiredFee> <feeAssign>Per Room</feeAssign> <feeFrequency>Per Night</feeFrequency> <feeBasedOn>VAL</feeBasedOn> <feeBasedOnValue>32.48</feeBasedOnValue> <salesTax/> <conditions>paid locally by guest at checkout</conditions> <feeTotal>32.48</feeTotal> </hotelFee> </hotelFees>

Code Example

Assume an availability request was made for the City of Las Vegas (CY191), arrival on 12/01/2023, for a 2-night stay. The response demonstrates the XML that would be returned to the client if the request were only for a single hotel – where <hotelCode> is 1413.

Request





XML


Response

XML


Response Codes