Prepackaged API Spec

API Commands Available:

Get Prepackaged Offers

Request

This request is used to specify filters on the entire prepackaged database in order to reduce the data to the subset that is relevant to the user. The response includes a list of all the filters that should be displayed to the end user. Any number of filters of any kind can be submitted and if none are submitted, all the offers in the database will be returned (in pages).

In each filter item, an 'id' is supplied, which can be used to actually apply this filter. The id may contain any characters following the general XML specifications for attribute values.

An 'offers' attribute indicates how many of the parent-filter's offers are related to this child filter value, (given all the other specified filters).

A 'parent' attribute indicates which is the parent filter of this filter (if it has a parent) - e.g. which country contains this region.

A 'selected' attribute (which is false is not supplied). Indicates that this item was selected in the preceding request.

When any filter is selected, some of its sibling filters will be returned, but not necessarily all of them. For example when a month is selected, only the neighbouring months may be returned. Some of the filters are hierarchical. In these cases, initially only the top level filters will be returned (e.g. just months). Then, when the user selects a filter, all the child filters of the selected month will be returned, and so on. The offers returned will always correspond to the selected leaf filters, so if June and July are selected, and also the second week of July, then the offers returned will be all those in June and all those in the second week of July only. Note that the hierarchy is not strong. For example, some resorts may not be associated with a parent region, but instead with a parent country.

The following empty request will return all possible filters and all available offers.

<GetPrepackagedOffersRequest>

<!-- DEPRECATED groupByHotel-->

<!--groupByHotel>false</groupByHotel--><!-- selects whether to group results by hotel or to separate all offers completely -->

<!-- the grouping functions are ignored/ not supported when a hotel id is specified - see the 'Filtering' section below -->

<groupByHotelAndSupplier>false</groupByHotelAndSupplier><!-- selects whether to group results by hotel-supplier or to separate all offers completely -->

<currency>EUR</currency>

</GetPrepackagedOffersRequest>

Response

The response contains a list of the available filters, and then a list of all relevant offers. Example:

<GetPrepackagedOffersResponse sid="ZWSRH3EBfLees7rr">

<filters>

<group type="destRegTop" union="destinationLocations">

<!-- This lists the top level regions offered. This is normally a country except for special cases such as the Canary Islands -->

<filter offers="26691634" id="destRegTop.IT">Italy</filter>

<filter offers="2669163" id="destRegTop.ES" selected="true">Spain</filter>

<filter offers="26691639" id="destRegTop.Canaries">Canary Islands</filter>

</group>

<group type="destRegMid" union="destinationLocations">

<!-- Lists the sub-regions (mid-regions) that are children of the top level regions selected in the requested filters -->

<filter offers="266916" id="destRegMid.Balearics" parent="destRegTop.ES" selected="true">Balearics</filter>

<filter offers="194498" id="destRegMid.Thesouth" parent="destRegTop.ES" selected="true">The South</filter>

<filter offers="194488" id="destRegMid.CostadelSol" parent="destRegTop.ES">Costa del Sol</filter>

</group>

<group type="destRegBot" union="destinationLocations">

<!-- Lists the sub-regions (bottom-regions) that are children of the mid level or top level regions selected in the requested filters -->

<filter offers="266916" id="destRegBot.Mallorca" parent="destRegMid.Balearics" selected="true">Mallorca</filter>

<filter offers="194498" id="destRegBot.Menorca" parent="destRegMid.Balearics" selected="true">Menorca</filter>

</group>

<group type="destRes" union="destinationLocations">

<!-- Lists the resorts that are direct children of any top, mid or bottom regions selected in the requested filters -->

<filter offers="26691" id="destRes.PlayadelIngles" parent="destReg.Balearics">Playa del Ingles</filter>

<filter offers="19449" id="destRes.PlayadelasAmericas" parent="destReg.Thesouth">Playa de las Americas</filter>

</group>

<group type="origCoun" union="originLocations">

<!-- Lists all the origin countries offered -->

<filter offers="618639" id="origCoun.SV">Sweden</filter>

<filter offers="466670" id="origCoun.NO">Norway</filter>

</group>

<group type="origCit" union="originLocations">

<!-- Lists the cities related to any origincountries selected in the requested filters -->

<filter offers="61863" id="origCit.GOT" parent="origCoun.SV">Gothenberg</filter>

<filter offers="46667" id="origCit.OSL" parent="origCoun.NO">Oslo</filter>

</group>

<group type="origApt" union="originLocations">

<!-- Lists the airports that are children to any origincities or origin countries selected in the requested filters -->

<filter offers="61863" id="origApt.ARN" parent="origCit.GOT">Arlanda</filter>

