Hotel API Specification June 2012
Example XML for Typical Usage
This API is designed to directly follow the typical behaviour and requirements of the end user. As such it gives the UI designer the fastest and simplest possible route to product, and enables them to focus on the UI design and not data processing or business logic. The following sample XML illustrates the most typical end-to-end user experiences and provides example XML for each step of that process.
Obtaining a login token (token is required for using any other XML API commands)
Entering a location (User enters their location as text and receives a list of possible locations matching that text)
Availability searching
Step 1) User selects a location and submits a search request along with required dates, rooms-list and duration
Step 2) User is shown the results received from the suppliers so far
Step 3) User requests next page of results, or filters or sorts the results
Step 4) User selects one of the hotels/ offers and is shown more details and alternate offers for that hotel
Other features:
Static links to hotels and results sets
Searching for Hotels and Related Offers
Request
<GetHotelsRequest sid="***" token="***" xmlns="http://www.travelfusion.com/xml/api/simple">
<location>
<!-- Submit only 1 of the following location identifiers -->
<city code="LON"/>
<airport code="LHR"/>
<hotel code="00005gaw87"/>
<coordinate lat="0.34234" lon="65.283"/>
<locationResolutionResultItem id="6296680"/>
</location>
<radius>xxx</radius> // in metres. If omitted, default logic will be used.
<date>2012-01-11</date>
<duration>7</duration>
<rooms>
<room>
<!-- The ages of the people that will be staying in the room -->
<ages>
<age>30</age>
<age>30</age>
<age>1</age>
</ages>
</room>
</rooms>
<!-- special parameters may be necessary in certain special cases. Please discuss with Travelfusion if you feel that you need to submit any extra information such as personal logins to supplier systems -->
<specialParameters>
<parameter type="supplier" name="_supplier_name_._param_name_">__some_value__</parameter>
</specialParameters>
</GetHotelsRequest>
Response
<GetHotelsResponse sid="xxx">
<!-- ‘supplierConnections’ is the number of data connections to suppliers, ‘completeConnections’ indicates how many supplier have responded so far, ‘totalResults' is the number of hotels found so far (i.e. items within the 'results' element below), ‘totalOffers' is the number of bookable offers found so far -->
<resultInfo completeConnections="51" supplierConnections="51" suppliers="8" totalResults="225" totalOffers="800">
<supplierResultInfo>
<supplier name="hotels.com" completeConnections="15" supplierConnections="21" totalResults="100"/>
<supplier name="booking.com" completeConnections="12" supplierConnections="30" totalResults="125"/>
</supplierResultInfo>
<!-- starResultInfo: indicate the number of offers and hotels per star rating -->
<starResultInfo>
<star value="1" totalOffers="120" totalResults="10"/>
<star value="2" totalOffers="130" totalResults="20"/>
<star value="3" totalOffers="90" totalResults="80"/>
<star value="4" totalOffers="80" totalResults="10"/>
<star value="5" totalOffers="50" totalResults="13"/>
</starResultInfo>
<!-- systemInfo: suppliers gives the total number of suppliers that are active for your account. numberOfHotels is the number of unique hotels covered by those suppliers -->
<systemInfo suppliers="10" numberOfHotels="500000"/>
</resultInfo>
<results>
<!-- 'code' is TF's internal identifier for this hotel. It will always be used to identify this hotel across all searches. The 'id' is a temporary id used to identify this result for use in the 'GetBookingIdsRequest' -->
<hotel code="00000000003F6C8F" id="1">
<hotelDetails>
<!-- Click here for details -->
</hotelDetails>
<!-- The supplierDescriptions element will only be returned when a specific hotel id is requested in the request location or filters. In this case all suppliers' descriptions will be returned in this list. -->
<supplierDescriptions>
<supplierDescription>
<supplier>hotelsdotcom</supplier>
<hotelDetails>
<!-- Click here for details -->
</shotelDetails>
</supplierDescription>
<supplierDescription>
...
</supplierDescription>
</supplierDescriptions>
<offers>
<offer id=”xxx”>
<billingPrice agentCommision="0.00" currency="EUR">2501.45</billingPrice>
<price agentCommision="0.00" currency="GBP">1501.45</price>
<supplier>hotelsdotcom</supplier>
<referralUrl>http://www.travelfusion.com/doreferral/?referralid=1AGSDJ3287</referralUrl>
<!-- DEPRECATED - Please use the rooms tag below instead -->
<roomTypes>
<!-- id attribute will only appear when extras are available for the hotel otherwise it will be omitted -->
<roomType id="1">DubbelRum</roomType>
<roomType id="2">EinkelRum</roomType>
</roomTypes>
<rooms>
<!-- id attribute will only appear when extras are available for the hotel otherwise it will be omitted -->
<room id="1">
<type>DubbelRum</type>
<tfType>Double</tfType>
<!-- extraInfos indicate additional information related to this room within the offer -->
<extraInfos>
<extraInfo name="terms-text: Cancellation Policy">Cancel up until noon on the date of arrival</extraInfo>
<extraInfo name="terms-text: Refund Policy">Non refundable</extraInfo>
</extraInfos>
</room>
<room id="2">
<type>EinkelRum</type>
<!-- extraInfos indicate additional information related to this room within the offer -->
<extraInfos>
<extraInfo name="terms-text: Cancellation Policy">Cancel up until noon on the date of arrival</extraInfo>
<extraInfo name="terms-text: Refund Policy">Non refundable</extraInfo>
</extraInfos>
</room>
</rooms>
<!-- the roomExtraOptions indicate special features available for some rooms -->
<roomExtraOptions>
<roomExtraOption id="1" type="Early Check In">
<price type="Room" currency="EUR">10.00</price>
<description>Early check in [from 12 noon] - Sometimes you may need to check in to your room early. Early check in allows you to check in from 12 noon to 2.30pm </description>
</roomExtraOption>
.....
<roomExtraOption id="4" type="Domestic Pet">
<price type="Room" currency=" EUR">40.00</price>
<description>2 domestic pets - You may bring up to 2 domestic pets (cats, dogs) with you on your stay. Guide dogs and Hearing dogs are exempt from this charge. </description>
</roomExtraOption>
</roomExtraOptions>
<!-- extraInfos indicate additional information related to the offers within the offer -->
<extraInfos>
<extraInfo name="terms-text: Cancellation Policy">Cancel up until noon on the date of arrival</extraInfo>
<extraInfo name="terms-text: Refund Policy">Non refundable</extraInfo>
</extraInfos>
</offer>
<offer id=”xxy”>
...
</offer>
</offers>
</hotel>
<hotel code="00000000003F6C8G" id="2">
...
</hotel>
<results>
<filters>
<filter code="hotelId" type="string"></filter>
<filter code="hotelCode" type="string"></filter>
<filter code="starts" type="enumeration">
<value selected="true" count="53">3</value>
<value selected="true" count="18">5</value>
<value selected="true" count="78">4</value>
</filter>
...
</filters>
<GetHotelsResponse>
Types of Search
Availability searching
If a date, duration and rooms-list are submitted in the request, then the response will contain a list of available hotels, each of which will contain a list of the best offer(s) available at the hotel. The offers for each hotel will be ranked, and the hotels will be ranked based on the best offer for each hotel. The hotels will be returned in pages, so a paging request must be used to get subsequent pages of data
Hotel-Only Searching
If date, duration or rooms-list is omitted, a geographical search will be done for hotels in the specified location/ area. The response will be similar to the availability search, but there will be no offers within each hotel. The hotels will be ranked based on information related to the hotel itself - e.g. cheapest known price, distance from required location.
Hotel Details Request
If a specific hotel is requested in the request 'location' or filters, without a radius, more details of that hotel will be returned, for example all fields of the HotelDetails element and also the SupplierDescriptions element. More offers will also be returned (assuming it is an availability search). The offers will be returned in pages, so a paging request can be used to get subsequent pages of data.
Result Modification
There are various modifications that can be applied to a result. These modifications can all be applied at the same time as performing the original search by submitting the relevant elements alongside the search parameters. Or alternatively they can be submitted after the results have been obtained, as long as a session id is submitted (sid). See the 'Example XML for Typical Usage' section above for real usage examples.
The various modifiers are:
Polling for Latest Results
Currencies
Paging Results
Ranking of results
These are all but filtering described in detail here
Booking (Get Booking Ids For Offer)
In order to book a hotel offer, you will first need to obtain the 'booking ids' for the offer. You can do this as follows:
Request
<GetBookingIdsRequest sid="***" token="***" xmlns="http://www.travelfusion.com/xml/api/simple">
<id name="hotelId" value="3"/>
<id name="offerId" value="74">
<!-- optional element only to be submitted when extras are returned for a hotel in GetHotelsResponse -->
<!-- multiple rooms can be specified, each with multiple 'extras' -->
<id name="roomId" value="2">
<id name="extraId" value="4"/>
</id>
</id>
</GetBookingIdsRequest>
Response
<GetBookingIdsResponse>
<id name="xmlLoginId" value="ABc12345"/>
<id name="loginId" value="ABc12346"/>
<id name="routingId" value="Z1DXW72E04KTDAS8"/>
<id name="optionId" value="QKK4YY022TE7DWL8"/>
<id name="roomId" value="1">
<id name="extraId" value="QKK4YY022TE7DWL8"/>
</id>
</GetBookingIdsResponse>
These 4 ids can then be submitted to our booking API here.
Previous Specification
Prior to June 2012, a different specification was in use. This has been deprecated but some parts of it are still relevant to the prepackaged API. Link to previous spec.