Look up the status of any commercial flight

The Flight Status By Flight API can be integrated within mobile and desktop applications, search engines, and other applications.

The API provides travelers and those interested in the traveler with the ability to look up a flight by flight number and get the latest status of the flight.

Audiences

  • All industries

Platform

FlightStats APIs

Look up the status of any commercial flight

Travelers check the status of their flight continually before departure to ensure the flight isn’t canceled or delayed. Friends and family of the traveler, business colleagues, travel managers, and others are interested in the same information.

Meeters and greeters, ground transportation, and other entities also check arrival status.

The Flight Status By Flight API can be integrated into the mobile, desktop, website, and other applications that all these audiences use to look up a single flight number and get the current status information for the flight.

Status information includes:

  • Status codes and current gate and runway times

  • Aircraft equipment

  • Departure/arrival gate and terminals

  • Baggage claim information

  • Irregular operational data

Here's an example of a flight status display from FlightStats that uses the Flight Status By Flight API.

Flight status by flight

Setting up Flight Status By Flight

Use the following tasks to set up Flight Status By Flight.

1) Get an application ID and key

To get started with Flight Status By Flight API, you first need an account and an application ID and key. See Get evaluation account for details about setting up an account. Flight Status by Flight APIs are available in our commercial or contract plans, and we also offer a trial period where you can try them out.

Once you have your account, follow the instructions on Get started to acquire an application ID and key and to get familiar with the standard FlightStats API platform patterns.

2) Review background material

Please read both of these documents before proceeding with these tasks:

  • Cirium Flight Status provides background material on the basics of flight status information, including status codes, gate, and time information, irregular operations, and other material.
  • Codeshares and wet leases provides background material on airline relationships such as codeshares and wet leases. It contains recommended advice on what flight numbers to display to your audience.

3) Set up your request

Flight Status By Flight has several types of APIs.

By departure date

Use this if you know the flight number, departure date, and optionally the departure airport.

By flight

Use this if you know the flight number, arrival date, and optionally the arrival airport.

By flight ID

Use this if you know the Cirium unique flight ID for the flight. For example, you can do this by doing a Flight Status By Airport request and getting a list of flights for which you want details on a specific flight.

By tail number

Use this if you want the know the details of a particular flight and all you have is a tail number.

Most status requests are by flight number and departure date. You can also request by departure airport. Note that a single flight may fly between multiple airports on a given day. For example, WN 1280 flies from MDW to LAS and then goes from LAS to SLC on the same day.

Flight Status By Flight returns both segments unless a departure airport is specified. In that case, it returns only that flight departing from the specified airport. Most status applications return all flights.

Airline and airport codes can be IATA 2 letter codes, ICAO 3 letter codes, or FS Codes (which is a unique code assigned by Cirium that usually are the IATA code). Most traveler-facing applications use IATA codes.

The API accepts all three types. The API first looks at IATA codes, then ICAO, and finally checks if the code provided is an FS code.

Pro tip

Don’t expect everybody to know the code of the airline or airport they're looking up. Some of the codes can be unintuitive. For example, WN is the code for Southwest Airlines. Instead, present the user with a auto-complete or drop-down of codes and names. The Airline Reference API can be queried and stored to power such a drop down. If you're using the reference API, submit the FS code to avoid any ambiguity with codes.

Submit the airline code, flight number, and departure date (year, month, and day). You’ll also need to choose the data format that you want the response to be in (JSON, JSONP, or XML).

We recommend specifying includeNewFields in the extendedOptions field. This returns two additional fields: operatingCarrier, and primaryCarrier. Cirium flight status records are based on the carrier operating the flight.

Flight numbers become complex when codeshares and wet leases are involved, and the primary carrier is what you want to display back to the driver. For example, you’ll want to display Alaska instead of Horizon.

An example request for Alaska 2122 departing on Jan 26, 2022 with recommended parameters looks like this:

https://api.flightstats.com/flex/flightstatus/rest/v2/json/flight/status/AS/2122/dep/2022/1/26?appId=YOUR_APP_ID&appKey=YOUR_APP_KEY&utc=false&extendedOptions=includeNewFields"

4) Parse the response and display

The above query returns the following response:

Request

The first thing you’ll see in the response is a request structure that shows you how we interpreted your request. You wouldn’t show this information to a customer, but it might be useful to you when troubleshooting.

Appendix

The appendix is next in this response. It includes airline information for AS, QX, and AA. It includes airport information for PDX and MFR, and a single object for the DH4 equipment type.

Flight statuses

Next are two flight status objects, one for each flight segment. AS 2122 flies from PDX to MFR and has a return segment of MFR to PDX later in the day. Each flight status object contains a unique flight ID assigned by Cirium.

This number won’t mean anything to your customers, but can be used when referencing a flight with Cirium support or for other reasons.

