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 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 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 \<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 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 \<?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