Avoid airport delays for time-sensitive shipments

There are many reasons why a customer may have an urgent time-sensitive shipment they need to get to the destination. The shipment of pharmaceutical items such as vaccines and perishable goods such as food and plants all require that items arrive without delay. Any delay of important equipment such as engines for aircraft on ground (AOG) can be measured in thousands in dollars for the airline. Critical health items such organs or blood may be a matter of life or death.

In large population areas, you may have multiple airports at your disposal to choose from for the departure or arrival airport. If your shipment involves connection points, you have even more airports to consider. Knowing what is happening at the airports is critical to making the right choice. It's crucial to pick the best performing airport and minimize potential delays.

The Airport Delay Index APIs can be integrated within your systems and applications to provide insight into delays and cancellations occurring at airports around the world.

Audiences

  • Cargo

Platform

FlightStats APIs

Airport Delay Index APIs

The Airport Delay Index APIs return a measure of the level of departure delays that an airport is currently experiencing. Every 30 minutes a process loops through all the airports in our system. For each airport, we look at the flights that were scheduled to depart in the last two hours and for flights that are scheduled to depart in the next hour. We create a score based on the number of flights that are canceled or delayed and if delayed to what severity. Each airport is assigned a score of 0-5. A low index (0-1) indicates that departures are running relatively smoothly. A higher index (4-5) is indicative of significant delays and flight operations disruptions.

Here's a sample of how the index can be mapped to severity

  • 4 to 5 - Excessive
  • 3 to 4 - Significant
  • 2 to 3 - Moderate
  • 1 to 2 - Low
  • 0 to 1 - Very Low

The Airport Delay Index is based completely off of departing flights. There is not an index for arrivals, however if an airport is experiencing a lot of delayed or canceled departures it is usually the case that it is experiencing arrival delays as well.

Calling the Airport Delay Index APIs

Use the following steps to use the Airport Delay Index APIs.

1) Get an application ID and key

To get started with Airport Delay Index APIs, you first need to get an account, an application ID, and a key. See Get an evaluation account for more details on setting up an account. Airport Delay Index 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) Set up your request

The Airport Delay Index has several types of APIs.

By airport

Use this to request delay index information for 1 or more airports. A comma (or any punctuation mark) separated list of airport codes is specified in the request.

By country

Use this to request delay index information for all airports in a particular country. A country code is specified in the request.

By region

Use this to request delay index information for all airports in a particular region of the world. A region (“Africa", "Antarctica", "Asia", "Caribbean", "Central-America", "Europe", "Middle-East", "North-America" "Oceania", "South-America") is specified in the request.

By state

Use this to request delay index information for all airports in a particular US state or Canadian providence. A state/providence code is specified in the request.

All of the above APIs support a format parameter which controls the data format of the response (XML, json, or jsonp).

To filter the response to include only large airports, you can specify a size of airport in the classification filter. The size is a number defined as one to five where one is for the largest airports, and five is for the smallest. We recommend starting at “2” and adjusting the number to return additional or fewer airports.

You can also filter the response to just airports experiencing delays. The score parameter takes a number from one to five, where one is airports with no or low delays and five is airports with excessive delays. Airports with moderate delays and above are usually interesting, so a good starting point would be to specify a “2” for this. However, if you are displaying all airports on a map in a given region, state or country and want to show airports regardless of delay status, then you should omit the parameter.

3) Example requests

The following provides two examples of how to use the APIs. You will need to pick the API that best satisfies your application requirements.

Looking up a single airport

Perhaps your application has a details page about a specific airport. Use the Airport Delay Index By airport API to get a delay index for a specific airport. Besides format and airports, you typically would not specify any additional parameters.

A sample request for AUS looks like:

curl --request GET --url "https://api.flightstats.com/flex/delayindex/rest/v1/json/airports/AUS?appId=YOUR_APP_ID&appKey=YOUR_APP_KEY"

The above query returns the following response:

The first part of the response just repeats information about your request. This part may be helpful if the airport codes you provided aren’t found or get mapped to a different airport than expected. The request takes IATA, ICAO or FS airports codes and attempts to automatically map the airport. This can be controlled using the codeType parameter.

An array of delay indexes is returned. For each delay index, there is detailed information about the airport as well details about the current index for that airport.

