Hotel API Specification June 2012 >
Hotel API Specification June 2012 >
IMPORTANT: The GetHotelsRequest will always respond immediately, and will return the best offers received from suppliers so far (therefore the first response may contain no offers at all). If the completeConnections is less than thesupplierConnections, then a polling request can be submitted to receive any new offers that have been returned by the various suppliers. You should not submit this 'polling' request more often that every 3 seconds, and you should always stop polling when either all results have been returned or when a certain timeout is reached (e.g. after 1 minute). Note that for requests that return no offers such as 'Hotel-Only Searching', there will be no need to poll.
To poll for the latest offers, the GetHotelsRequest can be submitted, without any parameters. The 'sid' that was received in the first response must be submitted as follows:
<GetHotelsRequest sid="ZWSRH3EBfLees7rr"/>
By default, all prices will be returned in the currency in which it was provided to Travelfusion. This means that in principle various different currencies may feature in the same response. If you wish to request all prices in a fixed specific currency, the 'currency' element should be submitted as below. The currency element can also be submitted with the original request to avoid sending a second request to change the currency.
<GetHotelsRequest sid="ZWSRH3EBfLees7rr">
<currency>EUR</currency>
</GetHotelsRequest>
By default, the best 10 offers are returned. This can be changed by submitting the ‘paging’ element described below. The paging element can also be submitted with the original request to avoid sending a second request to change the page size.
<GetHotelsRequest sid="ZWSRH3EBfLees7rr">
<paging>
<pageNumber>2</pageNumber> <!-- Requests the second page of results -->
<offersPerPage>5</offersPerPage> <!-- Specifies the number of offers on each page -->
</paging>
</GetHotelsRequest>
Travelfusion may not support 'page-skipping'. i.e. you may not be able to view page X without viewing page (X-1) first.
Note that all requests to the service must represent actual user actions and requirements. Therefore the page size requested should not exceed what a user can actually reasonably view, and extra pages should only be requested if the user does so themself.
By default, the offers are ordered in a best-to-worst-order defined by Travelfusion. To change the ranking parameters of this ordering, the importance (weighting) of each criteria for sorting can be specified as below.
<GetHotelsRequest sid="ZWSRH3EBfLees7rr">
<rankingParameters>
<mostPopularWeight>0.2</mostPopularWeight> // (use statistics to get the monthly number of referrals to each hotel etc)
<priceWeight>1.0</priceWeight>
<tripAdvisorRankingWeight>0.2</tripAdvisorRankingWeight>
<starRatingWeight>0.2</starRatingWeight>
<distanceFromLocationWeight>0.6</distanceFromLocationWeight>
</rankingParameters>
</GetHotelsRequest>
If some of the weights are omitted, the value assumed for those weights will be 0. If they are all omitted, default (Travelfusion defined) values will be used for them all.
Weights must be between 0 and 1 and indicate the relative importance of each feature of the offers. Offers are ranked according to these weights and features.
When using Currencies, Paging, Ranking or Filtering, any previously submitted values must be submitted in every request for results or the settings will be lost.
For example, if the user asks to sort by starRating, a request like this would be submitted:
<GetHotelsRequest sid="ZWSRH3EBfLees7rr">
<rankingParameters>
<starRatingWeight>1</starRatingWeight>
</rankingParameters>
</GetHotelsRequest>
However if the user then wishes to filter all results over £1000 but retaining the above sorting, the following XML would be needed:
<GetHotelsRequest sid="ZWSRH3EBfLees7rr">
<rankingParameters>
<starRatingWeight>1</starRatingWeight>
</rankingParameters>
<filters>
<filter code="priceMax" currency="GBP">1000</filter>
</filters>
</GetHotelsRequest>