Pick flights with high on-time performance

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 the items to 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.

There are usually numerous options of flights to choose from to get the shipment to its destination. You want a flight that isn’t likely to be canceled or delayed. Picking the next flight out might seem the best option, but a later flight may be more likely to arrive on time.

The Flight Rating APIs can be integrated into your applications or systems and provide insight into the historical on-time performance of a flight vs other flights on the same route.

Audiences

  • Cargo

Platform

FlightStats APIs

Ratings APIs

Twice a month Cirium calculates On-Time Performance Ratings for each flight in our system. For each flight, we collect information on how the flight performed vs other flights on the same route over the last 3 months. We look at how often the flight was on-time, delayed and to what extent, canceled or diverted. This information is compared against other flights on the same route, and we rate the flight on the following criteria:

  • Delay Performance - This looks at the number of times the flight was delayed more than a minute, and then calculates average delay and a standard deviation. This is then compared against the delay performance of other flights on the same route, and a score is assigned to it illustrating how well it compares.
  • On-Time Performance Rating - This looks at the number of times the flight arrived on-time (delay < 15 minutes) vs the total number of flights flown. This is then compared against the on-time performance ratings of other flights on the same route, and a score is assigned to it illustrating how well it compares.
  • Overall Rating - This averages the Delay Performance and On-Time Performance Rating for an overall rating for the flight.

The Ratings API returns percentage and “star” ratings. The star rating represents a rating on a scale of 1 to 5. Most applications take that number and display a number of stars for each flight for a quick visual comparison. In addition to the ratings and percentages, a lot of additional statistics are returned which will be described in more detail later in this document.

Flight Ratings are updated twice a month and take into account the most recent delays and cancellations.

Calling the Rating APIs

Use the following steps to use the Rating APIs.

1) Get an application ID and key

To get started with Rating 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. Rating 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 Rating APIs have two types of APIs

Ratings for flight

Returns the calculated ratings information for a given airline and flight number. A rating element is returned for each departure/arrival airport pair that the flight flew during the observed time period.

Ratings for route

Returns the calculated ratings information for all flights having the given departure and arrival airports.

This article will focus on Ratings for route but discusses the per flight usage in the Additional Information section.

A common use case is to combine the results of a schedules lookup with on-time performance ratings. An application looking for direct flights for a given route can issue a call to Schedules By Route By Departure and at the same time issue a call for Ratings for route. The results can then be combined and presented to the user as a list of schedules with on-time performance ratings, providing context on which flights are more reliable.

The API request structure is simple. You specify the data format you want the results in (json, xml, or jsonp) and specify the departure and arrival airports.

To get ratings for flights between Portland and Seattle, the request looks like:

curl --request GET --url "https://api.flightstats.com/flex/ratings/rest/v1/json/route/PDX/SEA?appId=YOUR_APP_ID&appKey=YOUR_APP_KEY"

Pro tip

Airport and Airline objects are returned in an appendix within the results. This dramatically reduces the size of the response as the object does not need to be repeated within each Rating object. If you would rather have the objects inlined with each rating object, then specify useInlinedReferences in the extendedOptions parameter. Just be aware that this may dramatically increase response size.

3) Parse the response

A truncated version of the response for the above query follows:

The example is a truncated example of the response where only two flights are being shown, but this should be enough to walk through the response and highlight things to consider.

Request

The first part of the response contains 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.

Appendix

The last part of the response is an appendix of airlines and airports. This appendix information can be used to present names in addition or instead of codes, as well as providing additional details about the airlines and airports.

Ratings Array

Each flight for the route is returned in a rating object. One thing to note is that Cirium returns ratings objects for all flights that are marketed or operated on the route. The above example highlights this. There is a Rating object for QX 2000 and AS 2000. Horizon Airlines operates the flight and Alaska 2000 markets it. In this particular case the flight is wet lease and the Horizon flight would typically not be displayed. For more information on these relationships see Codeshare and wet lease relationships. The information in each object is the same because this is the same flight.

The only difference is that the Alaska flight shows all of its 54 observed flights were codeshares.

"codeshares": 54, "observations": 54,

The Horizon flight shows that it operated all of its 54 observed flights.

"codeshares": 0, "observations": 54,

There is not any linkage between the flights, but this typically is not a problem as the ratings objects are usually combined with a flight listing from schedule or other sources, and the flights get mapped accordingly. The schedules API for example includes the information necessary to match these flights.

Each rating object includes the airline code and flight number as well as airport pair. It includes information on the number of observations of this flight over the last three months. This may not be the total of all flights within the same time period. Some flights may not be included. As stated, it also returns the number of those flights that were operated by other carriers in the codeshare property. It also includes a property called directs. Almost all the flights returned by the Rating APIs are non-stop flights that go from point A to B without any stops. A direct flight has a stop somewhere along the line. A stop is not the same as a connection.

Each rating has a breakdown of how many of the flights were on-time, delayed or other:

  • ontime - The number of flights that arrived within 15 minutes of its scheduled arrival time
  • late 15 - The number of flights where the arrival was delayed between 15-29 minutes
  • late 30 - The number of flights where the arrival was delayed between 30-44 minutes
  • late 45 - The number of flights where the arrival was delayed 45 minutes or more
  • cancelled - The number of flights that were canceled
  • diverted - The number of flights that were diverted to another airport

The following statistics are also included:

  • ontimePercent - The percentage of observations that were on-time
  • delayObservations - The total number of flights that were delayed more than 1 minute
  • delayMean - The mean of all delayed observations
  • delayStandardDeviation - The standard deviation of delay
  • delayMin - The minimum delay value observed
  • delayMax - The maximum delay value observed

All the above information is then calculated into the actual rating scores (Ontime, Delayed, and Overall) that was discussed above. The allStars property contains the overall star rating which is typically used to display a star rating. A common pattern is to display stars similar to the following:

Visual of a single rating star pattern

This breaks down the stars into half stars to help further show differences between flights

Pro tip

Not all flights have ratings. Ratings are calculated twice per month and require that the flight has flown a minimum number of times in the past two months in order to accurately judge performance against other flights.

Additional information

In addition to displaying a star rating for a flight, it may be useful to surface the details behind the rating to your customers. As shown above there’s a lot of detailed information included with each rating. A details page or small popup can surface additional details about the rating.

As an example, customers of FlightStats.com can look at the on-time performance of a flight on the flight tracker application. A sample screen looks like the following:

Visual of detailed rating breakdown

Ratings Drop

Request/response APIs may not be the most efficient solution for your application. For high-volume applications that require more up-front processing or caching, Cirium offers a bi-monthly ratings drop where a data file containing all the rating data is available for download. The file can then be combined within your systems. For more information on the Ratings Drop, please contact us.

FAQs

What is the Ratings API?

Resources

The Connections API returns connecting and direct flights between airports. It is highly configurable with specific APIs for the Cargo industry including First flight in/out and Last flight in/out.

Cirium offers monthly On-time Performance Reports for airlines and airports as well as annual performance awards for best performing airlines and airports.

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.