Notifications about flight arrival disruptions using the Flightstats API

Passenger-side staff at airports need up-to-date information about disruptions that impact arriving flights. The Multi-flight Alert API can be integrated with your existing software to notify staff of delays, cancelations, and other disruptions.

Audiences

  • Airlines
  • Airports

Platform

FlightStats APIs

Multi-flight alerts

Airports and airlines need to supply up-to-date status of flight arrivals to their staff or companies they contract with. Disruptions to normal operations or a change in aircraft impact the ground crew, baggage handlers, meeters and greeters, terminal staff, shuttle service, and others.

Delays late in the day might require staff to stay longer than expected, or staff may be able to leave early if later flights are canceled.

Our batch alerts monitor flights arriving at an airport and then send alerts when flights are canceled, diverted, seriously delayed, or when there is a change in aircraft type. The alerts are delivered to API integration endpoints on your platform. Your software is then updated, and notifications are sent to the appropriate staff.

Terminology

Term
Definition
Flight
A flight status record is for a single non-stop flight between two points with no stops in between. Direct flights with stops and flights with connections require multiple rules to be set up so that the status of each non-stop flight can be properly monitored.
Flight Rule
A flight rule is an object created for you that tells us to watch for flight status changes based on a configuration provided by you.
Single-flight Rule
Single-flight rules tell us to monitor flight status changes on a single non-stop flight between two points and to send an alert to you when something of significance has occurred.
Multi-flight Rule
Multi-flight rules tell us to monitor flight status changes for all flights matching a criteria. These include departing or arriving at an airport or any flight for a carrier. We'll then send an alert to you when something of significance has occurred.
Flight Alert
We monitor changes to the status of a flight. If the change matches the criteria you are interested in, we'll send a flight alert to an alert callback or delivery endpoint that you’ve specified. The flight alert contains information about the flight rule, the current status of the flight that applies to the rule, and what changed that triggered the alert.
Event
An event identifies what changed in a flight.
Alert Callback / Delivery Endpoint
A secure HTTPS endpoint on your system that we call when a flight alert is triggered.
Validation
For Single-flight rules, we attempt to match the flight provided by you to schedules published by airlines. If we can't, the API returns a validation error. We won't do this if skipValidation is an attribute in the create rule request.

Setting up Multi-flight alerts

Use the following steps to set up Multi-flight status alerts.

1) Get an application ID and key

To get started with Flight Alerts, 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. Flight Alerts requires a contract, but we offer a trial period where you can make up to 500 requests to the Flight Alert APIs to 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) Familiarize yourself with the Multi-flight by Arrival Airport API

The Multi-flight By Arrival API monitors incoming flights for a given airport and alerts your endpoints when the conditions around the flight match the criteria you specify in the rule. The API can be filtered to just report on flights for a particular carrier, multiple carriers, or all carriers at the airport.

3) Choose what alerts you want

Multi-flight alerts can trigger alerts for numerous events. By default, a rule sends alerts on practically every event that occurs with a flight status change. You might also want to customize the events that trigger alerts based on whether you are dropping off or picking up the customer. If you're picking up the customer, you'll want to know if they provided a complete itinerary.

The events that can be configured are available in the Flight Alerts API Reference - Alert Event Fields.

We recommended the following configurations:

Short Description
Event
Description
Canceled
can
Alert on flight cancelation
Diverted
div
Alert for if the flight landed at a different airport than scheduled
Pre-arrival
preArr120,preArr60
Provides alerts at two hours and one hour before arrival
Arrival Delay
arrDelay15
Alert for if the flight arrival appears to be delayed by 15 minutes. This is computed by comparing the estimated gate departure and scheduled gate departure.
Arrival Delay Change
arrDelayDelta15
Subsequent alerts are sent if the delay varies +- 15 minutes from the first delay alert
Arrival Delay Monitoring Window
arrDelayWindow120
Starts monitoring for delay two hours before arrival
Arrival Gate
arrGate60
Alert for changes to the arrival gate that occur within 60 minutes of arrival
Arrival
arr
Alert for when the flight has either touched down on the runway or arrived at the gate

Pro tip

As you begin setting up the alerts, it might be beneficial to set up some alerts that send you emails. These emails contain the normal JSON payload your endpoints receive but don’t require you to have an endpoint set up. You can either create a regular rule or use the Test Delivery API. In either case, you specify smtp://YOUR_EMAIL_ADDRESS as the endpoint. The Test Delivery API allows you to specify the specific type of flight alert event and send the alert immediately, whereas creating a regular rule will deliver alerts based on the normal monitoring of the flight you specify in the rule.

Email deliveries of JSON are only allowed for testing and troubleshooting, not for production use.

4) Create an endpoint to receive alerts

Flight Alerts push alerts to the HTTP or HTTPS URL you specify in the deliverTo parameter. This is a Web endpoint in your infrastructure that you create to consume an HTTP POST message containing the Alerts callback message.

HTTP POST is the only delivery mechanism we support. This means you must have a running Web server configured to accept POST requests to the delivery URL given in the rule. Your Web server will receive Alert Messages in your requested format (JSON or XML) with a structure that contains:

  • An event object that specifies what event triggered the alert, and if applicable, the threshold event value that you specified in the creation of the rule. See Alert Callback Events for details on the applicable events

  • A datasource string that contains the source of data from which the event was detected. This might be helpful for troubleshooting, but in most cases, it can be ignored

  • The date and time the alert was triggered.

  • A rule structure containing the flight rule for the alert.

  • Up-to-date flight status object for the flight associated with the alert

To use the Alerts API, you must implement a Web service that accepts an HTTP POST and parses an Alerts Message, then set up a rule specifying that service as the destination.

