Hotel API Specification October 2011

API Commands Available:

*********************************************************************************

Important note: This version of the API is deprecated and must not be used.

*********************************************************************************

City map hotel browsing

This API call is used to get a list of all the hotels in a particular area or city, for the purpose of displaying them all to the user on a map with some general information about each one.

Request

<GetAllHotelsInAreaRequest>

<!-- Specify just 1 of the following elements: -->

<area lat="51.514538" lon="-0.124394" radius="10000"/>

<city code="LON" radius="10000"/>

<hotelId>123456</hotelId>

<locationID id="6618994" radius="10000"/>

<!-- If returnAllHotels is set to true, all hotels in the area will be returned, ranked and paged. Otherwise a selection of the best hotels will be returned in a single response, giving a good map coverage and

indicating how many hotels have been hidden close to each returned hotel -->

<returnAllHotels>true</returnAllHotels>

</GetAllHotelsInAreaRequest>

If hotelId is supplied, will return the details of that hotel only. There is not logical reasons to submit this, but it can sometimes simplify the interaction with the API.

If an area is provided, it must have a radius.

If a city is provided, the radius is optional and if it is not supplied, this will indicate that all results should have a logical association with that city, not necessarily a geographical one.

'locationID' refers to a location returned in the location resolution response.

Radius is in metres. Maximum radius is 30000. In reality, the hotels returned will be within a coordinate box, containing the circle defined by the radius (so, some hotels returned may be outside the circle.)

Response

<GetAllHotelsInAreaResponse sid="ZWSRH3EBfLees7rr">

<hotels>

<hotel>

<!-- Follows the specification for the 'hotel' element in the GetLiveHotelOffersResponse below. Some elements will be omitted for efficiency (e.g. description, facility list, images etc) -->

</hotel>

<hotel>

....

</hotel>

</hotels>

</GetAllHotelsInAreaResponse>

Note that not all relevant hotels will be returned. Where hotels are very close together, only the best will be returned (based on the cheapest known offer from the hotel)

Get Live Hotel Offers

This API call is used to obtain live availability and pricing for all hotels in a particular area or city. Note that when submitted, the initial response is likely to return no results, as Travelfusion will still be waiting for our suppliers to return data. You need to poll every few seconds to get updates. Please see the details of polling below.

Request

<GetLiveHotelOffersRequest>

<!-- Specify just 1 of area or city or locationID-->

<area lat="51.514538" lon="-0.124394" radius="10000"/>

<locationID id="6618994" radius="10000"/>

<city code="LON" radius="10000"/>

<date>2012-01-11</date>

<duration>7</duration>

<groupByHotel>false</groupByHotel>

<rooms>

<room>

<adults>2</adults>

<children>1</children>

</room>

</rooms>

<currency>EUR</currency> <!-- defines the currency in which all results should be returned. If omitted, the currency will be that returned by the supplier -->

<hotelId>0000000000236808</hotelId>

</GetLiveHotelOffersRequest>

Radius is in metres. Maximum radius is 30000.

'locationID' refers to a location returned in the location resolution response.

Response

<GetLiveHotelOffersResponse sid="ZWSRH3EBfLees7rr">

<offers completeConnections="0" supplierConnections="595" suppliers="17" totalOffers="0">

<liveHotelOffer id="74">

<!-- The hotel element defines the relevant supplier's details for the hotel. If a specific hotel is requested in the search or filters, this element will be omitted, and the supplierHotelDescriptions element supplied instead (see below).

If a specific hotel is not requested, some of this data will be omitted and only the key items returned to enable on-screen comparison of the offers whilst minimising data sizes -->

<hotel id="124356">

<!-- You can not utillise tripadvisor data unless you have a direct agreement with trip advisor. Please contact travelfusion if you wish to activate this data for your account. -->

<tripAdvisor>

<ranking>4.5</ranking>

<reviews>57</reviews>

<url>www.tripadvisor.com/4578284</url>

</tripAdvisor>

<priceInfo> <!-- These stats could apply to all room types or just double room -->

<numberOfPricesReceived>4382</numberOfPricesReceived>

<averagePrice currency="EUR">80</averagePrice>

<minPrice currency="EUR">30</minPrice>

</priceInfo>

<starRating>3.0</starRating>

<hotelName>LOOIER</hotelName>

<coordinate lat="51.514538" lon="-0.124394"/>

<description>Nice place. No roof. Pool is in lobby. </description>

<address>34 Long Lane, London Bridge, SE1 4NH, GB </address>

<addressDetails>

<streetAddress>34 Long Lane</streetAddress>

<postalCode>SE1 4NH</postalCode>

<country>GB</country>

<province/>

<city>London Bridge</city>

<region/>

</addressDetails>

<thumbNail>travelfusion.com/image738473.jpg</thumbNail>

<images>

<image description="lobby" thumbURL="www.hotels.com/thumbs/1234">hotels.com/img/1234</image>

<image description="pool" thumbURL="www.hotels.com/thumbs/1234">hotels.com/img/1234b</image>

</images>

<facilities>

<!-- The facilities will either be from the following list of 'known' facilities, or they will be free text: Internet, Wheel chair, Fitness facility, Bar, Pool, Pets permitted, Air conditioning, Handicap accessible,

Restaurant, Children pool, Lift, Child care, Child activity, Meeting facility, Banquet facility, Room service, Kitchen, Parking, Breakfast, Cancellation policy -->

<!-- The 'type' attribute contains the symbolic value from the list above, or is omitted if the facility is unrecognised. The 'details' is the text for display to the user. -->

