Flight Status Feed API

Download OpenAPI specification:Download

Introduction

The Flight Status Feed API, part of the FlightStats APIs, provides all of FlightStats’ worldwide flight records. Every commercial scheduled flight is added to our system as a Flight Status record and updated multiple times. This API is a complete set of all those Flight Status records along with all updates. A record will typically get its first status update on create approximately 3 days before departure and the feed will show updates to the flight as they happen until the flight is complete.

The feed is a stream of the changes to flight records, not a lookup mechanism. For lookups, please see the Flight Status APIs.

Updates to our entire data set occur about once every six seconds on average throughout the day. The Flight Status Feed is throttled to 3000 requests per minute per user account as a safeguard against runaway processes that could slow down the entire system. To reduce the chance of hitting the rate limiter, your software will need to sleep 10 seconds if you see an empty /next operation.

Reference data

Due to the volume of data provided in the data feed, Airlines, Airport, and Equipment objects are not included in the response payload. You will need to lookup the reference data separately to expand information for those objects.

Workflow

There are two types of requests made to this API. You need to make a call to fetch an available list of flight status payloads and then use the urls provided to retrieve the flight statuses themselves. The “list of items” request has three resource options:

  • latest
  • next/{count}
  • previous/{count}

Sample Latest Payload

Sample List Payload

Each unique url is used to request a payload that contains one-to-many flight statuses. The response contains the request and list of flightStatus.

Sample Flight Statuses Payloads

Use cases

Case #1: Starting at a given point in time

  1. Request 'latest'
  2. Request and process payload of the 'latest' unique url
  3. Using the same unique url, request the next/'n' list
  4. Loop through this list of unique urls, requesting and processing the flight status payloads
  5. When finished use the last unique url to request the next/'n'
  6. Continue

Note: If you request next/100 and our system only has 75 available it will return 75 unique urls. If it returns 0 urls, then there are no items in the feed after that particular item. This is a common situation since a typical scenario is to ask for new entries every 10-15 seconds and it's possible no new entries have been added since the last request.

Case #2: Recovery

  1. Using the unique url of the last successfully processed payload, request the next/’n’
  2. Loop through these unique urls and until finished and request next/’n’

Case #3: Simultaneous retrieval

The list of unique urls is immutable so you can retrieve multiple flight status payloads simultaneously (for example via multiple threads or processes) without fear of duplication or missing data.

Notes about flight status payloads

Each flight status record can be updated multiple times. Each update creates a new entry in the Flight Status Feed. All updates are included with the payload so that the latest flight status has the complete set of changes within it.

Open source Java client for the Flight Status Feed

This open source code repository provides a pattern for how to consume the Flight Status Feed. See the README file for more details.

Extended options

Changes to extended options

  • includeNewFields - Existing fields will not be changed without an API version change, but new fields may be added at any time. Effectively, the extendedOption "includeNewFields" is always true for the Flight Status Feed and can't be disabled. Clients should configure their parsers to be lenient and ignore unexpected fields.
  • useInlinedReferences - This is not a valid option for this API
  • includeDeltas - This is always true for this API

Licensing

The Flightstats data feed is a premium APIs and only available in the Contract plan.

A breakdown of the available plans is available on Get evaluation account

Schemas

Click the download button at the top of this document to download the OpenApi spec for this API. Other schemas:

Related articles

Cirium flight status - Explanation of Cirium flight status data set

Codeshares and wet lease relationships - Explanation of codeshares and wet lease relationships

Related products

Flight Status - Current flight information for flights about three days in advance of departure until about seven days after arrival

Flight Alerts - Push based alerts for single flights or bulk

Flight Data (Laminar Data Hub) - Status and positional data appropriate for geospatial-aware applciations

Authentication

appIdQueryParam

ID of the application making the request

Security Scheme Type API Key
Query parameter name: appId

appKeyQueryParam

Authentication key of the application making the request

Security Scheme Type API Key
Query parameter name: appKey

appIdHeader

ID of the application making the request

Security Scheme Type API Key
Header parameter name: appId

appKeyHeader

Authentication key of the application making the request

Security Scheme Type API Key
Header parameter name: appKey

Retrieve an item

Retrieve a feed item that may contain one or more flight status entries

path Parameters
format
required
string
Enum: "json" "xml"
Example: json

The data format returned in the response

itemId
required
string

The full id of the feed item

query Parameters
extendedOptions
Array of strings
Items Enum: "languageCode:en" "languageCode:ar" "languageCode:de" "languageCode:es" "languageCode:fr" "languageCode:ja" "languageCode:ko" "languageCode:pt" "languageCode:zh"

Extended options for modifying standard API behavior to fit special use cases

Responses

Response samples

Content type
No sample

Return latest item

Return the url of the latest feed item

path Parameters
format
required
string
Enum: "json" "xml"
Example: json

The data format returned in the response

query Parameters
extendedOptions
Array of strings
Items Enum: "languageCode:en" "languageCode:ar" "languageCode:de" "languageCode:es" "languageCode:fr" "languageCode:ja" "languageCode:ko" "languageCode:pt" "languageCode:zh"

Extended options for modifying standard API behavior to fit special use cases

Responses

Response samples

Content type
No sample

List next URLs

List the next N URLs after the given feed item URL

path Parameters
format
required
string
Enum: "json" "xml"
Example: json

The data format returned in the response

itemId
required
string

The full id of the feed item

batchSize
required
string

How many item urls to list

query Parameters
extendedOptions
Array of strings
Items Enum: "languageCode:en" "languageCode:ar" "languageCode:de" "languageCode:es" "languageCode:fr" "languageCode:ja" "languageCode:ko" "languageCode:pt" "languageCode:zh"

Extended options for modifying standard API behavior to fit special use cases

Responses

Response samples

Content type
No sample

List previous URLs

List the previous N URLs before the given feed item URL

path Parameters
format
required
string
Enum: "json" "xml"
Example: json

The data format returned in the response

itemId
required
string

The full id of the feed item

batchSize
required
string

How many item urls to list

query Parameters
extendedOptions
Array of strings
Items Enum: "languageCode:en" "languageCode:ar" "languageCode:de" "languageCode:es" "languageCode:fr" "languageCode:ja" "languageCode:ko" "languageCode:pt" "languageCode:zh"

Extended options for modifying standard API behavior to fit special use cases

Responses

Response samples

Content type
No sample
)