Alerts API

Skip to the Interactive Docs

The Alerts API offers access to push-based alerting of flight status information. Alert subscription is initiated by creating a Rule. There are two types of rules:

Single Flight Rules monitor a specific individual flight. When the flight ends, the monitoring ends. Single flight rules are created with these endpoints:

  • By Departure: A flight identified by its departure airport and time (e.g. AA100 departing JFK on 2018/12/2)
  • By Arrival: A flight identified by its arrival airport and time (e.g. AA100 arriving at LHR on 2018/12/3)
  • By Route Departure: Same as By Departure, but both the departure and arrival airport are specified
  • By Route Arrival: Same as By Arrival, but both the departure and arrival airport are specified

Multi-Flight Rules monitor a category of flights, regardless of how many flights that may be. Multi-Flight rules exist until deleted. Multi-Flight rules are created with these endpoints:

  • By Arrival Airport: All flights arriving at a given airport (e.g. all arrivals at LHR)
  • By Departure Airport: All flights departing at a given airport (e.g. all departures from LHR)
  • By Primary Marketing/Operating Carrier: All flights where the carrier is the primary marketer or operator (e.g. all DL flights)

Important Note: These Premium APIs are available within our Contract Plan.

See the specification for handling event notification Alert Message Callbacks.

URI
https://api.flightstats.com/flex/alerts/{protocol}/v1/{format}/{...}
Alert Request
Event Fields, Extended Options
Response
request, error, alerts
Long Term Support (?)
SOAP(deprecated): WSDL | XSD
REST: WADL | XSD
Extended Fields (?)
SOAP(deprecated): WSDL+XSD
REST: JSON | WADL | XSD

Interactive Documentation

  1. Click on the name of the web service to expand the test client interface.
  2. Fill out each required parameter (click app id & key to pre-populate with your credentials)
  3. Send Request to see the actual JSON response. You will also be provided with a curl invocation including a pre-formatted REST URL. To see the XML response, replace the json in the URL with xml.
  4. Please be aware that large responses may take a long time to pretty-print in your browser.

Alert Extended Options

The Alerts API has several unique extended options to support common use-cases. These can be used in conjunction with other Extended Options to customize API behavior to fit specific needs.
Option Description
skipValidation Skips the step of verifying the existence of the flight requested and obtaining the expected alerting capabilities for it. This can be used to force a rule to be registered for a flight that Cirium does not currently have any knowledge about (a flight which is not in the published schedules or detected from operational information). Capabilities are not considered when validating rules.
testRun Parses the request and checks the existence of the requested flight and the expected capabilities for alerting on it (unless "skipValidation" is also included, in which case only the request is validated). This can be used to verify flight alerting capabilities before deciding to register a rule. The rule returned does not contain a unique id, is not stored and will not be alerted on.

Alert Event Fields

The "events" attribute of the request defines the specific events for which notifications will be generated and sent to the configured callback address. Each event (except pre-departure, see table) can be specified once per Alert rule.

The callback events received will depend on the event fields selected. For a mapping of callback events see the Alerts Service Callback Events.

Some events require a parameter value, some allow an optional parameter value, and some do not support a parameter value. The following patterns are used in the "Event" column to indicate parameter use:

