Flights
The Flights category contains a wide array of APIs that can help you manage flights, from searching for flight options to actually booking a flight.
| APIs | Description |
|---|---|
| Flight booking | |
| Flight Offers Search | Lets you can search flights between two cities, perform multi-city searches for longer itineraries and access one-way combinable fares to offer the cheapest options possible. |
| Flight Offers Price | Confirms the availability and final price (including taxes and fees) of flights returned by the Flight Offers Search API. |
| Flight Create Orders | Provides a unique booking ID and reservation details once the reservation is completed. |
| Flight Order Management | Checks the latest status of a reservation, shows post-booking modifications like ticket information or form of payment and lets you cancel reservations. |
| Seatmap Display | Shows airplane cabin plan from a Flight Offer in order for the traveler to be able to choose their seat during the flight booking flow. |
| Branded Fares Upsell | Provides the branded fares available for a given flight, along with pricing and a fare description. |
| Flight Price Analysis | Uses an Artificial Intelligence algorithm trained on Amadeus historical flight booking data to show how current flight prices compare to historical fares and whether the price of a flight is below or above average. |
| Flight Choice Prediction | Uses Artificial Intelligence and Amadeus historical flight booking data to identify which flights in search results are most likely to be booked. |
| Flight inspiration | |
| Flight Inspiration Search | Provides a list of destinations from a given city that is ordered by price and can be filtered by departure date or maximum price. |
| Flight Cheapest Date Search | Provides a list of flight options with dates and prices, and allows you to order by price, departure date or duration. |
| Flight Availabilities Search | Provides a list of flights with seats for sale on a given itinerary and the quantity of seats available in different fare classes. |
| Travel Recommendations | Uses Artificial Intelligence trained on Amadeus historical flight search data to determine which destinations are also popular among travelers with similar profiles, and provides a list of recommended destinations with name, IATA code, coordinates and similarity score. |
| Flight schedule | |
| On Demand Flight Status | Provides real-time flight schedule data including up-to-date departure and arrival times, terminal and gate information, flight duration and real-time delay status. Help travelers track the live status of their flight and enjoy a stress-free trip. |
| Flight Delay Prediction | Provides delay probabilities for four possible delay lengths |
| Airport | |
| Airport & City Search | Finds airports and cities that match a specific word or a string of letters. |
| Airport Nearest Relevant | Provides a list of commercial airports within a 500km (311mi) radius of a given point that are ordered by relevance, which considers their distance from the starting point and their yearly flight traffic. |
| Airport Routes API | Finds all destinations served by a given airport. |
| Airport On-Time Performance | Predicts an airport's overall performance based on the delay of all flights during a day. |
| Airlines | |
| Flight Check-in Links | Simplifies the check-in process by providing direct links to the airline check-in page. |
| Airline Code Lookup | Finds the name of an airline by its IATA or ICAO airline codes. |
| Airline Routes | Finds all destinations served by a given airline. |
Search flights
Search to get flight inspirations
The Flight Inspiration Search API provides a list of destinations from a given airport that is searched by the IATA code of the origin, ordered by price and filtered by departure date, one-way/round-trip, trip duration, connecting flights or maximum price.
Information
The Flight Inspiration Search API uses dynamic cache data. This cache data is created daily based on the most trending options that are derived from past searches and bookings. In this way, only the most trending options are included in the response.
The only mandatory query parameter is the IATA code of the origin as in the following example request that retrieves a list of destinations from Boston:
The departure date is an optional parameter, which needs to be provided in the YYYY-MM-DD format:
If the oneWay parameter set to true, only one way flight options will be provided in the response. Alternatively, if the oneWay parameter set to false, the search results will show round-trip flights. Otherwise, both flight options will be included in the results. For example, the following request shows one-way flights out of Boston:
One-way journeys can be optionally refined by the journey duration provided in days with the duration parameter:
The nonStop parameter filters the search query to direct flights only:
If you need to cap the maximum ticket price, just specify the maximum price in decimals using the maxPrice parameter:
Information
This API returns cached prices. Once a destination is chosen, use the Flight Offers Search API to get real-time pricing and availability.
The API provides a link to the Flight Offers Search API to search for flights once a destination is chosen and a link to the Flight Cheapest Date Search API to check the cheapest dates to fly:
Search for destinations for a specific duration of stay
For example, let's say a traveler wants to spend six days in a city but doesn't have a strong preference for the destination. With the Flight Inspiration Search API we can recommend the traveler the cheapest destinations based on the stay duration.
This can be done using the parameter viewBy which returns flight destinations by DATE, DESTINATION, DURATION, WEEK, or COUNTRY. In our scenario we need to pass the value DURATION to the parameter viewBy, like in the example below. Also, as input we give a duration of six days and origin Miami. The departure date will be between the 1st and 3rd of September 2021.
GET https://test.api.amadeus.com/v1/shopping/flight-destinations?departureDate=2021-09-01,2021-09-03&duration=6&origin=MIA&viewBy=DURATION
As you can see, all the recommendations have a duration of six days and are sorted by the lowest price. The API also provides link to the Flight Offers Search API for each result in order to check for available flights.
Search for cheapest flights regardless of the dates
The Flight Cheapest Date Search API finds the cheapest dates to travel from one city to another. The API provides a list of flight options with dates and prices, and allows you to order by price, departure date or duration.
Information
The Flight Cheapest Date Search API uses dynamic cache data. This cache data is created daily based on the most trending options that are derived from past searches and bookings. In this way, only the most trending options are included in the response.
Information
This API returns cached prices. Once the dates are chosen, use the Flight Offers Search API to get real-time pricing and availability.
The origin and destination are the two mandatory query parameters:
We can further refine our search query by the departure dates, one-way/round-trip, trip duration, connecting flights or maximum price.
The API supports one or multiple departure dates in the query provided the dates are speficied in the ISO 8601 YYYY-MM-DD format and separated by a comma:
If the oneWay parameter set to true, only one way flight options will be provided in the response. Alternatively, if the oneWay parameter set to false, the search results will show round-trip flights. Otherwise, both flight options will be included in the results. For example, the following request shows one-way flights out of Boston:
One-way journeys can be optionally refined by the journey duration provided in days with the duration parameter:
The nonStop parameter filters the search query to direct flights only:
If you need to cap the maximum ticket price, just specify the maximum price in decimals using the maxPrice parameter:
The API provides a link to the Flight Offers Search API to search for flights once a destination is chosen, in order to proceed with the booking flow.
Search for best flight offers
The Flight Offers Search API searches over 500 airlines to find the cheapest flights for a given itinerary. The API lets you search flights between two cities, perform multi-city searches for longer itineraries and access one-way combinable fares to offer the cheapest options possible. For each itinerary, the API provides a list of flight offers with prices, fare details, airline names, baggage allowances and departure terminals.
Tip
- Flight Offers Search API is the first step of Flight booking engine flow. Check the details from Video Tutorials and Blog Tutorial.
Warning
- Flights from low-cost carriers, American Airlines, Delta and British Airways are unavailable.
The Flight Offers Search API starts the booking cycle with a search for the best fares. The API returns a list of the cheapest flights given a city/airport of departure, a city/airport of arrival, the number and type of passengers and travel dates. The results are complete with airline name and fares as well as additional information, such as bag allowance and pricing for additional baggage.
The API comes in two flavors:
- Simple version: GET operation with few parameters but which is quicker to integrate.
- On steroids: POST operation offering the full functionalities of the API.
The minimum GET request has following mandatory query parameters:
- IATA code for the origin location
- IATA code for the destination location
- Departure date in the ISO 8601 YYYY-MM-DD format
- Number of adult travellers
Let's have a look at all the optional parameters that we can use to refine the search query. One or more of these parameters can be used in addition to the mandatory query parameters.
Return date in the ISO 8601 YYYY-MM-DD format, same as the departure date:
Number of children travelling, same as the number of adults:
Number of infants travelling, same as the number of adults:
Travel class, which includes economy, premium economy, business or first:
We can limit the search to a specific airline by providing its IATA airline code, such as BA for the British Airways:
Alternatively, we can exclude an airline from the search in a similar way:
The nonStop parameter filters the search query to direct flights only:
The currencyCode defines the currency in which we will see the offer prices:
We can limit the maximum price to a certain amount and specify the currency as described above:
The maximum number of results retrieved can be limited using the max parameter in the search query:
The API returns a list of flight-offer objects (up to 250), including
information such as itineraries, price, pricing options, etc.
The POST endpoint consumes JSON data in the format described below. So, instead of constructing a search query, we can specify all the required parameters in the payload and pass it onto the API in the request body. In addition to this, a X-HTTP-Method-Override header parameter is required.
Search for flights including or excluding specific airlines
If you want your search to return flights with only specified airlines, you can use the parameter includedAirlineCodes to consider specific airlines. For example, there is a traveler who wants to travel from Berlin to Athens only with Aegean Airlines (A3):
GET https://test.api.amadeus.com/v2/shopping/flight-offers?max=3&adults=1&includedAirlineCodes=A3&originLocationCode=BER&destinationLocationCode=ATH&departureDate=2022-12-06
With the parameter excludedAirlineCodes you can ignore specific airlines. For example, there is a traveler who wants to travel from Berlin to Athens ignoring both Aegean Airlines (A3) and Iberia (IB):
GET https://test.api.amadeus.com/v2/shopping/flight-offers?max=3&adults=1&excludedAirlineCodes=A3,IB&originLocationCode=BER&destinationLocationCode=ATH&departureDate=2021-09-06
Interactive code examples
Check out this interactive code example which provides a flight search form to help you build your app. You can easily customize it and use the Flight Offers Search API to get the cheapest flight offers.
Search for the best flight option
The Flight Choice Prediction API predicts the flight your users will choose. Our machine-learning models have analyzed historical interactions with the Flight Offers Search API and can determine each flight’s probability of being chosen. Boost conversions and create a personalized experience by filtering out the noise and showing your users the flights which are best for them.
Here is a quick cURL example piping the Flight Offers Search API results directly to the prediction API. Please note that a X-HTTP-Method-Override header parameter is required.
Let’s look at flight offers for a Madrid-New York round trip (limiting to four options for this test illustration)
The prediction API returns the same content as the Low Fare search with the
addition of the choiceProbability field for each flight offer element.
Search for flight offers for multiple cities
Many travelers take advantage of their international trips to visit several destinations. Multi-city search is a functionality that lets you search for consecutive one-way flights between multiple destinations in a single request. The returned flights are packaged as a complete, bookable itinerary.
To perform multi-city searches, you must use the POST method of the Flight Offers Search API. The API lets you search for up to six origin and
destination city pairs.
In the following example, we’ll fly from Madrid to Paris, where we’ll spend a couple of
days, then fly to Munich for three days. Next, we’ll visit Amsterdam for two
days before finishing our journey with a return to Madrid. We'll use the
following IATA city codes: MAD > PAR > MUC > AMS > MAD
The request will look like this:
Search using loyalty programs
The Flight Offers Price API and the Seatmap Display API both accept Frequent Flyer information so end-users can benefit from their loyalty program. When adding Frequent Flyer information, please remember that each airline policy is different, and some require additional information, such as passenger name, email or phone number to validate the account. If the validation fails, your user won’t receive their loyalty program advantages.
Search for routes from a specific airport
The Airport Routes API shows all destinations from a given airport. To follow up on our previous example, let's check where we can fly to from Madrid (MAD). The options are obviously quite broad, so we can limit the maximum number of results to 10. Keep in mind that this limit will apply from the beginning of the results list in the alphabetical order of the airport IATA codes.
The request will look like this:
So we can see the the following results:
Search for routes for a specific airline
The Airline Routes API shows all destinations for a given airline. To follow up on our previous example, let's check what destinations the British Airways fly to. There's definitely plenty of options, so we can limit the maximum number of results to two for the sake of simplicity. Keep in mind that this limit will apply from the beginning of the results list in the alphabetical order of the city names.
The request will look like this:
So we can see the the following results:
Look up the airline ICAO code by the IATA code
If we need to know the IATA code for a particular airline but only have the airline's ICAO code, the Airline Code Lookup API can help us out. Just specify the IATA code in the query and send out the request:
The response is pretty straightforward:
Search for flight and fare availability
With the Flight Availabilities Search API you can check the flight and fare availability for any itinerary. This refers to the full inventory of fares available for an itinerary at any given time. The concept of flight availability originated in the early days of flight booking as a way for agents to check what options existed for their travelers’ itineraries.
You can build the request by passing into the body of the POST request an object that you can customise to your needs. An example of such object is provided in the specification of the Flight Availabilities Search API. In addition to this, a X-HTTP-Method-Override header parameter is required.
Here’s an example request for a one-way flight from Mad (MIA) to Atlanta (ATL) for one traveler departing on December 12, 2021:
POST https://test.api.amadeus.com/v1/shopping/availability/flight-availabilities
The response contains a list of available flights matching our request criteria (for the sake of this example, we only show the first result). Each flight availability includes descriptive data about the flight and an availabilityClasses list containing the available fare classes and the number of bookable seats remaining in each fare class.
Note that airlines’ bookable seat counters goe up to a maximum of 9, even if more seats are available in that fare class. If there are less than 9 bookable seats available, the exact number is displayed.
Search branded fares
Branded fares are airfares that bundle tickets with extras, such as checked bags, seat selection, refundability or loyalty points accrual. Each airline defines and packages its own branded fares and they vary from one airline to another. Branded fares not only help build brand recognition and loyalty, but also offer travelers an attractive deal as the incremental cost of the fare is usually less than that of buying the included services à la carte.
The Branded Fares Upsell API receives flight offers from the Flight Offers Search API and returns branded fares as flight offers which can be easily passed to the next step in the booking funnel. The booking flow is the following:
- Search for flights using the Flight Offers Search API.
- Find branded fare options for a selected flight using the Branded Fares Upsell API.
- Confirm the fare and get the final price using the Flight Offers Price API.
- Book the flight using the Flight Create Orders API.
Let's see an example of how to search for branded fares.
You can build the request by passing the flight-offer object from the Flight Offers Search API into the body of the POST request including the mandatory X-HTTP-Method-Override header parameter:
Please not that the X-HTTP-Method-Override header parameter is required to make this call.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 | |
The API will procide the following JSON in the response:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 | |
You can also see the process step to step How to upsell with branded fares in this video tutorial from Advanced flight booking engine series.
Search for personalized destination recommendations
The Travel Recommendations API provides personalized destinations based on the traveler's location and an input destination, such as a previously searched flight destination or city of interest.
For example, for a traveler based in San Francisco who has searched for multiple flights to Barcelona, what other similar destinations the API could recommend? The API takes as input the country of the traveler and the IATA code of the city that was searched, in our case this will be US and BCN respectively.
GET https://test.api.amadeus.com/v1/reference-data/recommended-locations?cityCodes=BCN&travelerCountryCode=US
The response will look like this:
The only required parameter for the Travel Recommendations API is the city code. So, the API is capable of suggesting flight based on that input alone:
You can also narrow the query down by using the destinationCountryCodes parameter, which supports one or more IATA country codes, separated by a comma:
To expand the example of the San Francisco-based traveler searching for multiple flights to Barcelona, we can specify the destination country as well:
If you want to take it to the next level, you can call the Flight Cheapest Date Search API to let the users know not only the recommended destinations but also what are the cheapest dates to visit any of these cities. For real-time flights, you can also call the Flight Offers Search API. The Travel Recommendations API has returned links to both APIs.
Search for recommended nearby destinations
With the Airport Nearest Relevant API you can find the closest major airports to a starting point. By default, results are sorted by relevance but they can also be sorted by distance, flights, travelers using the parameter sort.
Information
To get the latitude and longitude of a city you can use the Airport & City Search API using the city's IATA code.
Let's call the Airport Nearest Relevant API to find airports within the 500km radius of Madrid.
GET https://test.api.amadeus.com/v1/reference-data/locations/airports?latitude=40.416775&longitude=-3.703790&radius=500
A part of the response looks like:
We can do this by calling the Flight Cheapest Date Search API which finds the cheapest dates to travel from one city to another. Let's see, for example, the cheapest dates to fly to Barcelona in November 2021.
GET https://test.api.amadeus.com/v1/shopping/flight-dates?origin=MAD&destination=BCN&departureDate=2021-05-01,2021-05-30
In the last step, we want to let the traveler perform a flight search for any of the above dates that are convenient for them. That is very easy with our APIs, as the Flight Cheapest Date Search API for each result contains a link to the Flight Offers Search API. For example, if we want to perform a flight search for the first result, we only have to take the link provided and make an API call:
GET https://test.api.amadeus.com/v2/shopping/flight-offers?originLocationCode=MAD&destinationLocationCode=BCN&departureDate=2021-05-29&returnDate=2021-06-11&adults=1&nonStop=false
Search for a city that has an airport
The Airport & City Search API finds airports and cities that match a specific word or a string of letters. Using this API, you can automatically suggest airports based on what the traveler enters in the search field. The API provides a list of airports/cities ordered by yearly passenger volume with the name, 3-letter IATA code, time zone and coordinates of each airport.
Information
Please keep in mind that Airport & City Search API only returns the cities which have an airport. If you want to retrieve any city that matches a search keyword, check out City Search API.
The Airport & City Search API has two endpoints:
You can see the process step to step in this video tutorial.
GET /reference-data/locationsto return a list of airports and cities by a keywordGET /reference-data/locations//reference-data/locations/{locationId}to return an airport or city by Id
To get a list of airports and cities by a keyword, we need to two mandatory query parameters:
subType- this defines whether we are looking for an airport or a citykeyword- this defines the keyword (or a part of it) used in our search, which can be any character in the range of A-Za-z0-9./:-'()"
Here is a basic query to look for any airport whose name starts with a letter M:
To narrow the search down, we can use an optional parameter countryCode, which is a location code in the ISO 3166-1 alpha-2 format:
The Airport & City Search API supports pagination and dynamic sorting. The dynamic sorting enables you to sort by the results by the number of travelers by airport or city where the airports and cities with the highest traffic will be on top of the list:
In addition to that, we can select how detailed the response will be. This is done by the optional view parameter, which can be:
LIGHT- to only show the iataCode, name, detailedName, cityName and countryNameFULL- to add on top of the LIGHT information the timeZoneOffset, geoCode, detailed address and travelers.score
The default option is FULL:
To search an airport or city by Id, we need to obtain the Id by using the GET /reference-data/locations endpoint. For example:
The Id for the city of Munich is CMUC. However, for the Munich Airport the Id will be AMUC. Once we know this Id, we can use it to call the GET /reference-data/locations//reference-data/locations/{locationId}, as it is the only parameter that the query requires:
Compare the flight price to historical fares
When booking a flight, travelers need to be confident that they're getting a good deal. You can compare a flight price to historical fares for the same flight route using the Flight Price Analysis API. It uses an Artificial Intelligence algorithm trained on Amadeus historical flight booking data to show how current flight prices compare to historical fares and whether the price of a flight is below or above average.
The only mandatory parameters for this search are the origin airport IATA code, destination airport IATA code and the departure date in the ISO 8601 YYYY-MM-DD format.
Let's see how it works. In our example we will be flying from Madrid (MAD) to Paris (CDG) on 12 December 2022:
This is what we get in the response:
By default the price will be shown in Euros. In this example we can see that the lowest price for such ticket should be 29.59 Euros and the highest 198.15 Euros. The first, medium and trird choices give you an idea about the possible price ranges for this flight.
We also have an option to request the result in a different currency. This is done by using the currencyCode parameter, which is an ISO 4217 format currency code. In addition, we can specify whether we are inquiring about a round trip or a one way ticket.
Confirm Fares
The availability and price of airfare fluctuate, so it’s important to confirm before proceeding to book. This is especially true if time passes between the initial search and the decision to book, as fares are limited and there are thousands of bookings occurring every minute. During this step, you can also add ancillary products like extra bags or legroom. For that you can use the Flight Offers Price API.
Once a flight has been selected, you’ll need to confirm the availability and price of the fare. This is where the Flight Offers Price API comes in. This API returns the final fare price (including taxes and fees) of flights from the Flight Offers Search as well as pricing for ancillary products and the payment information that will be needed to make the final booking.
The body to be sent via POST is built by a new object of type
flight-offers-pricing composed by a list of flight-offers (up to 6) +
payment information. In addition to this, a X-HTTP-Method-Override header parameter is required.
Return fare rules
The Flight Offers Price API confirms the final price and availability of a fare. It also returns detailed fare rules, including the cancellation policy and other information. In addition to this, a X-HTTP-Method-Override header parameter is required. To get the fare rules, add the parameter include=detailed-fare-rules to your API call, as shown below:
The FareRules object represents a collection of fare rules and penalties associated with a specific fare. Each rule is represented as a TermAndCondition object, containing information about the rule category, circumstances, applicability, maximum penalty amount, and detailed descriptions.
-
FareRules:currency: The currency in which the penalties are expressed.rules: An array ofTermAndConditionobjects, each representing a specific fare rule or condition.
-
TermAndCondition:category: A string defining the type of modification concerned in the rule, such asREFUND,EXCHANGE,REVALIDATION,REISSUE,REBOOK, orCANCELLATION.circumstances: A string providing additional information on the circumstances under which the rule applies.notApplicable: A boolean indicating if the rule does not apply to the fare.maxPenaltyAmount: A string representing the maximum penalty amount for the given rule.descriptions: An array ofDescriptionobjects that provide further details on the rule. EachDescriptionobject includes:descriptionType: A string representing the type of description.text: The actual text of the description, providing more context or explanation for the rule.
You can also see the process step to step How to display farerules in this video tutorial from Advanced flight booking engine series.
Check CO2 emissions data
The Flight Offers Price API allows you to see the emissions data for your itinerary. This data is returned as part of the reponse in the following format:
weightis an integer representing the weight of CO2 emitted for the concerned flight segmentweightUnitis a string indicating the unit of measurement for the weight of CO2 emissions, which can be specified in either pounds or kilos.cabinis a string representing the quality of service offered in the cabin where the seat is located. This is an enum, which can beECONOMY,PREMIUM_ECONOMY,BUSINESS,FIRST.
Book a Flight
Once the fare is confirmed, you’re ready to use the Flight Create Orders API to perform the actual booking. This API lets you log a reservation in the airlines’ systems and create a PNR, and returns a unique Id number and the reservation details. If you’re using an airline consolidator, the PNR will be automatically sent to the consolidator for ticket issuance. Visit the Flight Create Orders documentation page for more details on this API.
Remember, you need to be able to issue a ticket to make bookings with our Flight Create Orders API. To access the API in production, you need to either sign a contract with an airline consolidator or be accredited to issue tickets yourself.
Issue a ticket
Once the booking is made, you need to complete payment. In most cases, you’ll receive payment from the customer and then pay the airline, typically via an industry-specific settlement procedure like the BSP or ARC (more on those later).
In the final step, a flight ticket is issued. In industry terms, a flight ticket is a confirmation that payment has been received, the reservation has been logged, and the customer has the right to enjoy the flight. For IATA member airlines, only certain accredited parties can issue tickets. In the next section, we’ll go into detail about your options for managing this final step in the booking process.
You can see How to manage and issue flight booking process in this video tutorial from Flight Booking Engine 101 series.
If you are interested in knowing more about issuing tickets in travel industry, please check out this article.
View the aircraft cabin layout
With the Seatmap Display API you can view the aircraft cabin layout:
deckConfiguration- the dimensions of the passenger deck in (x,y) coordinates, including the location of the wings, exit rows, and cabins. These dimensions form a grid on which you will later place facilities and seats.facilities- the (x,y) coordinates of aircraft facilities, such as bathrooms or galleys.seats- the (x,y) coordinates of all seats on the aircraft, with their respective availability status, characteristics, and prices.
To help you build a more consistent display, the API returns a uniform width for all cabins and classes. Rows with special seating like business class or extra-legroom seats have fewer seats per row (e.g., 4 seats for width of 7 coordinates) than economy rows (e.g. 7 seats for a width of 7 coordinates).
You can see the more details about the aircraft cabin layout in the video below.
Display in-flight amenities
Both endpoints of the Seatmap Display API return information about the following in-flight amenities:
- Seat
- Wi-fi
- Entertainment
- Power
- Food
- Beverage
Select a seat
Requests to either endpoint of the Seatmap Display API will return a list of seating options with their characteristics, pricing, and coordinates. Let's look at an example response:
For each seat, the Seatmap Display API provides a seatAvailabilityStatus so you can indicate which seats are currently available for booking. Seats may have one of three availability statuses:
AVAILABLE– the seat is not occupied and is available to book.BLOCKED– the seat is not occupied but isn’t available to book for the user. This is usually due to the passenger type (e.g., children may not sit in exit rows) or their fare class (e.g., some seats may be reserved for flyers in higher classes).OCCUPIED– the seat is occupied and unavailable to book.
If a flight is fully booked, the API returns an OCCUPIED status for all seats. In most cases, fully booked flights are filtered out during search with the Flight Offers Search API or when confirming the price with the Flight Offers Price API. The Flight Create Orders API returns an error message if you try to book an unavailable seat. For more information on the booking flow, check out how to build a flight booking engine.
Once your user has selected their seat, the next step is to add the desired seat to the flight offer and prepare them for booking.
In the above example response, seat 20D is indicated as AVAILABLE. For your user to be able to book the seat, you must add the seat to the flightOffer object and call Flight Offers Price to get a final order summary with the included seat.
To include the seat in the flightOffer object, add it to fareDetailsBySegment → additionalServices → chargeableSeatNumber, as shown below:
The Flight Offers Price API then returns the flightOffer object with the price of the chosen seat included within additionalServices:
You can use the same process to select seats for multiple passengers. For each passenger, you must add the selected seats in fareDetailsBySegment for each travelerId within the flight offer.
At this point, you now have a priced flightOffer which includes your user's selected seat. The final step is to book the flight using the Flight Create Orders API. To do this, simply pass the flightOffer object into a request to the Flight Create Orders API, which will book the flight and return an order summary and a booking Id.
Add additional baggage
Search additional baggage options
The first step is to find the desired flight offer using the Flight Offers Search API. Each flight offer contains an additionalServices field with the types of additional services available, in this case bags, and the maximum price of the first additional bag. Note that at this point, the price is for informational purposes only.
To get the final price of the added baggage with the airline policy and the traveler's tier level taken into account, you must call the Flight Offers Price API. To do this, add the include=bags parameter in the path of the Flight Offers Price API:
As you see below, the API returns the catalog of baggage options with the price and quantity (or weight):
The Flight Offers Price API returns two bag offers for the given flight. The catalog shows that either one or two bags are available to be booked per passenger. Higher bag quantity will be rejected due to the airline's policy.
In the example above, the price of two bags is double that of one bag, though some airlines do offer discounts for purchasing more than one checked bag. Each bag offer is coupled to the specific segment and traveler Id returned in each bag offer.
If there is no extra baggage service available, the API won’t return a baggage catalog.
Add additional baggage to the flight offer
Next, you need to add the additional baggage to the desired flight segments. This gives you the flexibility to include extra bags on only certain segments of the flight.
Fill in chargeableCheckedBags with the desired quantity (or weight, depending on what the airline returns) in travelerPricings/fareDetailsBySegment/additionalServices, as shown below:
Confirm the final price and book
Once you’ve added the desired bags to the flight order, you need to call the Flight Offers Price API to get the final price of the flight with all additional services included. Once this is done, you can then call the Flight Create Orders API to book the flight. If you want to add different numbers of bags for different itineraries, you can do it following the same flow.
If the desired flight you want to book, does not permit the additional service, the Flight Create Orders API will reject the booking and return the following error:
Video Tutorial
You can also see the process step to step How to add additional baggages in this video tutorial from Advanced flight booking engine series.
Check the flight status
The On-Demand Flight Status API provides real-time flight schedule data including up-to-date departure and arrival times, terminal and gate information, flight duration and real-time delay status.
To get this information, the only mandatory parameters to send a query are the IATA carrier code, flight number and scheduled departure date, and you'll be up to date about your flight schedule. For example, checking the Iberia flight 532 on 23 March 2022:
If the flight changes and the carrier assigns a prefix to the flight number to indicate the change, you can specify it in the query using the additional one-letter operationalSuffix parameter:
The example response looks as follows:
Check for any flight delays
For any traveller it's quite important to know how far in advance they should get to the airport. The Flight Delay Prediction API estimates the probability of a specific flight being delayed.
The query consists of ten mandatory parameters:
originLocationCode- IATA code of the city or airport from which the traveler is departing, e.g.PARfor ParisdestinationLocationCode- IATA code of the city or airport to which the traveler is going, e.g.PARfor ParisdepartureDate- the date on which the traveler will depart from the origin to go to the destination in the ISO 8601 YYYY-MM-DD format, e.g.2019-12-25departureTime- local time relative tooriginLocationCodeon which the traveler will depart from the origin in the ISO 8601 format, e.g.13:22:00arrivalDate- the date on which the traveler will arrive to the destination from the origin in the ISO 8601 in the YYYY-MM-DD format, e.g.2019-12-25arrivalTime- local time relative todestinationLocationCodeon which the traveler will arrive to destination in the ISO 8601 standard. e.g.13:22:00aircraftCode- IATA aircraft codecarrierCode- airline / carrier code, e.g.TKflightNumber- flight number as assigned by the carrier, e.g.1816duration- flight duration in the ISO 8601PnYnMnDTnHnMnSformat, e.g.PT2H10M
The response result will look as follows:
The main parameter of the dataset is the result, which contains a self-explanatory value, e.g. LESS_THAN_30_MINUTES, BETWEEN_30_AND_60_MINUTES, etc.
Check the on-time performance of an airport
Another way to get prepared for any delays, is checking the on-time performance of the actual airport. The Airport On-Time Performance API estimates the probability of a specific flight being delayed.
The search query is very simple. In our query we only need to provide our flight departure date and the departure airport. For example, JFK on 12 December 2022.
This is the result:
The probability parameter shows the probability of the airport running smoothly. In our example, this metric means that there is a 92.8% chance that there will be no delays.
Get a direct link to the airline check-in page
Suppose we are building an app with an integrated check-in flow for a particular airline. In this case, we can leverage the Flight Check-in Links API to generate a link to the airline's official check-in page in a required language for both web and mobile platforms. The only parameter that we need to provide in our search query is the airline's IATA code. If required, we can request the links in a specific language, such as UK English (en-GB). This is what our request would look like:
This is what we get in the response:
Here we've got a dedicated link for web applications, a dedicated link for mobile applications and a link that works on all platforms.
Cancel a reservation
Just as you can help users book a flight with the Flight Create Orders API, you can now also help them cancel their reservations with the Flight Order Management API. However, you have a limited window of time to cancel via API. If you’re working with an airline consolidator for ticketing, cancellations via API are generally only allowed while the order is queued for ticketing. Once the ticket has been issued, you’ll have to contact your consolidator directly to handle the cancellation.
To call the Flight Order Management API, you have pass as a parameter the flight-orderId from the Flight Create Orders API.
To retrieve the flight order data:
To delete the flight order data:
View reservation details
With the Flight Order Management API you can consult and check your flight reservation.
To call the Flight Order Management API, you have pass as a parameter the flight-orderId from the Flight Create Orders API, such as:
Common Errors
Issuance not allowed in Self Service
Self-Service users must work with an airline consolidator that can issue tickets on your behalf. In that case, the payment is not processed by the API but directly between you and the consolidator. Adding a form of payment to the Flight Create Orders API will be rejected by error INVALID FORMAT.
Price discrepancy
The price of airfare fluctuates constantly. Creating an order for a flight whose price is no longer valid at the time of booking will trigger the following error:
If you receive this error, reconfirm the fare price with the Flight Offers Price API before booking.
The following is a common error in the test environment, as you can perform many bookings without restrictions (no real payment), but the inventory is a copy of the real one, so if you book many seats, the inventory will be empty and you won't be able to book anymore.
Notes
Carriers and rates
- Low cost carriers (LCCs), American Airlines are not available. Depending on the market, British Airways is also not available.
- Published rates only returned in Self-Service. Cannot access to negotiated rates, or any other special rates.
Post-booking modifications
With the current version of our Self-Service APIs, you can’t add additional baggage after the flight has been booked. This and other post-booking modifications must be handled directly with the airline consolidator that is issuing tickets on your behalf.
How payment works
There are two things to consider regarding payments for flight booking:
- The payment between you (the app owner) and your customers (for the services provided + the price of the flight ticket). You decide how to collect this payment, it is not included in the API. A third party payment gateway, such as Stripe will be an easier solution for this.
- The payment between you and the consolidator (to be able to pay the airline and issue the flight ticket). This will be done between you and your consolidator of choice, and is to be agreed with the consolidator.
Flight Booking Engine 101 Video tutorial
A video tutorial series to Explain Flight Booking Engine is available in Youtube channel.