Alerts API

Skip to the Interactive Docs

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

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: WSDL | XSD
REST: WADL | XSD
Extended Fields (?)
SOAP: WSDL | XSD
REST: 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 FlightStats 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 three (3) 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. One (1) pre-arrival event can be specified per Alert rule.
Allowable value range: 0 to 1440.
Departed Late depLate# Required depLate15 Alert if the flight has not departed by a configurable number of minutes later than the scheduled departure. This differs from the departure delay event in that it will not be sent until after the elapsed number of minutes past the scheduled departure, regardless of when the delay is detected.
The minutes specified MUST be one of: 15, 30, 45, 60.
Arrived Late arrLate# Required arrLate30 Alert if the flight has not arrived by a configurable number of minutes later than the scheduled arrival. This differs from the arrival delay event in that it will not be sent until after the elapsed number of minutes past the scheduled arrival, regardless of when the delay is detected.
The minutes specified MUST be one of: 15, 30, 45, 60.
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, 0 minutes 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.
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, 0 minutes is used as the default.
Allowable value range: 0 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.
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.

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.