<filter offers="46667" id="origApt.GOT" parent="origCit.GOT">Gothenberg</filter>

<filter offers="32689" id="origApt.OSL" parent="origCit.OSL">Oslo</filter>

</group>

<group type="depMon" union="departureDates">

<!-- Lists all the possible departure months offered -->

<filter offers="374127" id="depMon.2012-03">2012-03</filter>

<filter offers="320302" id="depMon.2012-01">2012-01</filter>

</group>

<group type="depWk" union="departureDates">

<!-- Lists all the possible departure weeks that are children of the selected months. Note that where a week is split across 2 months, it is broken into 2 separate partial weeks -->

<filter offers="87680" id="depWk.2012-1-4w" parent="depMon.2012-01">2012-4</filter>

<filter offers="84777" id="depWk.2012-1-5w" parent="depMon.2012-01">2012-5</filter>

<filter offers="84777" id="depWk.2012-2-5w" parent="depMon.2012-02">2012-5</filter>

</group>

<group type="depDay" union="departureDates">

<!-- Lists all the possible departure dates that are children of the selected weeks -->

<filter offers="44217" id="depDay.2012-03-28" parent="depWk.16">2012-03-28</filter>

<filter offers="31684" id="depDay.2012-03-29" parent="depWk.16">2012-03-29</filter>

</group>

<group type="trpWks" union="tripDurations">

<!-- Lists all the possible trip durations in weeks -->

<filter offers="374127" id="trpWks.1">1</filter>

<filter offers="320302" id="trpWks.2">2</filter>

</group>

<group type="trpDays" union="tripDurations">

<!-- Lists all the possible trip durations in days, that are within the selected weeks -->

<filter offers="37412" id="trpDays.8" parent="trpWks.2">8</filter>

<filter offers="3741" id="trpDays.10" parent="trpWks.2">10</filter>

</group>

<group type="prcRan">

<!-- Lists all the possible price ranges that are available in EUR (max value is non-inclusive)-->

<filter offers="1464095" id="prcRan.1000-1100">1000 - 1100 EUR</filter>

<filter offers="835669" id="prcRan.1100-1200">1100 - 1200 EUR</filter>

<filter offers="310254" id="prcRan.1200-1300">1200 - 1300 EUR</filter>

</group>

<group type="supp">

<!-- Lists all the possible vendors that are available -->

<filter offers="1037501" id="supp.VINGSE">Ving</filter>

<filter offers="837099" id="supp.APOLLOSE">Apollo</filter>

</group>

<group type="star">

<!-- Lists all the possible star ratings that are available. Partial ratings will be rounded down -->

<filter offers="113121" id="star.1">1</filter>

<filter offers="1131234" id="star.2">2</filter>

</group>

<group type="facil">

<!-- Lists all the possible facilities that are available. -->

<filter offers="11321" id="facil.swimmingpool">Swimming Pool</filter>

<filter offers="111234" id="facil.helipad">Helipad</filter>

</group>

<group type="offerType">

<!-- Lists all the possible types of prepackaged offer available -->

<filter offers="11321" id="offerType.lmsSpec">Last Minute Packages With Known Hotel</filter>

<filter offers="113821" id="offerType.lmsUnSpec">Last Minute Deals With Unknown Hotel</filter>

<filter offers="118321" id="offerType.lmsFlight">Last Minute Deals For Flight Only</filter>

<filter offers="113281" id="offerType.regular">Conventional Prepackaged Holidays</filter>

</group>

</filters>

<freeTextFilters>

<!-- the hotel details free text search will only allow offers where the hotel contains the specified (whole word(s)) string in its description or name. If multiple free text filters are specified, offers that match any of them will be returned -->

<freeTextFilter id="freeText.hotelDescription">Hotel Description</freeTextFilter>

<freeTextFilter id="freeText.hotelName">Hotel Name</freeTextFilter>

<freeTextFilter id="freeText.region">Destination Region</freeTextFilter>

<freeTextFilter id="freeText.resort">Destination Resort</freeTextFilter>

<freeTextFilter id="freeText.country">Destination Country</freeTextFilter>

<freeTextFilter id="freeText.month">Month of Trip</freeTextFilter>

</freeTextFilters>

<offers totalResults="789">

<prepackagedOfferGroup totalOffers="123">

<!-- if the hotel element is not supplied, then this offer is flight only (unless you requested a specific hotel in the filters). If the hotel element is supplied but without id (or any child elements), then this indicates the hotel is unknown for this offer -->

<hotel ....>

<!-- follows the hotel element definition in the 2011 hotel specification -->

</hotel>

<offersForHotel>

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

<offerForHotel>

<roomType>DubbelRum</roomType>

<!-- The price is for 2 adults -->

