Notifications of equipment changes

Airport ground handling staff must be updated about last-minute equipment changes. The Multi-flight alerts can be integrated with your existing software to notify ground crews of changes to aircraft equipment types and/or tail numbers.

Audiences

  • Airlines
  • Airports

Platform

FlightStats APIs

Multi-flight Alerts

Ground handling services must be notified of any changes to the expected aircraft that they’ll be servicing. A last-minute change can dramatically impact sequencing and turn-around time. Ground handlers need to know as early as possible about changes to ensure the proper ground support equipment is available and ready to go. They also need to know what staff to have available in case a different type of aircraft arrives than was originally scheduled.

Our Multi-flight alerts monitor flights and send alerts about any change to equipment type or tail numbers of the aircraft you’re tracking. The alerts are delivered to API integration endpoints on your platform, where your software is updated and notifications are sent through the appropriate channels to the relevant staff.

Terminology

Term
Definition
Flight
The flight alert system is tied directly to our flight status system. There, a flight status record is created for a single non-stop flight from one airport to another with no stops in between. Direct flights with stops and flights with connections require multiple rules so that the status of each non-stop flight can be 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 you provide.
Single-flight rules
Single-flight rules tell us to monitor flight status changes on a single non-stop flight between one airport and another. We’ll send you an alert if something significant happens.
Multi-flight rules
Multi-flight rules tell us to monitor flight status changes for all flights matching a criteria. Criteria includes departures and arrivals at an airport or any flight for a carrier. We’ll send you an alert if something significant happens.
Flight alert
We monitor changes to the status of a flight. If the change matches the criteria you are interested in, We’ll send you 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.

Setting up Multi-flight alerts

Use the following tasks to set up Multi-flight Alerts.

1) Get an application ID and key

To get started with Multi-flight alerts, you first need to get an account and an application ID and key. See Get evaluation account for more details about setting up an account. Multi-flight Alerts require a contract. While we offer a trial period for single-fight alerts, we don’t for Multi-flight Alerts. Please contact us to establish a contract.

Once you have your account, follow the instructions on Get started to acquire an application ID and key. You should also become familiar with the standard FlightStats API platform patterns.

2) Familiarize yourself with the Multi-flight Alert APIs

We offer three Multi-flight Alert APIs:

Your use case determines which API or APIs you need. An airport wanting to monitor all flights for equipment changes creates a multi-flight rule for departures, and another multi-flight rule for arrivals using the airport APIs. An airline wanting to monitor all of its flights would register a multi-flight rule by carrier.

3) Choose the alerts you want

Multi-flight alerts are triggered by many types of events. By default, a rule can send alerts on practically every event that occurs with a flight status change. The events that can be configured are available in the Flight Alerts API Reference - Alert Event Fields.

If you’re only interested in tail number changes, you can pass events=tailNumber as a parameter. There isn’t a way to filter for equipment adjustments.

Since it’s important to look for updates to tail numbers and equipment types, we recommend that you don’t specify a value for events because that means that you’ll receive all alerts. Your application will most likely be interested in all events anyway, as your ground handling services would be interested in important disruption events in addition to equipment changes.

Pro tip

As you begin setting up the alerts, it might be beneficial to set up some alerts to send emails to yourself. These emails contain the normal JSON payload your endpoints receive but don’t require you to have an endpoint setup. 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 type of flight alert event and send the alert immediately. This rule will deliver alerts based on the normal monitoring of the flights you specify in the rule.

Email deliveries of JSON are only allowed for testing and troubleshooting. They’re not for production use.

4) Create an endpoint to receive alerts

The Multi-flight Alert API pushes 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.

Currently, the only supported delivery mechanism is HTTP POST. 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 Messages 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 can be ignored

  • The date and time that the event triggered the alert

  • A rule structure containing the flight rule that the alert is for

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

With tail number and equipment change alerts, the event object may be set to EQUIPMENT_CHANGE. An EQUIPMENT_CHANGE event might include a change to the tail number and/or a change to the equipment code.

