Availability Search

14 min

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:

/GetAvailability.do

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	Yes	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 (No longer supported for new integrations)	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	Yes	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 version="1.0" encoding="utf-8" ?>
<availabilityRequest cancelpolicy="Y" hotelfees="Y">
	<control>
		<userName>Username</userName>
		<passWord>Password </passWord>
	</control>
	<checkIn>10-OCT-2015</checkIn>
	<checkOut>12-OCT-2015</checkOut>
	<noOfRooms>2</noOfRooms>
	<noOfNights>2</noOfNights>
	<city></city>
	<hotelCodes>
		<hotelCode>108</hotelCode>
	</hotelCodes>
	<roomsInformation>
		<roomInfo>
			<roomTypeId>4</roomTypeId>
			<bedTypeId>5</bedTypeId>
			<adultsNum>1</adultsNum>
			<childNum>1</childNum>
			<childAges>
				<childAge>8</childAge>
			</childAges>
		</roomInfo>
		<roomInfo>
			<roomTypeId>0</roomTypeId>
			<bedTypeId>0</bedTypeId>
			<adultsNum>1</adultsNum>
			<childNum>0</childNum>
		</roomInfo>
	</roomsInformation>
</availabilityRequest>

Example 2: Multiple Hotel Code Search

<?xml version="1.0" encoding="utf-8" ?>
<availabilityRequest cancelpolicy="Y" hotelfees="Y">
	<control>
		<userName>*****</userName>
		<passWord>*****</passWord>
	</control>
	<checkIn>21-Mar-2018</checkIn>
	<checkOut>23-Mar-2018</checkOut>
	<noOfRooms>1</noOfRooms>
	<noOfNights>2</noOfNights>
	<city></city>
	<hotelCodes>
		<hotelCode>108</hotelCode>
		<hotelCode>108</hotelCode>
	</hotelCodes>
	<roomsInformation>
		<roomInfo>
			<roomTypeId>0</roomTypeId>
			<bedTypeId>0</bedTypeId>
			<adultsNum>2</adultsNum>
			<childNum>0</childNum>
			<childAges/>
		</roomInfo>
	</roomsInformation>
</availabilityRequest>

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 version="1.0" encoding="utf-8" ?>
<availabilityRequest cancelpolicy="Y" hotelfees="Y">
	<control>
		<userName>*****</userName>
		<passWord>*****</passWord>
	</control>
	<checkIn>21-Mar-2018</checkIn>
	<checkOut>23-Mar-2018</checkOut>
	<noOfRooms>1</noOfRooms>
	<noOfNights>2</noOfNights>
	<city>CY191</city>
	<hotelCodes/>
	<roomsInformation>
		<roomInfo>
			<roomTypeId>0</roomTypeId>
			<bedTypeId>0</bedTypeId>
			<adultsNum>2</adultsNum>
			<childNum>0</childNum>
			<childAges/>
		</roomInfo>
	</roomsInformation>
</availabilityRequest>

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:

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	policyDescription	Element	Yes	A crucial field that communicates information about restrictions and policies that affect eligibility for confirming a reservation. Customers are expected to abide by this information prior to confirming a booking. Any booking confirmed that is in conflict to the stated information will be subject to cancellation and/or penalty.
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	Yes	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	Yes	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	Yes	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	Yes	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	Yes	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	Yes	Grouping of all hotel fees for a given room
hotelFees	hotelFee	Group	Yes	Each hotel fee is within a hotelFee group
hotelFee	feeType	Element	Yes	There can be 0 or more hotelFee elements regardless of feeType. Values = Amenity, Cleaning, National Park Entrance, Resort, Security Deposit
hotelFee	feeMethod	Element	Yes	Values = Inclusive, Exclusive
hotelFee	requiredFee	Element	Yes	Values = Yes, No
hotelFee	feeAssign	Element	Yes	Values = Per Person, Per Room
hotelFee	feeFrequency	Element	Yes	Values = Per Stay, Per Night
hotelFee	feeBasedOn	Element	Yes	Values = PER, VAL (for percent, value)
hotelFee	feeBasedOnValue	Element	Yes	Decimal value: 00.00
hotelFee	salesTax	Element	Yes	If sales tax is included, the tax rate is listed.
hotelFee	conditions	Element	Yes	String - payment or fee conditions. Max length = 100 char
hotelFee	feeTotal	Element	Yes	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

/GetAvailability.do

<?xml version="1.0" encoding="utf-8" ?>
<availabilityRequest cancelpolicy="Y" hotelfees="Y">
	<control>
		<userName>Username</userName>
		<passWord>Password</passWord>
	</control>
	<checkIn>01-Dec-2023</checkIn>
	<checkOut>03-Dec-2023</checkOut>
	<noOfRooms>1</noOfRooms>
	<noOfNights>2</noOfNights>
	<city>CY191</city>
	<hotelCodes>
		<hotelCode>1</hotelCode>
	</hotelCodes>
	<roomsInformation>
		<roomInfo>
			<roomTypeId>246</roomTypeId>
			<bedTypeId>10</bedTypeId>
			<adultsNum>2</adultsNum>
			<childNum>0</childNum>
			<childAges/>
		</roomInfo>
	</roomsInformation>