<price currency=”EUR”>300</price>

<supplier>ving</supplier>

<!-- Note that the number of nights is equivalent in value to the trpDays filter. So if you want offers of 15 nights, you should submit 15 in the trpDays filter. -->

<numberOfNights>15</numberOfNights>

<dateOfFlight>2012-06-16 17:25</dateOfFlight>

<dateOfReturnFlight>2011-12-13 14:15</dateOfReturnFlight>

<departureAirportLocation>Stockholm, Sweden</departureAirportLocation>

<location>Playa del Ingles, Mallorca, Spain</location>

<!-- the origin and destination may have type 'city' or 'airport". This will depend on the data provided by the supplier. If the type is city, then the exact airport is not provided -->

<origin type="airport" code="OSL">Oslo Gardenmowing</origin>

<destination type="city" code="BCN">Barcelona</destination>

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

<offerForHotel>

</offersForHotel>

</prepackagedOfferGroup>

</offers>

<supplierHotelDescriptions>

<!-- See Hotel API spec for more details of this element -->

</supplierHotelDescriptions>

</GetPrepackagedOffersResponse>

Filtering

The 'union' attribute identifies filters that will be joined by union to combine the related offers satisfying any of the leaf filters in the union (e.g. you can specify Mallorca region and France country, and get all the offers in France plus all the offers in Mallorca). Any filters that are not in the same union will be intersected, so only offers matching all of the filters will be returned. If no filter is submitted for a particular group, it will be treated as if all possible filters had been specified for that group. A filter will always be unioned with itself (e.g. if you ask for offers in France and in Germany you will get all offers in either country).

<GetPrepackagedOffersRequest sid="ZWSRH3EBfLees7rr">

<groupByHotelAndSupplier>false</groupByHotelAndSupplier>

<currency>EUR</currency>

<filters>

<filter id="destCoun.IT"/>

<filter id="facil.helipad"/>

<!-- the showall attribute will cause all the possible values of the specified filters that would give offers when combined with this filter only. For example, the below filter means that all the countries and facilities will be returned that can be found in offers for the supplier ving. -->

<filter id="supp.ving" showall="destCoun,facil"/>

<!-- This is a special filter. It is the only filter that will NOT RETURN THE POSSIBLE FILTER OPTIONS IN THE RESPONSE. It is used to specify a single hotel, in order to get all the offers for that hotel. -->

<!-- When a hotel id is specified, the grouping options are not allowed/ ignored (groupByHotelAndSupplier and groupByHotel). Instead, the offers will be returned as a simple list of offers, with no hotel details. The supplierHotelDescriptions element will be returned in this case, containing all descriptions from all suppliers -->

<filter id="hotel.000000000012233D"/>

</filters>

<freeTextFilters>

<freeTextFilter id="freeText.hotelDescription">Costa del</freeTextFilter>

<freeTextFilter id="freeText.hotelName">Costa del</freeTextFilter>

</freeTextFilters>

</GetPrepackagedOffersRequest>

In order to support linking to a specific search/ filter result, Travelfusion will ensure that the filter ids remain constant for all time.

THE DETAILS REQUEST IS NOW DEPRECATED AS ALL NECESSARY FUNCTIONS ARE SUPPORTED BY THE SEARCH REQUEST

Get Offer Details

This request will return all the offers that meet the specified criteria. It is designed to provide the data needed once the user has selected an offer from a full GetPrepackagedOffersRequest search.

It also can be used as a standalone request to support advertising banners, bookmarks and emailing results to a friend etc.

This request should not normally 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, or if you wish to use it for banners/ adverts.

The response will also contain offers for the day before and 2 days after the requested date. If no date is supplied, the soonest available offers will be displayed, and those for the following 3 days.

Request:

<GetPrepackagedOfferDetailsRequest>

<hotelId>124736</hotelId>

<departureDate>2012-06-16</departureDate>

<numberOfNights>14</numberOfNights>

<originAirport>OSL</originAirport>

</GetPrepackagedOfferDetailsRequest>

Response:

<GetPrepackagedOfferDetailsResponse>

<hotel>

Polling, Paging, Ranking and Usage

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

<priceWeight>1</priceWeight>

<starRatingWeight>0.5</starRatingWeight>

<distanceFromCityWeight>0.5</distanceFromCityWeight>

<mostPopularWeight>0.8</mostPopularWeight>

<bestOfferWeight>0.8</bestOfferWeight>

<dateWeight>0.8</dateWeight>

If any filters were supplied previously, they must be supplied again in the paging/ ranking request.

If any of these weights is omitted it will be assumed '0'. If no parameters are specified they will all be assumed 0 except price (which will be assumed as '1')