When an alert is triggered based on flight status and an active rule, we send a message to the destination.

While you're implementing your endpoint, we recommend using the Test Delivery API and sending test messages for each of the event types your application is expected to receive.

Since the Test Delivery API calls aren't monitoring flights, there is no charge to use them. In addition, you won’t have to wait for events to occur on real flights, but instead trigger events immediately. This dramatically reduces the development and initial testing cycle.

Once each event type has been appropriately coded, you can then create regular flight rules that trigger based on real flights.

Pro tip

If you want an additional level of security to ensure that your endpoint only consumes valid POSTs, we pass a Cirium-Flex-Alert-Key and Cirium-Flex-Alert-Hash in the header of the POST message. For more details on how to set this up, see Cirium Alert key/hash headers.

5) Create a rule

To create a rule, use Multi-flight By Airport Arrival and specify which airport to monitor, whether you want XML or JSON, and the URL of your endpoint that we'll push alerts to.

By default, the API sends an alert for all flights arriving at the airport. To filter to just a single airline, or multiple airlines, specify a comma-separated list of airline codes in the carriers parameter.

In most cases, you’ll likely want to restrict the event types that trigger the alert. See the recommended configuration above. To restrict the list, include a comma-separated list of event types in the events field.

For example, the events string for a recommended configuration would look like:

*events=can,div,arrDelay15,arrDelayDelta15,arrDelayWindow120,arrGate60,arr*

You may set the name and description parameters to identify the rule for a customer or help your system match the flight to some identifier for further processing.

In addition, you can pass in more name and value pairs that are included in the response of the alerts. To use this ability, additional query parameters that begin with an underscore are treated as a name/value pair 'name', with the assigned value treated as the name/value pair value. For example, if you want the name/value pair foo/bar, you should add the query parameter &_foo=bar to the request URI string.

When you successfully create a rule, we’ll return a rule structure containing the ID of the rule. You will likely want to update your internal system with this rule ID so you can match or delete it in the future.

6) Process alerts

We continually monitor flights for which you’ve created flight rules. If an event occurs on a flight and that event is of interest to you, we’ll call your endpoint and deliver the message.

Your endpoint is responsible for processing alerts in a timely fashion. We recommend that when an alert is posted to your endpoint, you queue the alert and process it asynchronously. For example, store the content of the alert in a fast storage system for further processing and return a 200 response immediately.

If we can’t deliver alerts to your endpoint quickly enough (for example, if there is a slowdown on your inbound server), we might delete some of the undelivered alerts to prioritize timely alerts. Provided your queuing mechanism is efficient, you’ll never lose an alert and will be able to better monitor your alert backlog. If you expect a large volume of alerts, let us know, and we can fine-tune the delivery characteristics (such as concurrency and timeout durations) for your account.

If your inbound server goes down, we'll retry for two hours. After that, we’ll purge the stale callbacks because these only cause confusion for the customer. We’ll only retry on a connection failure (such as a connection refused or socket timeout) since we can't be sure we actually reached your host. This also allows you to shut down your systems for maintenance. We'll start delivering alerts where we left off once the system is back up.

We won’t retry if we receive an HTTP response regardless of the HTTP status code. At that point, we were able to deliver the alert even if your host had an error processing it. The reason we do this is so that one problematic entry (regardless of the cause) doesn't cause us to retry over and over and hold up all future alert deliveries.

Additional information

The Flight Alerts APIs include several management APIs that will help you with managing your system and troubleshooting.

To return a list of all the rules registered for your account, use the List API and List LessThan API. They each return up to 1000 rules and allow you to traverse backwards through all the flight rules we've stored for your account. The information is sorted by largest rule ID to smallest.

We delete rules seven days after the scheduled gate arrival. You can only retrieve rules that are less than seven days old, in addition to future rules.

To retrieve the details of a rule, use the FetchRule API to pass the ID of the rule.

Finally, to delete a particular rule, call the Delete Rule API. You can delete any registered rule. If we haven’t already monitored the rule or sent any events, you won’t be charged for the rule. Otherwise, you'll be charged, but the delivery of alerts will stop.

To update a rule, you need to delete it and re-create it. There is no Update API.

FAQs

How do you calculate Alerts API billing?

What are some tips for using the Alerts API?

Do you purge Alerts API stale callbacks if my server goes down?

What is the difference between the Alerts API and the Traveler Trip Alerts API?

How can I quickly test the Alerts API?

Do you support schedule change alerts?

When should I use flight alerts versus flight status?

How do I add authentication to my Alerts API callbacks?

Why can't I retrieve my old Alerts API ruleIds?

Can we whitelist your IP address to ensure we receive alerts?

Do you purge Alerts API stale callbacks if my server goes down?

How do I acquire unique identification for traffic from Cirium using the FlightStats Alerts API?

What is the alertType in a simulated alert?

Does your system retry after an alert delivery failure?

Resources

The FlightStats APIs site provides detailed information about the 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.

The Flight Alerts feature provides an example of an implementation.

Alerts APIs provide push-based alerts of flight status information.

Flight Status and Track by Flight provide a request/response stream of flight status information for all global flights.

Trip Alerts are for traveler-based pushed alerts based on the context of an entire trip, not just individual flights.

Flight Information Display System API is a simple request/response API specifically designed for the needs of FIDS.

Flight Status by Airport APIs provide departure and arrival information for a specific airport.

Flight Status Feed is a data feed of flight information that powers airline or airport operation database systems that in turn power FIDS screens.

Multi-flight alerts are a push-based system that sends updates for flights arriving or departing an airport, or all flights for a airline. These alerts can feed into an Airline or Airport operation database systems that in turn can power FIDS screens.