dep
No parameter is allowed -- dep
depDelay[#]
An parameter may optionally be supplied -- depDelay or depDelay30
preDep#
A parameter is required -- preDep60

The following table describes in detail the specific events that can be registered and the criteria that will cause a notification for each.

Short Description Event Parameter Examples Full Description
All Detected Changes all None all Alert on any change detected for a flight. This includes any changes to scheduled, estimated, or actual flight times, changes to gates or baggage, and all changes to status: departure, arrival, cancellation, or diversion.

This does not include any pre-departure or pre-arrival notifications, but may be used in combination with them.
Departure dep None dep Alert on confirmed departure.
Arrival arr None arr Alert on confirmed arrival.
Cancelled can None can Alert on flight cancellation.
Diverted div None div Alert on flight diversion (re-routing).
Pre-departure preDep# Required preDep15, preDep60 Alert a configurable number of minutes in advance of the scheduled departure. Up to four (4) pre-departure events can be specified per Alert rule.
Allowable value range: 0 to 1440.
Pre-arrival preArr# Required preArr15 Alert a configurable number of minutes in advance of the scheduled arrival. Up to four (4) pre-arrival events can be specified per Alert rule.
Allowable value range: 0 to 1440.
Departure Delay depDelay[#] Optional depDelay, depDelay15 Alert if the flight departure appears to be delayed by a configurable number of minutes. This is computed by comparing the estimated gate departure and scheduled gate departure. If gate times are not available and runway times have been allowed by including the "depDelayAllowRunway" event flag then the difference between the scheduled runway departure time and estimated runway departure time may be used instead. If the optional number of minutes is omitted, 1 minute is used as the default.
Allowable value range: 0 to 1440.
Departure Delay Change depDelayDelta# Required depDelayDelta15 If a departure delay event has been configured and an alert has been generated for it, this sets the amount of delay change in minutes (plus or minus) required to trigger subsequent alerts. If omitted, then any change in departure delay will be alerted.
Allowable value range: 0 to 1440.
Departure Delay Monitoring Window depDelayWindow# Required depDelayWindow120 The number of minutes in advance of the scheduled departure time during which departure delays should be monitored. If omitted, then delays are monitored for the entire period while the flight is active.
Allowable value range: 0 to 1440.
Allow Runway Times for Departure Delay depDelayAllowRunway None depDelayAllowRunway Allow delay computations to take into consideration runway departure times. Note: A change in runway departure time does not infer a change in checking or boarding time. Care must be used with this option and passenger travel.
Use only Runway Times for Departure Delay depDelayRunwayOnly None depDelayRunwayOnly Generates delay alerts using only runway departure times. Note: A change in runway departure time does not infer a change in checking or boarding time. Care must be used with this option and passenger travel.
Arrival Delay arrDelay[#] Optional arrDelay, arrDelay15 Alert if the flight arrival appears to be delayed by a configurable number of minutes. This is computed by comparing the estimated gate arrival and scheduled gate arrival. If gate times are not available and runway times have been allowed by including the "arrDelayAllowRunway" event flag then the difference between the scheduled runway arrival time and estimated runway arrival time may be used instead. If the optional number of minutes is omitted, 1 minute is used as the default.
Allowable value range: 1 to 1440.
Arrival Delay Change arrDelayDelta# Required arrDelayDelta15 If an arrival delay event has been configured and an alert has been generated for it, this sets the amount of delay change in minutes (plus or minus) required to trigger subsequent alerts. If omitted, then any change in arrival delay will be alerted.
Allowable value range: 0 to 1440.
Arrival Delay Monitoring Window arrDelayWindow# Required arrDelayWindow120 The number of minutes in advance of the scheduled arrival time during which arrival delays should be monitored. If omitted, then delays are monitored for the entire period while the flight is active.
Allowable value range: 0 to 1440.
Allow Runway Times for Arrival Delay arrDelayAllowRunway None arrDelayAllowRunway Allow delay computations to take into consideration runway arrival times. Note: A change in runway arrival time does not infer a change in gate arrival time. Care must be used with this option and passenger travel.
Use only Runway Times for Arrival Delay arrDelayRunwayOnly None arrDelayRunwayOnly Generates delay alerts using only runway arrival times. Note: A change in runway arrival time does not infer a change in gate arrival time. Care must be used with this option and passenger travel.
Departure Gate depGate[#] Optional depGate, depGate240 Alert on changes to the departure gate that occur within the specified number of minutes of departure. If the optional number of minutes is omitted, then changes to the departure gate are monitored at all times while the flight is active.
Allowable value range: 0 to 1440.
Arrival Gate arrGate[#] Optional arrGate, arrGate240 Alert on changes to the arrival gate that occur within the specified number of minutes of arrival. If the optional number of minutes is omitted, then changes to the arrival gate are monitored at all times while the flight is active.
Allowable value range: 0 to 1440.
Baggage Pickup Location bag[#] Optional bag, bag120 Alert on changes to the baggage pickup location that occur within the specified number of minutes of arrival. If the optional number of minutes is omitted, then changes to the baggage pickup location are monitored at all times while the flight is active.
Allowable value range: 0 to 1440.
Tail Number tailNumber Optional tailNumber Alert on changes to the tail number.

Alert Name/Value Support

The 'Create flight rule...' Alert APIs allow callers to pass in name/value pairs that will be included as part of the response of any alerts that are generated.

To use this ability, additional query params that begin with an underscore will be treated as a name/value pair 'name', with the assigned value treated as the name/value pair 'value'.

As an example, if the name/value pair foo/bar was desired, the query param &_foo=bar should be added to the request URI string.

Cirium Alert key/hash headers

When the alert POST is sent, we include two header fields:

  • Cirium-Flex-Alert-Key - A pipe (|) concatenated string of the alert fields listed below.
    • Example: MQ|3424|ORD|CLE|ARRIVAL_DELAY|2020-04-07T16:16:39.388Z
      • The carrier FS code: alert.flightStatus.carrierFsCode (alert.flightStatus.carrier.fs if using inlined references)
      • The flight number: alert.flightStatus.flightNumber
      • The departure airport FS code: alert.flightStatus.departureAirportFsCode (alert.flightStatus.departureAirport.fs if using inlined references)
      • The arrival airport FS code: alert.flightStatus.arrivalAirportFsCode (alert.flightStatus.arrivalAirport.fs if using inlined references)
      • The event type: alert.event.type
      • The event time: alert.event.dateTimeRecorded
  • Cirium-Flex-Alert-Hash - The sha512 HMAC hex encoded hash.
    • Example: bec05d9c9f5e7a28d37c5ea2326c6b4634c1717b6c512793cc6960282c02051abca41e807ae18abe1839b9c30a11def09c21068b66b1193513aaa5696637a738

If the customer wishes to confirm the POST is from Cirium, they can create the same key out of the alert fields and, using their appKey, create the same hash code. The receiver can then compare their computed key/hash with Cirium-Flex-Alert-Key/Hash. Since the appKey, which only Cirium and the customer know, is used as the secret in the hash creation, the customer can be assured the POST is from Cirium and not someone attempting to spoof an alert callback. The sha512 HMAC encoding is not reversible and the customer's appKey is a 32 character hex code, making it secure against hacking via the hash.

Here is a sample of Java code that computes the hash:

public static void main(String[] args) throws Exception {
    String appKey = "fakeAppKey";
    String alertKey = "MQ|3424|ORD|CLE|ARRIVAL_DELAY|2020-04-07T16:16:39.388Z";
    Mac sha512_HMAC = Mac.getInstance("HmacSHA512");
    SecretKeySpec secret_key = new SecretKeySpec(appKey.getBytes(UTF_8), "HmacSHA512");
    sha512_HMAC.init(secret_key);
    String hash = Hex.encodeHexString(sha512_HMAC.doFinal(alertKey.getBytes(UTF_8)));
    System.out.println(hash);
}

Deprecated APIs

SOAP is deprecated. SOAP requests will continue to be served, but enhancements (such as Multi-Flight alerts) may not be available/supported.