Carriers, flight numbers, and codeshares

Each segment contains carrier fields for QX as the operator and AS as the primaryCarrier. This means that the flight is primarily marketed as an AS (Alaska Airlines) flight, but QX (Horizon Airlines) is the airline operating this flight.

Each status object includes a codeshare element that shows an S codeshare relationship. You might want to note this on your display since some travelers find it is important. FlightStats.com, for example, displays a note that says the flight is “Operated by Horizon Air on behalf of Alaska Airlines.”

Note that the PDX-MFR flight also has a codeshare record with American Airlines 7634 and a codeshare relationship of L. This means that American Airlines is also marketing this flight, but it is an Alaska flight operated by Horizon. Your customer might ask for the status of AA 7634, and the request would look like this:

https://api.flightstats.com/flex/flightstatus/rest/v2/json/flight/status/AA/7634/dep/2022/1/26?appId=YOUR_APP_ID&appKey=YOUR_APP_KEY&utc=false&extendedOptions=includeNewFields"

The following truncated response shows the identical flight status object that is returned:

The identical record is returned. Notice that even though AA 7634 is requested, the flight status object is the same flight information with QX as the operator and AS and the primary carrier. This is because all flight status records are based on the operator of the flight.

In the event that the flight number being returned is not the same as the flight number requested, your application should recognize this and ensure to display the requested flight number to your user to avoid confusion. In some cases, providing this information is a requirement. We recommend that you highlight that this flight is operated by another carrier.

For example, FlightStats.com displays the AA 7634 flight as (AA) American Airlines 7634 with a note that says: “Operated by Horizon Air on behalf of Alaska Airlines 2122.” This is especially important to travelers who are checking in at PDX as they would need to check in with Alaska Airlines, not American.

Airports

Each status object will contain a departure and arrival airport code. These are FS codes, and you can look up the associated airport in the Appendix to get the name of the airport, city, country, and other information.

If a flight was diverted to another airport, divertedAirportFsCode might be present as well. If present, this is the airport where the flight landed instead of the originally-planned airport.

Status Codes

The code will be one the following:

  • A - Active

  • C - Canceled

  • D - Diverted

  • S - Scheduled

  • L - Landed

  • R - Redirected

  • U - Unknown

See Flight status codes for details about these codes.

Dates and times

Each status object will contain a general departure and arrival date as well as an Operational Times object that contains published, scheduled, estimated, and actual times. Both gate times and runway times are represented. There might not be values for some times dependent on the data feeds we have for the flight.

Pro tip

When displaying time information to travelers, what matters the most is usually the gate times. A runway may be displayed when no gate time is present. Estimated times vary in reliability as well and should only be shown when the equivalent actual time is not available. The estimated time gets more reliable as the departure time approaches.

Delays

If the flight is delayed, the delays object contains information about the delay. Here’s an example:

Delays are calculated based on comparing the actual or estimated times as opposed to the scheduled or published time of the same type (departure/arrival gate/runway).

We use actual times if they're available. For example, after a flight has departed and there is an actual gate time to use.

departureGateDelayMinutes = actualGateDepartureTime - scheduledGateDepartureTime.

Prior to departure:

departureGateDelayMinutes = estimatedGateDepartureTime - scheduledGateDepartureTime

The same applies to arrival and runway calculations.

Estimated runway times are typically less reliable than gate times, so use gate times when possible

Severity of delays

Flights are considered late if the delay is greater than 15 minutes. If you want to present this to your customer, consider the following scale:

  • If Delay < 15, the flight is on time

  • If Delay >= 15 but < 30, the flight is late

  • If Delay >= 30 but < 45, the flight is very late

  • If Delay >=45, the delay is excessive

Flight durations

Flight durations contain calculations that might be beneficial to display to the traveler. Not all durations are reported. Reporting depends on the state of the flight and whether or not we collected all times from the data sources.

In the above example for the PDX to MFR flight, the following is reported:

  • BlockMinutes - The scheduled/actual amount of time between when the flight departs the gate to when it arrives at the arrival gate

  • AirMinutes - The scheduled and actual amount of time between when the flight takes off to when it lands

  • taxiOutMinutes - The scheduled and actual amount of time between when the flight departs the gate to when it takes off

  • taxiInMinutes - The scheduled and actual amount of time between when the flight touches down at the arrival airport to when it arrives at the gate

Airport resources

Each flight status object contains an airport resources object that contains terminal and gate information for the departure and arrival airport, and baggage claim information at the arrival airport. Values might not be present, depending on our data sources.

Equipment

The equipment code for what kind of aircraft is expected and actually was used is returned in the Equipment structure. This code can be used to look up a description of the aircraft in the appendix element.