</availabilityRequest>

Response

<?xml version="1.0" encoding="utf-8" ?>
<availabilityResponse status="Y">
	<hotelList>
		<hotel>
			<hotelCode>1</hotelCode>
			<name>Bellagio</name>
			<address>3600 Las Vegas Boulevard South</address>
			<city>Las Vegas</city>
			<stateProvince>Nevada</stateProvince>
			<country>USA</country>
			<postalCode>89109</postalCode>
			<rateCurrencyCode>USD</rateCurrencyCode>
			<shortDescription>Text Description</shortDescription>
			<starRating>5.5star</starRating>
			<thumbNailUrl>url here</thumbNailUrl>
			<hotelUrl>url here</hotelUrl>
			<maintenance/>
			<bookingPolicy> </bookingPolicy>
			<policyDescription><![CDATA[  general policy text  ]]></policyDescription>
			<roomInformation>
				<roomNo>1</roomNo>
				<roomCode>1385</roomCode>
				<roomTypeCode>246</roomTypeCode>
				<roomType>1 Bedroom Penthouse Suite</roomType>
				<roomDescription/>
				<bedTypeCode>10</bedTypeCode>
				<bedType>Double</bedType>
				<stdAdults>2</stdAdults>
				<promotionCode>Discounted Rates</promotionCode>
				<confirmationType>CON</confirmationType>
				<confirmationConditions/>
				<roomBookingPolicy>
					<policyFrom>2008-04-01</policyFrom>
					<policyTo>2025-12-31</policyTo>
					<amendmentType>Cancel</amendmentType>
					<policyBasedOn>nights</policyBasedOn>
					<policyBasedOnValue>1</policyBasedOnValue>
					<cancellationType>Normal</cancellationType>
					<stayDateRequirement>N</stayDateRequirement>
					<arrivalRange>Less Than</arrivalRange>
					<arrivalRangeValue>4</arrivalRangeValue>
					<policyFee>$531.96</policyFee>
					<noShowBasedOn>nights</noShowBasedOn>
					<noShowBasedOnValue>1</noShowBasedOnValue>
					<noShowPolicyFee>$531.96</noShowPolicyFee>
				</roomBookingPolicy>
				<rateInformation>
					<ratePlanCode>1</ratePlanCode>
					<ratePlan>Room Only</ratePlan>
					<averageRate>631.00</averageRate>
					<totalRate>1,262.01</totalRate>
					<dailyRates>
						<nightlyRate date="01-Dec-2023" dailyCondition="">
							<stdAdultRate>531.96</stdAdultRate>
							<additionalAdultRate>0.00</additionalAdultRate>
							<total>531.96</total>
							<rateCode/>
						</nightlyRate>
						<nightlyRate date="02-Dec-2023" dailyCondition="">
							<stdAdultRate>730.05</stdAdultRate>
							<additionalAdultRate>0.00</additionalAdultRate>
							<total>730.05</total>
							<rateCode/>
						</nightlyRate>
					</dailyRates>
					<taxInformation>
						<tax taxName="roomTax">
							<taxAmount>0.0</taxAmount>
						</tax>
						<tax taxName="salesTax">
							<taxAmount>0.0</taxAmount>
						</tax>
						<tax taxName="otherCharges">
							<taxAmount>0.0</taxAmount>
						</tax>
					</taxInformation>
					<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>
				</rateInformation>
			</roomInformation>
		</hotel>
	</hotelList>
</availabilityResponse>

Response Codes

Code	Description
A1	Unspecified error. Please contact customer support.
A2	User ID not supplied or not valid
A3	Incorrect Hotel ID or City was requested.
A4	Arrival or Departure Date format incorrect.
A5	Number of rooms requested is greater than the number of Adults.
A6	Inventory not Available for the specified search criteria.
A7	Erroneous or Incomplete Data in Availability Request.
A8	No of child is not matching the child ages details provided.
A9	No of rooms or No of nights requested is zero.
A10	No of rooms is not matching with No of Room Info.
A11	No XML input detected.
A12	The number of nights does not match the check in date and the check out date.
A13	(Deprecated)
A14	(Deprecated)
A15	(Deprecated)
A16	The service has been temporarily suspended.
A17	Service not available.
A18	(Deprecated)
A19	Check in date should not be a past date!
A20	Too many connections from your account. Please try again in a few minutes time
A21	Your account is exceeding our rate limit per second. Please throttle your requests.
A22	Timeout
A23	HTTP error, this could be in the request or the response.