Flight API Specification

Searching

Please remember to read the connection guide which explains how to connect to the service and submit an XML request.

Request

<GetFlightsRequest>

<from>

<!-- Submit only 1 of the following location identifiers -->

<city code="LON"/>

<airport code="LHR"/>

<coordinate lat="0.34234" lon="65.283"/>

<locationResolutionResultItem id="1928301928"/>

</from>

<to>.... same as 'from' above.....</to>

<outDate>2011-06-16</outDate> <!-- outward date -->

<returnDate>2011-07-20</returnDate> <!-- (Optional) return date -->

<ages> <!-- age for each passenger -->

<age>30</age>

<age>30</age>

</ages>

<bagsToCheckin>1</bagsToCheckin> <!-- (Optional) The value cannot be higher than the number of passengers. Indicates how many passengers are checking in a bag -->

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

</GetFlightsRequest>

Response

<GetFlightsResponse sid="ZWSRH3EBfLees7rr">

<!-- ‘supplierConnections’ is the number of data connections to suppliers, ‘completeConnections’ indicates how many supplier have responded so far, ‘totalResults' is the number of bookable offers that have been found so far -->

<resultInfo completeConnections="51" supplierConnections="51" suppliers="8" totalResults="225">

<supplierResultInfo>

<supplier name="easyjet" completeConnections="15" supplierConnections="21" totalResults="100"/>

<supplier name="flybe" completeConnections="12" supplierConnections="30" totalResults="125"/>

</supplierResultInfo>

<!-- systemInfo: 'suppliers' gives the total number of suppliers that are active for your account. -->

<systemInfo suppliers="10"/>

</resultInfo>

<results>

<flightOffer id="1">

<supplier>flybe</supplier>

<billingPrice currency="EUR" luggageCharge="26.00">61.99</billingPrice> <!-- The billingPrice is the exact price in the currency that will be billed. The luggageCharge will only be included if 'bagsToCheckin' is specified in the request and has value great than 0 -->

<price currency="GBP" luggageCharge="26.00">41.99</price> <!-- This is the billing price converted to the requested currency using TF's conversion rates. The luggageCharge will only be included if 'bagsToCheckin' is specified in the request and has value great than 0 -->

<out orig="LGW" dest="MAD" dep="2011-06-16 08:25" arr="2011-06-16 21:21" changes="1" duration="11:56">

<segment dest="FRA" operator="British Airways">

<segment dest="MAD" operator="Norwegian">

</out>

<return>

-------- Similar format to outward ---------

</return>

</flightOffer>

<flightOffer id="2">

<supplier>easyjet</supplier>

<billingPrice currency="NOK">510.99</billingPrice>

<price currency="GBP">45.99</price>

<out orig="LTN" dest="MAD" dep=" 2011-06-16 09:25" arr="2011-06-16 12:21" changes="0" duration="1:56">

<segment dest="MAD" operator="Easyjet">

</out>

<return>

-------- Similar format to outward ---------

</return>

</flightOffer>

</results>

</GetFlightsResponse>

Polling

IMPORTANT: The above call will always respond immediately, and will return the best offers received from suppliers so far (therefore the first response will contain no offers at all). If the completeConnections is less than the supplierConnections, then the request below 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 all results have been returned or when a certain timeout is reached (e.g. after 1 minute). Polling only applies to requests that depend upon live connections to 3rd parties and therefore are 'slow'. This currently is only 'GetFlightsRequest' and 'GetHotelsRequest'

<GetFlightsRequest sid="ZWSRH3EBfLees7rr">

</GetFlightsRequest>

By default, the best 10 offers are returned. This can be changed by submitting the ‘paging’ element described below.

Paging

The sid must be submitted when to modifying the results of a previous search, for example to request a different page of results, or adjust the number of results per page:

<GetFlightsRequest sid="ZWSRH3EBfLees7rr">

<paging>

<pageNumber>2</pageNumber> <!-- Requests the second page of results -->

<offersPerPage>5</offersPerPage> <!-- Specifies the number of offers on each page -->

</paging>

</GetFlightsRequest>

Travelfusion may not support 'page-skipping'. i.e. you will not be able to view page 2 without viewing page 1 first. The end user should only be offered 'next' and 'previous' buttons, not a list of page numbers.

Ranking of results

The sid is used to re-rank the results of an existing search.

<GetFlightsRequest sid="ZWSRH3EBfLees7rr">

<rankingParameters>

<idealOutwardTime>13:00</idealOutwardTime>

<idealReturnTime>13:00</idealReturnTime>

<outwardTimeWeight>0.5</outwardTimeWeight>

<returnTimeWeight>0.5</returnTimeWeight>

<priceWeight>1.0</priceWeight>

<distanceWeight>0.3</distanceWeight>

<durationWeight>0.8</durationWeight>

</rankingParameters>

</GetFlightsRequest>

Each of the parameters is optional. They initially have default values as above. Weights must be between 0 and 1 and indicate the relative importance of each feature of the offers. Offers are then ranked according to these weights and features.

Filtering results

The information of how to do filtering can be found here.

Usage Guide

Any of the 3 requests above (polling, paging and ranking) can be combined into a single request where needed. For example, to launch a new search and set the timeWeight to 0 and priceWeight to 1, the following could be submitted:

<GetFlightsRequest>

<from>98019283019</from>

<to>MAD</to>

<going>2011-06-16</going>

<returning>2011-07-20</returning>

<parameters>

<timeWeight>0.5</timeWeight>

<priceWeight>1.0</priceWeight>

</parameters>

</GetFlightsRequest>

Note that all parameters and paging is remembered in the session, so if the request below is then submitted, the results to the above search will be re-ranked, considering the new timeWeight (but preserving the previously specified priceWeight), and the 2nd page of 5 offers will be returned.

<GetFlightsRequest sid="ZWSRH3EBfLees7rr">

<paging>

<pageNumber>2</pageNumber>

<offersPerPage>5</offersPerPage>

</paging>

<parameters>

<timeWeight>0.5</timeWeight>

</parameters>

</GetFlightsRequest>

The API has been designed to represent the pages of a typical mobile or widget user-interface, and the behaviour of a typical user – i.e. submitting a search and then paging or filtering the results based on various criteria.

It supports some advanced weighted ranking functions that could be offered to the user in many simple formats or hidden completely. These are designed to help identify a very small set of the most useful results from a very large set of options, without the user needing to page through hundreds of offers and compare them by memory.

Booking (Get Booking Ids For Offer)

In order to book a flight offer, you will first need to obtain the 'booking ids' for the offer. You can do this as follows:

Request:

<GetBookingIdsRequest xmlns="http://www.travelfusion.com/xml/api/simple" token="{VALID_TOKEN}" sid="{VALID_SID}">

<id name="offerId" value="74"/>

</GetBookingIdsRequest>

Response:

<GetBookingIdsResponse xmlns="http://www.travelfusion.com/xml/api/simple">

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

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

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

<id name="outwardLegId">MP7FUDOKJYM5TZC9</id>

<id name="returnLegId">VOYLKLZ162CFO006</id>

</GetBookingIdsResponse>

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