Get started with FlightStats APIs

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.

Get a trial account

If you do not already have an account, sign up today for a free trial.

Request structure

Supported protocols

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.

Authenticating

Each service invocation is authenticated using your application ID (appId) and application key (appKey).

To acquire an application ID and key:

  1. login to developer.flightstats.com
  2. Click the “Create a new application” button
  3. Provide a name and description and click the “Create Application” button
  4. Copy the appId and appKey from the resulting screen into your application
  5. Pass the appId and appKey as part of the request

For the REST APIs, the credentials can be either included in the header or as query parameters:

https://api.flightstats.com/flex/flightstatus/v9/xml/fooservice?appId=12345678&appKey=abcdefghijklmnopqrstukwxyz123456

Example in header:

In the SOAP APIs, there are fields in the request for the credentials.

REST URI structure

All URIs follow a common pattern:

  1. Base URI: https://api.flightstats.com/flex
  2. API name: e.g., /flightstatus
  3. Protocol selector: e.g., /rest
  4. Version: e.g., /v1
  5. Format selector: /json, /jsonp, or /xml
  6. Required parameters: as pathinfo
  7. Optional parameters, if desired (REST only): ?query_string

For JSONP, supply the name of your callback method with the optional parameter callback.

For example:

Sample request image

Extended options

A special optional parameter, extendedOptions, adjusts the format and content of the response. The following options are common to many of the APIs:

  • useHTTPErrors (available for all APIs)
  • useInlinedReferences (available on some APIs)
  • includeNewFields (available on all APIs)
  • languageCode (available on some APIs)

To specify these options, simply include them as an optional parameter. Any of the following are valid:

  • extendedOptions=useHTTPErrors
  • extendedOptions=usehTTpeRRors // (not case sensitive)
  • extendedOptions=usehttperrors+useInlinedReferences

Unrecognized options are silently ignored.

Error reporting

extendedOptions=useHTTPErrors

By default, if a REST request to a valid resource results in an error, the server will produce an HTTP 200 status with the error reported in the error element of the response. This approach is friendlier to most javascript frameworks.

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.

Inline versus appendix details

extendedOptions=useInlinedReferences

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:

Accessing additional fields that have been added since initial API version

extendedOptions=includeNewFields

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.

Localization

extendedOptions=languageCode:xx

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.

Supported languages:

  • en - English (Default)
  • ar - Arabic
  • de - German
  • es - Spanish
  • fr - French
  • ja - Japanese
  • ko - Korean
  • pt - Portuguese
  • zh - Simplified Chinese

APIs supporting localization:

  • Airlines - airline names
  • Airports - airport names, city names, street addresses, countries, districts, regions
  • Alerts - airport names, city names, street addresses, countries, districts, regions, airline names, equipment names
  • Delay Index - airport names, city names, street addresses, countries, districts, regions
  • FlightStatus - airport names, city names, street addresses, countries, districts, regions, airline names, equipment names
  • FIDS - airport names, city names, airline names, "prevailing conditions" weather tags, timeliness remarks
  • Ratings - airport names, city names, street addresses, countries, districts, regions, airline names
  • Weather - airport names, city names, street addresses, countries, districts, regions, "prevailing conditions" tags
  • Connections - airport names, city names, street addresses, countries, districts, regions, airline names, equipment names

Response structure and options

API responses always include the following elements:

  • Response-specific data

for example, flightStatus or flightTrack elements. See specific API documentation for an explanation of what is returned by the API.

  • error

    for failed requests, information about the error. (Present but empty for successful requests.)

In addition, some APIs include the following in the response:

  • request

    a summary of the request

  • appendix

    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.

Error Handling

There are two approaches to error handling:

  • Return a 200 code and an error element in the response (default)
  • Return the actual HTTP code and a description of the error in the response body (extendedOptions=useHTTPErrors)

By default, if a REST request to a valid resource results in an error, the server will produce an HTTP 200 status with the error reported in the error element of the response. This approach is friendlier to most javascript frameworks.

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:

  • 200 (OK)

    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.

  • 401 (Unauthorized)

    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.

Summary of request

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:

  • Airline and airport codes are interpreted as ICAO codes, looked up, and then the API uses the associated FS that map to those ICAO codes
  • The codetype specified was icao and the API uppercased it to ICAO as the API is case-insensitive
  • The date is converted to a string to demonstrate how the API interprets the year, month, day fields
  • An airport object for JFK and airline object for AA is included in the appendix

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"

Appendix

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.

Version Policy

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.

Long term support fields

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:

  • Only Long Term Support fields: https://api.flightstats.com/flex/airports/v1/airports/all
  • LTS & Non-LTS Fields: https://api.flightstats.com/flex/airports/v1/airports/all?extendedOptions=includeNewFields

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.

New Versions

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.

Interactive documentation

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:

  1. Click on the name of the web service to expand the test client interface.
  2. Copy your appId and key into the credentials fields
  3. Fill out each required parameter
  4. Send Request to see the actual JSON response. You will also be provided with a curl invocation including a pre-formatted REST URL. To see the XML response, replace the json in the URL with xml.
  5. Please be aware that large responses may take a long time to pretty-print in your browser.

Note that you must provide valid application credentials when you submit requests through the interactive documentation.