Flight Offers API
The Flight Offers API returns available flight-only routes and related information such as prices and extras for the specified route. The documentation below describes version 1.1 of the Flight Offers resource.
API Endpoints
| Environment | URL |
|---|---|
| LIVE | https://prod.api.tui/flightOffers/flightOffers_v1 |
API Methods
Method: GET
{
"flightOffersRequest": {
"xmlns": "http://tuiuk.com/xsd/flights/flightoffers/v1",
"searchMode": "RETURN",
"numOfAdults": 2,
"numOfChildren": 1,
"childAgeonReturn": [12],
"currencyCode": "GBP",
"originAirportCodes": ["LGW"],
"destAirportCodes": ["LTN"],
"depDate": "2021-01-20",
"returnDate": "2021-01-21",
"directFlightInd": true,
"cabinClassCode": "ECONOMY"
}
}HTTP Headers
| Header Name | Value | Inbound/Outbound | Description |
|---|---|---|---|
| x-api-key | <your-api-key> | Inbound | Your unique key authorisation to access the flightOffers API. |
| Accept | application/json;flightOffers;version=1.0 or 1.1 / |
Inbound/Outbound | Version of flightOffers API invoked. If specified as / then the latest flightOffers API version will be called. |
Search Request Parameters
Search parameters should be submitted in the same order and are case sensitive.
| NAME | DESCRIPTION | FORMAT | MANDATORY | EXAMPLE | ALLOWED VALUES |
|---|---|---|---|---|---|
| searchMode | Type of search | Text string | YES | RETURN | ‘RETURN’ or ‘ONEWAY’ |
| numOfAdults | Number of adults | numeric | YES | 2 | 1-9 (total party must not exceed 9) |
| numOfChildren | Number of children | numeric | NO | 2 | 1-9 (total party must not exceed 9) |
| childAgeonReturn | Age of children on return date | numeric | Required if numOfChildren > 0 | 5,7 | List of child ages (below 18) separated by ‘,’. There must be equal number of adults in party to infants (child ages under 2) and if under 1 child age should be stated as 0. |
| currencyCode | Currency code | 3 character currency code | NO - v1.1 YES - v1.0 | GBP | ‘GBP’ |
| originAirportCodes | Departure airport | IATA 3 character airport code | YES | LGW | Airport codes from TUI UK timetable |
| destAirportCodes | Destination airport | IATA 3 character airport code | YES | PFO | Airport codes from TUI UK timetable |
| depDate | Departure date | YYYY-MM-DD | YES | 2017-08-30 | => todays date & <= end of next 2 seasons* |
| returnDate | Return date | YYYY-MM-DD | Required if searchMode=RETURN | 2017-09-06 | => todays date & greater than depDate <= end of next 2 seasons* |
| directFlightInd | Indicate if a direct flight | Text string | YES | true | ‘true’ or ‘false’ |
| cabinClassCode | Cabin type | Text string | YES | ECONOMY | ‘ECONOMY’ or ‘PREMIUMECONOMY’ |
Season availability: Three seasons are on sale at any given time:
Summer season: 1 May–31 October departures.
Winter season: 1 November–30 April departures.
In April we launch the next year’s summer season and in November we launch the next year’s winter season. So if today’s date is 26/06/2017 then the seasons on sale are Summer 17 (2017-05-01 to 2017-10-31), Winter 17-18 (2017-11-01 to 2018-04-30) and Summer 18 (2018-05-01 to 2018-10-31).
Booking deep link: Before using the booking deep-link URL, redirect the customer through the initialise-session and update-session-and-instart URLs.
API Response
| NAME | DESCRIPTION | FORMAT | EXAMPLE | ||
|---|---|---|---|---|---|
| party | numOfAdults | numOfAdults | numeric | 2 | |
| numOfChildren | Number of children | numeric | 2 | ||
| Summarised flight details | numOfInfants | Number of infants | numeric | 0 | |
| contentItem | Tui Flight Logo URL | Image URL of Logo | URL | ||
| originalAirportCode | Departure airport | IATA 3 character airport code | LGW | ||
| destAirportCode | Destination airport | IATA 3 character airport code | PFO | ||
| prices | currencyCode | Currency code | 3 character currency code | GBP | |
| totalPrice | Total price | 000.00 | 1346.00 | ||
| totalPricePerPerson | Price per person in party | 000.00 | 336.50 | ||
| deposit | Payment deposit option available | 000.00 | 0.00 | ||
| discount | Total discount applied | 000.00 | 120.00 | ||
| discountPerPerson | Discount per person in party | 000.00 | 30.00 | ||
| contentItem | Initialise Session* | URL to search results | URL | ||
| Update Session and Instart | Session URL | URL | |||
| Booking Deep Link | URL to bookflow | URL | |||
| Repeated for both outbound and inbound journeys | flightNum | Flight number | IATA flight number | TOM 4314 | |
| numOfStops | Number of stops in flight journey | numeric | 0 | ||
| departure | airportCode | Departure airport | IATA 3 character airport code | LGW | |
| date | Departure date | YYYY-MM-DD | 2021-08-30 | ||
| time | Departure time | HH:MM:SS | 08:50:00 | ||
| arrival | airportCode | Destination airport | IATA 3 character airport code | PFO | |
| date | Arrival date | YYYY-MM-DD | 2021-08-30 | ||
| time | Arrival time | HH:MM:SS | 15:15:00 | ||
| carrier | airlineCode | Carrier airline code | Text string | TOM | |
| flightSegmentDuration | hours | Hours of flight duration | numeric | 4 | |
| minutes | Minutes of flight duration | numeric | 25 | ||
| cabinClass | cabinClassAvail | Cabin types available | Text string | ECONOMY|PREMIUMECONOMY | |
| seatAvailability | maxEconomySeatAvail | Maximum number of seats in cabin type available | numeric | 9 | |
| seatExtra | code | Flight extra optional add on code | Text code | ELR | |
| extraAvailability | Number of available flight extra add on | numeric | 2 | ||
| seatExtraPrices | adultPrice | Adult price of extra add on | 00.00 | 40.00 | |
| childPrice | Adult price of extra add on | 00.00 | 40.00 | ||
| luggage | holdAllowance | numeric | 0 | ||
| holdAllowanceDimensions | 00x00x00cm | 00x00x00cm | |||
| carryOnAllowance | numeric | 5 | |||
| carryOnAllowanceDimensions | 00x00x00cm | 50x40x20cm | |||
| extraHoldAllowance | numeric | 0 | |||
| extraCarryOnAllowance | numeric | 0 | |||
| Included Luggage Allowance | URL | ||||
| Excess Baggage | URL |
Affiliate tracking: TUI affiliates must prepend their CJ tracking link to URLs returned by the API to ensure commission continues to be recorded.
Error Message Structure
In addition to the standard HTTP response code, failed API calls contain error information in the message body. Gateway errors generally relate to access control or an invalid API key, while API-generated errors describe invalid request content or downstream processing failures.
Below is the list of errors currently available in the API. This is not a definitive list; additional conditions may be added as requirements evolve.
| ErrorCode | ErrorMessage |
|---|---|
| E001 | Search mode unknown |
| E002 | Unrecognised currency |
| E003 | Departure airport must be specified |
| E004 | Arrival airport must be specified |
| E005 | Unrecognised departure or arrival airport |
| E006 | Unrecognised departure airport |
| E007 | Child age must be less than 16 years |
| E008 | Departure date must be selected |
| E009 | Search for return flights with no return date specified |
| E010 | Return date can not be less than departure date |
| E011 | At least one adult must be travelling |
| E012 | Age of all children must be specified |
| E013 | Unable to connect to search service |
| E014 | Unsupported search |
| E015 | Invalid parameter in the request |
| E018 | Only 9 Passengers are currently supported for our Web Bookings |
| E019 | For legal reasons, the number of infants needs to be the same as or less than the number of Adults. |
Warning Message Structure
In addition to errors, the API may return warnings. These provide supplementary information and may indicate that the search criteria should be refined or that the returned result has a minor data gap.
Below is the list of warnings currently available in the API. This is not a definitive list; additional conditions may be added as requirements evolve.
| Code | Message |
|---|---|
| W001 | Unable to calculate Booking Deeplink for Route(RouteCd) |
| W002 | No flights with PremiumClub Available |
| W003 | No seats available on this route |
Support
For support, contact TIBCO Operations Support.