Your application can look for this specific event type, but equipment changes and tail number changes might be included in other events as well. If we receive multiple updates to a flight at the same time, a single flight alert will be sent, and the event type will correspond with the update that we consider the highest priority.

For example, you might receive a DEPARTED alert that also contains a tail number change. Equipment changes and tail number changes are considered the lowest priority updates.

Alert priority level (highest to lowest):

  1. Status changes (EN_ROUTE, LANDED, CANCELLED, DIVERTED, UNKNOWN)

  2. Time changes (DEPARTURE_DELAY, ARRIVAL_DELAY, TIME_ADJUSTMENT)

  3. Gate changes (DEPARTURE_GATE, ARRIVAL_GATE)

  4. Baggage changes (BAGGAGE)

  5. Equipment changes (EQUIPMENT_CHANGE)

We recommend that you don't only use the event type. Every flight status object contains an array of the changes for the flight as well as the time that the update occurs. This array can be traversed so that you can see the recent changes to the equipment or tail number.

Note that the flight status updates array contains the entire history of all updates to the flight. You should look at the most recent (based on time) update to determine what has changed.

All equipment and tail number changes are recorded in the text fields array. Fields to look for are:

  • TAL: The tail number of the flight

  • SQP: The scheduled IATA aircraft type code

  • AQP: The actual IATA aircraft type code

Here's an example:

In the above example, the Scheduled Equipment Type was set to “330” at 2022-03-04T20:18:16.202Z. If the update contains only a newText field, then this is the first time that piece of data was set. If it has an originalText field as well, then it's a change update.

In the above example, the update set the tail number for the first time to EI-EAV, and changed the equipment type from 332 to 333.

Your code to detect equipment changes should look for:

  • TAL numbers changing from one setting to another

  • The initial setting of SQP

  • The initial setting of AQP, in which case you compare it to what has been scheduled and see if it’s different

  • Any AQP update

Pro tip

If two or more sources disagree about the equipment or tail number, it's possible that you’ll get updates that are toggling back and forth between two values. You might want to add logic to look through previous updates to see if this happening and notify accordingly. The data quality depends on the data sources we have for the flight. Subsequently, any notification to ground services should be viewed as a heads up, and you should confirm with the airline before making plans or staffing changes.

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. The Test Delivery API calls don’t monitor flights, so there’s 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 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 about how to set this up, see Cirium Alert key/hash headers.

5) Create a rule

To create a rule, use the appropriate Multi-flight or Alerts API based on your use case. We don’t recommend that you specify a value for events for your use case. Instead, filter to only the equipment change alerts.

You can set the name and description parameters to help identify the rule or help your system match the flight to an identifier for further processing. In addition, you can pass in additional name and value pairs that are included in the response of the alerts. To use this feature, 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 the name/value pair foo/bar was desired, 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'll likely want to update your internal system with this rule ID for matching or deleting 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 that’s 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 end point, 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's 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 will retry for two hours. After that duration, we’ll purge the stale callbacks, because these only cause confusion. 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 could also allow 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 because it means we were able to deliver the alert even if your host had an error processing it. The reason we do this is so 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 might be valuable to your system or help you with troubleshooting.

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

To retrieve the details of a rule, use the FetchRule API to pass the ID of the rule you are interested in.

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

To update a rule, you need to delete it and re-create it.

Advanced notifications of equipment changes

Multi-flight alerts are primarily focused on operations of the current day. If you’d like to receive more advanced notifications of equipment and schedule changes, we offer Cirium Market Alerts. These alerts can be configured to send email updates about equipment changes days or weeks ahead of when the flight is scheduled to depart. For more information, see our Thought Cloud article on.

FAQs

How can I quickly test the Alerts API?

How do I add authentication to my Alerts API callbacks?

Does your system retry after an alert delivery failure?

Resources

Multi-flight Alert APIs create rules that monitor for flights arriving at an airport. They can also monitor flights that are operated by a set of carriers.

Flight Alerts API Reference - Alert Event Fields define the events for which notifications will be generated and sent to the configured callback address.

Alerts API provide access to push-based alerting of flight status information.