The Airport Delay Index APIs always inline airport details within the response regardless of whether useInlinedReferences is set or not.

The response includes the time range that delay index was sampled for as well as the number of overall flights in that time frame and the number of flights (observed) that were used to determine the score. Some flights may be excluded from the observed list for a variety of reasons including not having a published schedule. For all the flights that were observed, a breakdown is provided:

  • canceled - The number of the flights in that time range that are canceled
  • onTime - The number of the flights in that time range that are not delayed or whose delay is currently less than fifteen minutes
  • delayed15 - The number of the flights in that time range that are currently delayed 15-29 minutes
  • delayed30 - The number of the flights in that time range that are currently delayed 30-44 minutes
  • delayed45 - The number of the flights in that time range that are currently delayed 45 minutes or more

The response also includes 3 score related fields:

  • rawScore - A raw delay score for the airport based on the number of observations, departure delays, cancellations, and the time of day at the airport (not normalized). This has limited value, and we recommend using the normalized score instead.
  • normalizedScore - A normalized delay score, from 0 to 5 in increments of .25 (where 5 is maximum delay)
  • delta - This is an indicator of whether problems are getting better or worse at the airport. It is the percentage change in normalized score from the last period based on current observations. Positive values indicate worsening conditions, while negative values indicate improving conditions.

As mentioned above the normalizedScore can be mapped a level of severity

  • 4 to 5 - Excessive
  • 3 to 4 - Significant
  • 2 to 3 - Moderate
  • 1 to 2 - Low
  • 0 to 1 - Very Low

From the example, you can see that AUS is currently experiencing moderate delays and delays are decreasing.

This information can be presented to your customers in a variety of ways. One example is the delay status shown on FlightStats. This is a heat type graph used to show severity from green to red.

Airport delay index heat graph

This kind of view presents a high-level picture but doesn’t necessarily give all the statistical details behind the score. There are other ways of presenting the information. The following example (not based on AUS delay numbers above) shows the information in a pie graph with the number of flights and percent of flights in that bucket. It just illustrates an alternative way of showing the information.

Airport delay index pie graph

Combining delay information with flight listings

The Airport Delay Index By airport API can also be used to mashup information with a Schedules, Flight Status or Connections API call. Make the call to the appropriate API, then loop through the results and build a list of unique airport codes as a comma separated string. You would then submit that string in the airports parameter. The information can then be combined with the flight listing to show flights involving airports currently experiencing problems.

Showing a regional delay map

Dashboard displays of airport delays are a fairly common solution within applications, operation centers, etc.

An example of this is the Airport Delays page on FlightStats.com which shows maps for various regions of the world and indicates major airports and their delay status by using colored icons.

Airport delay index map

In this example, a lot of airports are experiencing low to moderate delays and some airports on the east coast are experiencing more major delays.

The API used for this example is the Airport Delay Index by region API. “North-America” is passed into the region parameter. The map is filtered to just show large airports by passing a “2” in the classification parameter.

Pro tip

The number of airports being displayed on a map application like this should typically correspond with the zoom level of the map. There are a lot of airports in North America, and it doesn’t make sense to display minor airports when a map is zoomed out. As a user zooms in, the classification can be increased to return more airports, and typically the map software would not attempt to place markers for airports outside the current geographic area being shown.

Additional information

The Airport Delay Index is a snapshot of departure information currently at the airport. As mentioned, the delay index is updated every half an hour. Temporarily storing delay indexes gathered throughout the day, could paint a more complete picture of how the airport is performing. For example, perhaps a weather system was over the airport at noon and all flights at that time were delayed. Several hours later, the airport may still be recovering. Perhaps at noon the noon was severe, but by evening delays are moderate and still decreasing. This paints a more complete picture that flights later that night will be less likely to be delayed.

As airport delays typically are a result of bad weather, it is common to display weather information alongside delay information. The METAR for airport API returns the current weather conditions for a given airport.

FAQs

How do you calculate the delay index?

Can you alert me if a delay index increases?

How does your delay index differ from the information on the FAA airport delay map?

Resources

The 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.

FlightStats Weather APIs are a powerful companion to the Airport Delay Index APIs. Current and forecasted conditions are available.