The tail number of the flight might also be returned. While this is of limited value to many travelers, some frequent flyers and aviation enthusiasts know exactly what aircraft has a particular tail number, and photos of these flights are usually based on the tail number.

The fleetAircraftId might also be returned. This ID is used to look up the aircraft when using the Aircraft API. This API returns a wealth of information about the aircraft.

Irregular operations

If includeNewFields is set in the extendedOptions parameter, an array of irregular operations might be returned. This depends on the data sources for the flight. The array contains information that might be useful to the customer.

For example, if our data sources show that the flight returned to the departure gate, an array item with that code is returned here.

Confirmed Incident

If includeNewFields is set in the extendedOptions parameter and there's a serious incident involving the aircraft, there might be a Confirmed Incident element present. This is present if Cirium staff manually reports the incident.

In this case, you should report the message but not show status or time information since that information might be incorrect. Alternatively, you could display a message that tells your customer to contact the airline.

Additional information

In the majority of cases, the information outlined above is sufficient. However, the status objects might also include some additional information that you might find valuable.

FlightStatusUpdates

We publish a list of any updates made to a status record. These updates can be returned in the response if includeDeltas is specified in the extendedOptions field. This information can be valuable for troubleshooting or even for advanced status applications. Some examples of what you might be able to do with this information include:

Increasing/decreasing delay

The flight status record includes a structure that shows calculated departure/arrival gate/runway delays. However, this information doesn't tell you if the expected delay is increasing or decreasing. By parsing the updates to the record, you can show how often the estimated departure/arrival has been updated and whether the estimates are increasing or decreasing.

Important status changes

This informs you if a departed flight was previously canceled or diverted. It also tells you if a canceled flight that just had an estimated departure time updated has been reinstated or not.

Toggling data sources

An example of this is if the arrival gate keeps toggling between “21” and “25”. This can indicate two data sources that aren’t agreeing. It might be worth presenting both to the user as an option.

Updates are returned in an array with the UTC date/time of the update and generally what the source of the update was. Depending on whether the update was to date/time or a string, the updated information will be in an updatedTextFields array and/or updatedDateFields. The following example shows that one update updated equipment, status, and date fields:

The fields have codes that define what field was updated. See Cirium flight status for more information.

For an example, or for troubleshooting, FlightStats.com shows these items in the Event Timeline on the flight details for each page. Here's an example:

Flight status event timeline

Schedule information

If the flight was created by a published schedule from the airline, a schedule object might be returned. There are two pieces of information within the schedule that may be valuable to your application: service type and uplines/downlines.

We publish flight information for a variety of flight types, such as scheduled passenger flights, charter, or cargo-only flights. The flightType field might be of interest if, for example, you don't want to display cargo flights in your application.

The uplines and downlines arrays might contain information about where the previous segment of a flight with multiple stops (upline) or where the flight is going next (downline). In both cases, a linked flightId is included.

This shows your customer upline flight information, which might help them understand if the flight has had anything irregular occur that might impact the flight. For example, if it is delayed already, or if the upline flight was canceled.

This doesn’t necessary mean that their flight will be impacted, but it often does. Airlines can always adjust aircraft to accommodate for upline problems.

Inlined references

By default, Flight Status APIs return airline and airport codes only in the flight status response. The response includes an appendix, which has detailed airline and airport objects for every airline or airport that were a part of any flight status object.

You use the code to find the object in the appendix and then merge things like names, cities, countries, etc. in your code. This minimizes duplication in the response.

If instead you would like airport and airline objects, include the flight status object that is returned, and then specify useInlinedReferences in the extendedOptions fields. This might increase the size of the response if multiple flight segments are returned.

Displaying flight listings

Travelers and people watching a flight sometimes don't know the flight number. For these cases, it might be valuable for your application to offer additional ways for your customers to search for flights. The two APIs you most likely would be interested in are:

Flight Status By Route - Search for flights going from point A to point B

Flight Status By Airport - Search for flights arriving at a particular airport, or departing from a particular airport

These APIs return the same flight status object as FlightStatusByFlight, including a flight ID. When you select the flight you're interested in, you'll typically call Flight Status By Flight By Flight ID and pass that ID.

FAQs

How do you represent terminal and gate information?

How should I determine a delay status

What is the difference between the Flight Status by Flight API and the Trip Status API?

What is the FlightStats Code?

What is the Flight Status & Track by Flight API

What is a Flight Status Flight ID?

Resources

Cirium Flight Status provides background material about the basics of flight status information including status codes, gate and time information, irregular operations, and other material.

Flight Status By Flight API returns the flight statuses for a carrier and flight numbers arriving on a given date.

FlightStats APIs provide a set of status and positional APIs by flight, airport, fleet, route, or area. They also include schedules, airline reference, airport reference, ratings, delay index, and weather information.

Codeshares and wet leases describes the aircraft leasing relationships between companies.