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.
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:
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.
Use the following steps to use the Rating APIs.
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.
The Rating APIs have two types of APIs
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.
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.
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.
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.
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.
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:
The following statistics are also included:
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:
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.
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:
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.
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.