<facility type="Breakfast" availability="Available" details="Breakfast">

</facilities>

<extraInfos>

<extraInfo name="Andra aktiviteter">Tennis, Golf, Beach volley...</extraInfo>

<extraInfo name="Faciliteter">Reception, Hyrbil, Lobby, Bagageförvaring, Deponering på rummet, Butik, Souvenirbutik, Luftkonditionering i allmänna utrymmen, Internet i allmänna utrymmen, Internet på rummet</extraInfo>

</extraInfos>

</hotel>

<hotelOffers>

<!-- Will contain just 1 offer if 'groupByHotel' is false in the GetLiveHotelOffersRequest. Otherwise, will contain all offers for this hotel, ranked according to the ranking parameters -->

<hotelOfferDetails>

<roomType>DubbelRum</roomType>

<price currency="EUR">2501.45</price>

<supplier>hotelsdotcom</supplier>

<referralUrl>http://www.travelfusion.com/doreferral/?referralid=1AGSDJ3287</referralUrl>

</hotelOfferDetails>

<hotelOfferDetails>

......

</hotelOfferDetails>

</hotelOffers>

</liveHotelOffer>

<liveHotelOffer id="29">

......

</liveHotelOffer>

</offers>

<!-- The supplierHotelDescriptions element will only be returned when a specific hotel id is requested. In this case all suppliers' descriptions will be returned in this list. -->

<supplierHotelDescriptions>

<supplierHotelDescription>

<supplier>hotelsdotcom</supplier>

<hotel ....>

<!-- follows the hotel element definition above -->

</hotel>

</supplierHotelDescription>

</supplierHotelDescriptions>

<filters>

<filter id="hotelName" type="text">

<filter id="priceMin" type="number" min="25" max="100">

<filter id="priceMax" type="number" min="25" max="100"/>

<filter id="stars" type="number" min="0" max="5"/>

<filter id="tripadvisorRatingMin" type="number" min="0" max="5"/>

<filter id="tripadvisorRatingMax" type="number" min="0" max="5"/>

<filter id="facility" type="text">

<values>

<value>Wheelchair</value>

<value>Parking</value>

</values>

</filter>

<filter id="supplier" type="text">

<values>

<value>Hotelsupplier1</value>

<value>Hotelsupplier2</value>

</values>

</filter>

</filters>

</GetLiveHotelOffersResponse>

Polling, Paging, Ranking, Filtering and Usage

Please Read the Flights API specification for details of polling, paging, ranking and usage, which are achieved in a similar way for hotels. The only difference is that different ranking 'parameters' are offered for hotels. The following 4 are supported:

<mostPopularWeight>0.8</mostPopularWeight> // (use statistics to get the monthly number of referrals to each hotel etc)

<priceWeight>1.0</priceWeight>

<tripAdvisorRankingWeight>0.5<tripAdvisorRankingWeight>

<starRatingWeight>0.0</starRatingWeight>

<!--DEPRECATED: distanceFromCityWeight>0.3</distanceFromCityWeight-->

If any of these weights is omitted, the value used will be as in the example above/

Also, various filters can be applied as follows. (The various filter options can be generically extracted from the initial search response)

Filtering can only be submitted in the 'GetLiveHotelOffersRequest' request, not 'GetAllHotelsInAreaRequest'.

<filters>

<filter id="hotelId">123456</filter>

<filter id="hotelName">Marriot Bristol</filter>

<filter id="priceMin" currency="NOK">10000</filter>

<filter id="priceMax" currency="NOK">10000</filter>

<filter id="stars">3</filter>

<filter id="tripadvisorRatingMin">3</filter>

<filter id="tripadvisorRatingMax">5</filter>

<filter id="facility">wheelchair</filter>

<filter id="supplier">hotelsupplier</filter>

</filters>

Get Hotel Offer Details (Currently deprecated)

This request is designed to be made after the user has selected a specific offer or hotel, and would like more details. It should not be submitted for all hotels in a result. Please discuss with Travelfusion if you wish to make more than 1 HotelDetails request per user-action.

Request:

[

Provisionally deprecated spec

<GetHotelOfferDetailsRequest sid="ZWSRH3EBfLees7rr">

<offerId>123432</offerId>

</GetHotelOfferDetailsRequest>

]

[

Provisionally deprecated spec

<GetHotelOfferDetailsRequest sid="ZWSRH3EBfLees7rr">

<hotelId>123432</hotelId>

<checkinDate>16/6/2010</checkinDate>

<duration>14</duration>

</GetHotelOfferDetailsRequest>

]

Response:

[

Provisionally deprecated spec

<GetHotelOfferDetailsResponse sid="ZWSRH3EBfLees7rr">

<liveHotelOffer>

<!-- The liveHotelOffer element follows the same specification as the liveHotelOffer element defined in the GetLiveHotelOffersResponse above, as if the 'groupByHotel' option had been set to 'true' in the GetLiveHotelOffersRequest -->

</liveHotelOffer>

</GetHotelOfferDetailsResponse>

]

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:

<GetBookingIdsForOfferRequest sid="ZWSRH3EBfLees7rr">

<offerId>74</offerId>

</GetBookingIdsForOfferRequest>

Response:

<GetBookingIdsForOfferResponse>

<id name="xmlLoginId">ABc12345</id>

<id name="loginId ">ABc1234</id>

<id name="routingId">Z1DXW72E04KTDAS8</id>

<id name="optionId">QKK4YY022TE7DWL8</id>

</GetBookingIdsForOfferResponse>

These 4 ids can then be submitted to our booking API here.