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.
In this document, we’ll show you how to get started with these APIs.
If you do not already have an account, sign up today for a free trial.
The FlightStats APIs are primarily REST style, returning either XML, JSON, or JSONP. The APIs in the API reference include an OpenAPI spec that can be downloaded describing the requests and responses.
We also offer SOAP endpoints. Links to the WSDL and XSD files for each API are included in the API reference.
Our interactive test clients are REST and JSON-centric, but the returned data is otherwise identical to the REST/XML and SOAP services and may be used to prototype and debug those protocols and formats.
Each service invocation is authenticated using your application ID (appId) and application key (appKey).
To acquire an application ID and key:
For the REST APIs, the credentials can be either included in the header or as query parameters:
Example in header:
In the SOAP APIs, there are fields in the request for the credentials.
All URIs follow a common pattern:
For JSONP, supply the name of your callback method with the optional parameter callback.
A special optional parameter, extendedOptions, adjusts the format and content of the response. The following options are common to many of the APIs:
To specify these options, simply include them as an optional parameter. Any of the following are valid:
Unrecognized options are silently ignored.
If useHTTPErrors is specified in extendedOptions, the error will be reported as the HTTP status of the response, with details about the error will be in the body of the error message. A full response object will not be returned.
For more details, see the Error Handling section later in this document.
By default, potentially repetitive data in responses for some APIs is summarized in the appendix element. For example, in flightStatus elements, airports are referenced as arrivalAirportFsCode and departureAirportFsCode. Details on each airport referenced would appear in an airports element in the appendix.
If you prefer to have this information embedded in the main response element, pass extendedOptions=useInlinedReferences. This changes the results to include the airport object directly in the flightStatus element and not in the appendix. This can result in substantially longer results as airports, airlines, etc are repeated whereever they occur in the result instead of just a single referenced object in the appendix.
Flight Status Response example:
By default, API requests return the frozen Long Term Support data for a given version (see Version Policy below for details).
If there are new fields available for the requested version they can be included by specifying the option includeNewFields.
Some APIs offer localization of strings in the response data. Specify the desired language by providing the option languageCode:xx, substituting the appropriate two-letter language code for xx. If you do not provide a language code, you will get responses with localized strings in the default, English.
APIs supporting localization:
API responses always include the following elements:
for example, flightStatus or flightTrack elements. See specific API documentation for an explanation of what is returned by the API.
for failed requests, information about the error. (Present but empty for successful requests.)
In addition, some APIs include the following in the response:
a summary of the request
supplemental detail about elements of the response. For example, a FlightStatus response typically refers to one or more airports and airlines; details about the referenced airports and airlines are included in the appendix.
There are two approaches to error handling:
For example, if the request contains an invalid appId the API will return a 200 status code and the following JSON.
In this case, the normal HTTP status code is 401 and is returned in httpStatusCode. The error code is UNAUTHORIZED and more detail is provided in the errorMessage.
If instead, you desire actual HTTP error codes then you should use pass extendedOptions=useHTTPErrors as a parameter in the request. The API will then return the proper HTTP error code, the response body will be text/plain and the body will and contain a block of text describing the error. In the invalid API key example, the HTTP status code is 401 and the body of the message looks like:
status: 401 code: UNAUTHORIZED message: application with id="1" was not found id: 9a56697b-6743-4f79-92f4-07cf885c4e7c
The following HTTP status codes may be reported:
Standard response for a successful request (or when useHTTPErrors was not specified).
400 (Bad Request)
Something was wrong with the request submitted, and it must be corrected before it can succeed. The response body will include details about the error.
Authorization failure; valid credentials were not provided. This is usually due to invalid Application IDs or keys -- 403 (Forbidden)
Authorization failure; valid credentials were not provided. This is usually the result of a usage limit for an application being exceeded or the application not having permission to use the API.
404 (Not Found)
Requested item could not be found, or the endpoint does not exist.
405 (Method Not Allowed)
The HTTP request specified a method (e.g. PUT, DELETE, OPTIONS, etc.) that is not supported by this resource.
500 (Internal Server Error)
Unexpected server-side failure. Should this occur, please contact us for assistance. The response body will include a unique identifier that we can use to help locate the problem.
Some of the APIs will return a request element in the response that summarizes what you requested and also shows how the API interpreted it. This is provided for debugging and testing purposes. The best way to understand this is with an example.
The following demonstrates an API request to flight status by flight and departure date
curl -v -X GET "https://api.flightstats.com/flex/flightstatus/rest/v2/json/flight/status/AAL/100/dep/2021/9/1?appId=SOME_ID&appKey=SOME_KEY&utc=false&airport=KJFK&codeType=icao"
This is asking for AAL 10 on Sept 1, 2021 departing KFJK and local times. The specified codes are ICAO codes.
This produces the following response (the flight status portion is truncated):
Things to note about the response:
If the request were to include useInlinedReferences in the extendedOptions, there is no appendix returned as the airline and airport objects are inlined where referenced in the request (and flight status elements). Ex;
curl -v -X GET "https://api.flightstats.com/flex/flightstatus/rest/v2/json/flight/status/AAL/100/dep/2021/9/1?appId=SOME_ID&appKey=SOME_KEY&utc=false&airport=KJFK&codeType=icao&extendedOptions=useInlinedReferences"
Some APIs include and appendix for common data objects like Airline, Airportsand Equipment information. This reduces the amount of information returned in the response dramatically at times. Let's assume you did a flight status by route for Alaska Airlines flights departing PDX and flying to SEA. This returns a number of Alaska Airlines flights in the response and almost all those flights are operated by Horizon Airlines. If useInlinedReferences in extendedOptions, then for every one of the returned flights there would be a airline object for Alaska Airlines, a airline object for Horizon Airlines, an airport object for PDX, an airport object for SEA, and equipment objects for the aircraft. This quickly explodes the size of the response.
If useInlinedReferences is not specified in extendedOptions, then for every one of the returned flights there would be a string identifying the code for Alaska Airlines, a string identifying the code for Horizon Airlines, a string identifying the code for PDX, a string identifying the code for SEA, and a string identifying the code for the flight's equipment. In the appendix would be a single airline object for Alaska Airlines, a single airline object for Horizon Airlines, a single airport for PDX, a single airport object for SEA and unique equipement objects. All of the information in the appendix can easily be looked up using the codes in the request.
Cirium aims to provide a rich and responsive API platform that is free from unexpected disruptions. Our customers want API products that are continuously improving, but also have stable and predictable formats. We aim to please everybody with a versioning scheme for the FlightStats APIs that offers both a dependable format as well as incremental improvements.
When a new version of an API is released from BETA, the initial fields in the response are considered Long Term Support Fields and by default the APIs return only LTS fields. When we have opportunities to improve an API version by adding new data, we will add new non-LTS fields. Non-LTS fields will only be returned if they are specifically requested with an extendedOption parameter. The inclusion of the non-LTS fields will not affect the visibility or content of the LTS fields.
Here is an example of how the non-LTS fields are requested:
When a new API version is released, we make sure that we lock it down for long-term support so that you can depend on it into the future. Customers with parsers that expect strict adherence to our published documentation (WSDL, XSD, etc) will appreciate this. Customers with more flexible parsers that are tolerant of additive changes will have the opportunity to request the new non-LTS fields and stay on the cutting edge.
When we improve an API beyond simply adding data, we will release an entirely new version. The new version of the API will have its own set of LTS and non-LTS and will evolve separately from the previous version.
Documentation of API request parameters in an interactive format is available for each API using our API explorer.
Request parameters are displayed in a web form that you can fill out and submit to try out the APIs. To use the interactive documentation:
Note that you must provide valid application credentials when you submit requests through the interactive documentation.