Flight Alerts API

Download OpenAPI specification:Download

Introduction

The Alerts API, part of the FlightStats APIs, offers push-based alerting of flight status information. Alerts are based on flight segments and can be triggered on a variety of conditions and status changes. The API allows you to create, retrieve, and delete Alert rules.

To use the Alerts API, the developer 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, FlightStats sends a message to the destination.

To learn more visit the Alerts API Documentation. Events that can trigger an alert are described here.

Flight Alerts alerts recipients when

  • A flight has been delayed or cancelled
  • A flight has departed or arrived
  • A flight’s departure/arrival gate has changed
  • A flight's aircraft equipment or tail number changed

Rule types

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 (for example AA100 departing JFK on 2018/12/2)
  • By Arrival: A flight identified by its arrival airport and time (for example 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 (for example all arrivals at LHR)
  • By Departure Airport: All flights departing at a given airport (for example all departures from LHR)
  • By Primary Marketing/Operating Carrier: All flights where the carrier is the primary marketer or operator (for example all DL flights)

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 you wish to confirm the POST is from Cirium, you create the same key out of the alert fields and, using your 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 you know, is used as the secret in the hash creation, you 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 your 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);
}

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.

  • 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 messages

Alert Messages are produced when an existing alert rule is triggered, and delivered to the destination specified by the rule. 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, structured according to the specification below.

Alert callback fields

Element Cardinality Description
<alert> 1..1 Holder element for an Alert Message
<event> 1..1 The event that has triggered the alert
<type>PRE_DEPARTURE_STATUS</type> 1..1 The type of the event triggering the alert, see Alert Callback Events for a complete list
<value>60</value> 0..1 Configured parameter value for events that accept or require additional specification
</event>
<dataSource>FlightHistory</dataSource> 1..1 The source of the data from which the event was detected
<dateTimeRecorded>2012-10-29T13:37:02.022Z</dateTimeRecorded> 1..1 The UTC date and time of the event in ISO-8601 format. yyyy-MM-dd'T'HH:mm:ss.SSSZ
<rule>...</rule> 1..1 The Alert Rule that was triggered. See Alert Rule object in schema below.
<flightStatus> ... </flightStatus> 1..1 The Flight Status structure that triggered the rule. See Flight Status response in Flight Status API
</alert>

Alert callback events

Events received via callback are related to the events registered during rule creation. The relationship though is not always one-to-one. Cirium routinely receives multiple updates to a single flight at a time. When this occurs, the callback event will be what Cirium considers the highest priority update.

For example, Cirium may receive an update to a flight that indicates the flight has arrived that also includes a new baggage claim number. In this case, Cirium will send a single alert and the event type will be LANDED. No BAGGAGE_CHANGE alert would be sent. However, the flight status object included with the LANDED alert would include both changes and those changes would be noted in the associated flight updates array.

Priority level (highest to lowest):

  • Status changes (EN_ROUTE, LANDED, CANCELLED, DIVERTED, UNKNOWN)
  • Time changes (DEPARTURE_DELAY, ARRIVAL_DELAY, TIME_ADJUSMENT)
  • Gate changes (DEPARTURE_GATE, ARRIVAL_GATE)
  • Baggage changes (BAGGAGE)
  • Equipment changes (EQUIPMENT_CHANGE)

The following table indicates the events received during callback and the relevant event codes that may result in the given alert.

Event Triggering Event Code(s) Notes
PRE_DEPARTURE_STATUS preDep Sent when the rule is subscribed for preDeparture alerts. The alert is sent relative to the scheduled depature time.
PRE_ARRIVAL_STATUS preArr Sent when the rule is subscribed for preArrival alerts. The alert is sent relative to the scheduled arrival time.
EN_ROUTE any When Cirium observes that the flight departs from the gate
LANDED any When Cirium observes that the flight has landed
CANCELLED any When Cirium observes that the flight has been cancelled
DIVERTED any When Cirium observes that the flight has been diverted to another arrival airport
DEPARTURE_DELAY any When Cirium observes a change in the departure time and the change meets the customer's depDelay or depDelayDelta criteria (note, despite the event name, this also applies if the time changes to depart early)
ARRIVAL_DELAY any When Cirium observes a change in the arrival time and the change meets the customer's arrDelay or arrDelayDelta criteria (note, despite the event name, this also applies if the time changes to arrive early)
BAGGAGE any When Cirium observes a change to the baggage location
TIME_ADJUSTMENT any When Cirium observes a time change for a flight that isn't considered an ARRIVAL_DELAY or DEPARTURE_DELAY. Usually seen when subscribed for "all" events or when the time changes at the same time as a subscribed event (for example baggage and time change occurred in the same update).
DEPARTURE_GATE any When Cirium observes a change to the flight's departure gate
ARRIVAL_GATE any When Cirium observes a change to the flight's arrival gate
EQUIPMENT_ADJUSTMENT any Sent when Cirium observes a change in the tail number or equipment type for the flight. Be warned that this data is highly variable between data sources and is difficult to validate, so Cirium reports most of the observed changes.
UNKNOWN The unknown event is sent when Cirium detects that there is little chance of being able to send events for the registered rule. This can happen if the flight is not scheduled or observed

Licensing

Flight Alert APIs are premium APIS and only available in the Contract plan.

A breakdown of the available plans is available on Get evaluation account

Schemas

Click the download button at the top of this document to download the OpenApi spec for this API. Other schemas:

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

Long term support

Related articles

Notifications about flight arrival disruptions - Showcase article on how to use Multi-flight alerts to monitor for disruption

Notifications of equipment changes - Showcase article on how to use Multi-flight alerts to monitor for equipment changes

Notify ground transportation companies of flight status - Showcase article on how to use Single-flight alerts to monitor for flight changes

Related products

Trip Alerts (Trips & Waivers) - Alerts but based on your traveler's entire trip, not just individual flights

Flight Status - Current flight information for flights about three days in advance of departure until about seven days after arrival

Flight Data (Laminar Data Hub) - Status and positional data appropriate for geospatial-aware applciations

Authentication

appIdQueryParam

ID of the application making the request

Security Scheme Type API Key
Query parameter name: appId

appKeyQueryParam

Authentication key of the application making the request

Security Scheme Type API Key
Query parameter name: appKey

appIdHeader

ID of the application making the request

Security Scheme Type API Key
Header parameter name: appId

appKeyHeader

Authentication key of the application making the request

Security Scheme Type API Key
Header parameter name: appKey

Single flight

Single flight rules

By route with arrival date

Create a flight rule to be monitored for a specific flight between two airports arriving on the given day. Returns the fully constructed flight rule that was created.

path Parameters
format
required
string
Enum: "json" "jsonp" "xml"
Example: json

The data format returned in the response

carrier
required
string
Example: AS

Carrier (airline) code

flightNumber
required
string
Example: 412

Flight number

departureAirport
required
string
Example: SEA

The departure airport code for the flight

arrivalAirport
required
string
Example: PIT

The arrival airport code for the flight

year
required
string
Example: 2021

Four-digit year

month
required
integer <int64> [ 1 .. 12 ]
Example: 12

Month

day
required
integer <int64> [ 1 .. 31 ]
Example: 1

Day of month

query Parameters
name
string <= 64 characters
Default: "Default"
Example: name=AS412 12/1/2021

The name of the rule to be created, for descriptive purposes

desc
string <= 256 characters
Example: desc=AS412 12/1/2021

A description of the rule to be created, for descriptive purposes

type
required
string
Enum: "JSON" "XML"
Example: type=JSON

The format of the alert data to be posted to the 'deliverTo' address: 'JSON' or 'XML'.

deliverTo
required
string

Where the alert data will be delivered - the URL of an HTTP/HTTPS service that accepts POST data. For testing and evaluation purposes (no production use, please), we will also deliver alert data via email if the URL is of the form smtp://username@domain.com.

events
required
string
Example: events=dep,arr,div,can,preDep240,preDep60,bag240

A comma separated list of events that should be emitted for the flight. If omitted, all change events will be sent. See documentation for full example.

codeType
string
Enum: "IATA" "ICAO" "FS"
Example: codeType=FS

Airport code type. If not specified, the code searches in the order: IATA, ICAO, FS.

extendedOptions
Array of strings
Items Enum: "useHttpErrors" "useInlinedReferences" "testRun" "skipValidation" "languageCode:en" "languageCode:ar" "languageCode:de" "languageCode:es" "languageCode:fr" "languageCode:ja" "languageCode:ko" "languageCode:pt" "languageCode:zh"

Extended options for modifying standard API behavior to fit special use cases

Responses

Response samples

Content type
Example

Create Alert response (example is by flight for arrival)

Loading...

By route with departure date

Create a flight rule to be monitored for a specific flight between two airports departing on the given day. Returns the fully constructed flight rule that was created.

path Parameters
format
required
string
Enum: "json" "jsonp" "xml"
Example: json

The data format returned in the response

carrier
required
string
Example: AS

Carrier (airline) code

flightNumber
required
string
Example: 412

Flight number

departureAirport
required
string
Example: SEA

The departure airport code for the flight

arrivalAirport
required
string
Example: PIT

The arrival airport code for the flight

year
required
string
Example: 2021

Four-digit year

month
required
integer <int64> [ 1 .. 12 ]
Example: 12

Month

day
required
integer <int64> [ 1 .. 31 ]
Example: 1

Day of month

query Parameters
name
string <= 64 characters
Default: "Default"
Example: name=AS412 SEA-PIT 12/1/2021

The name of the rule to be created, for descriptive purposes

desc
string <= 256 characters
Example: desc=AS412 SEA-PIT 12/1/2021

A description of the rule to be created, for descriptive purposes

type
required
string
Enum: "JSON" "XML"
Example: type=JSON

The format of the alert data to be posted to the 'deliverTo' address: 'JSON' or 'XML'.

deliverTo
required
string

Where the alert data will be delivered - the URL of an HTTP/HTTPS service that accepts POST data. For testing and evaluation purposes (no production use, please), we will also deliver alert data via email if the URL is of the form smtp://username@domain.com.

events
required
string
Example: events=dep,arr,div,can,preDep240,preDep60,bag240

A comma separated list of events that should be emitted for the flight. If omitted, all change events will be sent. See documentation for full example.

codeType
string
Enum: "IATA" "ICAO" "FS"
Example: codeType=FS

Airport code type. If not specified, the code searches in the order: IATA, ICAO, FS.

extendedOptions
Array of strings
Items Enum: "useHttpErrors" "useInlinedReferences" "testRun" "skipValidation" "languageCode:en" "languageCode:ar" "languageCode:de" "languageCode:es" "languageCode:fr" "languageCode:ja" "languageCode:ko" "languageCode:pt" "languageCode:zh"

Extended options for modifying standard API behavior to fit special use cases

Responses

Response samples

Content type
Example

Create Alert response (example is by flight for arrival)

Loading...

Multi-flight

Multi-flight rules

Multi by arrival airport

Create a Multi-flight rule that monitors for flights arriving at an airport and optionally flights that are operated by a set of carriers.

path Parameters
format
required
string
Enum: "json" "jsonp" "xml"
Example: json

The data format returned in the response

arrivalAirport
required
string
Example: PIT

The arrival airport code to monitor for flights

query Parameters
carriers
string
Example: carriers=AS,DL,WN

Comma separated list of airline codes to constrain monitoring. If omitted, all flights matching the arrival will be monitored.

name
string <= 64 characters
Default: "Default"
Example: name=All flights for AS,DL,WN arriving at PIT

The name of the rule to be created, for descriptive purposes

desc
string <= 256 characters
Example: desc=All flights for AS,DL,WN arriving at PIT

A description of the rule to be created, for descriptive purposes

type
required
string
Enum: "JSON" "XML"
Example: type=JSON

The format of the alert data to be posted to the 'deliverTo' address: 'JSON' or 'XML'.

deliverTo
required
string

Where the alert data will be delivered - the URL of an HTTP/HTTPS service that accepts POST data. For testing and evaluation purposes (no production use, please), we will also deliver alert data via email if the URL is of the form smtp://username@domain.com.

events
required
string
Example: events=dep,arr,div,can,preDep240,preDep60,bag240

A comma separated list of events that should be emitted for the flight. If omitted, all change events will be sent. See documentation for full example.

codeType
string
Enum: "IATA" "ICAO" "FS"
Example: codeType=FS

Airport code type. If not specified, the code searches in the order: IATA, ICAO, FS.

includeCodeshares
boolean
Default: false
Enum: true false

Whether the carriers filter should also apply to codeshares. Otherwise, the carriers filter only considers the operator and primary marketer.

extendedOptions
Array of strings
Items Enum: "useHttpErrors" "useInlinedReferences" "testRun" "skipValidation" "languageCode:en" "languageCode:ar" "languageCode:de" "languageCode:es" "languageCode:fr" "languageCode:ja" "languageCode:ko" "languageCode:pt" "languageCode:zh"

Extended options for modifying standard API behavior to fit special use cases

Responses

Response samples

Content type
No sample

Multi by departure

Create a Multi-flight rule that monitors for flights departing an airport and optionally flights that are operated by a set of carriers.

path Parameters
format
required
string
Enum: "json" "jsonp" "xml"
Example: json

The data format returned in the response

departureAirport
required
string
Example: PIT

The departure airport code to monitor for flights

query Parameters
carriers
string
Example: carriers=AS,WN,DL

Comma separated list of airline codes to constrain monitoring. If omitted, all flights matching the arrival will be monitored.

name
string <= 64 characters
Default: "Default"
Example: name=All flights for AS,DL,WN departing from PIT

The name of the rule to be created, for descriptive purposes

desc
string <= 256 characters
Example: desc=All flights for AS,DL,WN departing from PIT

A description of the rule to be created, for descriptive purposes

type
required
string
Enum: "JSON" "XML"
Example: type=JSON

The format of the alert data to be posted to the 'deliverTo' address: 'JSON' or 'XML'.

deliverTo
required
string

Where the alert data will be delivered - the URL of an HTTP/HTTPS service that accepts POST data. For testing and evaluation purposes (no production use, please), we will also deliver alert data via email if the URL is of the form smtp://username@domain.com.

events
required
string
Example: events=dep,arr,div,can,preDep240,preDep60,bag240

A comma separated list of events that should be emitted for the flight. If omitted, all change events will be sent. See documentation for full example.

codeType
string
Enum: "IATA" "ICAO" "FS"
Example: codeType=FS

Airport code type. If not specified, the code searches in the order: IATA, ICAO, FS.

includeCodeshares
boolean
Default: false
Enum: true false

Whether the carriers filter should also apply to codeshares. Otherwise, the carriers filter only considers the operator and primary marketer.

extendedOptions
Array of strings
Items Enum: "useHttpErrors" "useInlinedReferences" "testRun" "skipValidation" "languageCode:en" "languageCode:ar" "languageCode:de" "languageCode:es" "languageCode:fr" "languageCode:ja" "languageCode:ko" "languageCode:pt" "languageCode:zh"

Extended options for modifying standard API behavior to fit special use cases

Responses

Response samples

Content type
No sample

Multi by carrier

Create a Multi-flight rule that monitors for flights that are associated with a particular marketing or operating carrier.

path Parameters
format
required
string
Enum: "json" "jsonp" "xml"
Example: json

The data format returned in the response

carrier
required
string
Example: AS

The marketing or operating carrier to monitor for flights

query Parameters
name
string <= 64 characters
Default: "Default"
Example: name=All flights marketed or operated by AS

The name of the rule to be created, for descriptive purposes

desc
string <= 256 characters
Example: desc=All flights marketed or operated by AS

A description of the rule to be created, for descriptive purposes

type
required
string
Enum: "JSON" "XML"
Example: type=JSON

The format of the alert data to be posted to the 'deliverTo' address: 'JSON' or 'XML'.

deliverTo
required
string

Where the alert data will be delivered - the URL of an HTTP/HTTPS service that accepts POST data. For testing and evaluation purposes (no production use, please), we will also deliver alert data via email if the URL is of the form smtp://username@domain.com.

events
required
string
Example: events=dep,arr,div,can,preDep240,preDep60,bag240

A comma separated list of events that should be emitted for the flight. If omitted, all change events will be sent. See documentation for full example.

codeType
string
Enum: "IATA" "ICAO" "FS"
Example: codeType=FS

Airport code type. If not specified, the code searches in the order: IATA, ICAO, FS.

extendedOptions
Array of strings
Items Enum: "useHttpErrors" "useInlinedReferences" "testRun" "skipValidation" "languageCode:en" "languageCode:ar" "languageCode:de" "languageCode:es" "languageCode:fr" "languageCode:ja" "languageCode:ko" "languageCode:pt" "languageCode:zh"

Extended options for modifying standard API behavior to fit special use cases

Responses

Response samples

Content type
No sample

Management

Management

Delete rule

Deletes a flight rule that was previously created given a rule ID. Returns the flight rule that was deleted. Note that once deleted any subsequent calls with the same ID will return a rule not found exception. Single Flight Rules are automatically deleted 7 days after the date of departure.

path Parameters
format
required
string
Enum: "json" "jsonp" "xml"
Example: json

The data format returned in the response

ruleId
required
integer <int64>
Example: 10023

ID of created rule.

query Parameters
extendedOptions
Array of strings
Items Enum: "useHttpErrors" "useInlinedReferences"

Extended options for modifying standard API behavior to fit special use cases

Responses

Response samples

Content type
Example

Delete alert response

Loading...

Retrieve rule

Returns the flight rule that was previously created given a rule ID.

path Parameters
format
required
string
Enum: "json" "jsonp" "xml"
Example: json

The data format returned in the response

ruleId
required
integer <int64>
Example: 102235

ID of created rule.

query Parameters
extendedOptions
Array of strings
Items Enum: "useHttpErrors" "useInlinedReferences"

Extended options for modifying standard API behavior to fit special use cases

Responses

Response samples

Content type
Example

Retrieve alert response

Loading...

List rules

Returns at most the last thousand Alert Rule IDs. See the alternative form of this to specify the max Rule ID, which allows for iteration over all Rule IDs.

path Parameters
format
required
string
Enum: "json" "jsonp" "xml"
Example: json

The data format returned in the response

query Parameters
ruleFilter
string

Criteria used to return specific rules. Options are: 'batch', 'single', or 'all'. If omitted, defaults to 'all'.

extendedOptions
Array of strings
Items Value: "useHttpErrors"

Extended options for modifying standard API behavior to fit special use cases

Responses

Response samples

Content type
No sample

List rules less than Rule ID

Returns at most the last thousand Alert Rule IDs that are less than the given max Rule ID. See the alternative form of this list the last 1000 Rule IDs.

path Parameters
format
required
string
Enum: "json" "jsonp" "xml"
Example: json

The data format returned in the response

lessThan
required
integer <int64>

Specifies the rules that have an ID less than the provided

query Parameters
ruleFilter
string

Criteria used to return specific rules. Options are: 'batch', 'single', or 'all'. If omitted, defaults to 'all'.

extendedOptions
Array of strings
Items Value: "useHttpErrors"

Extended options for modifying standard API behavior to fit special use cases

Responses

Response samples

Content type
No sample

Test delivery

We made this service to help you create and test your alert webservices, where FlightStats will send alert messages. When you invoke this service, FlightStats will send a simulated alert - a fake event for a fake flight - to your URL.

path Parameters
format
required
string
Enum: "json" "jsonp" "xml"
Example: json

The data format returned in the response

carrier
required
string
Example: AS

Carrier (airline) code

flightNumber
required
string
Example: 412

Flight number

departureAirport
required
string
Example: SEA

Departure Airport code

arrivalAirport
required
string
Example: PIT

Arrival Airport code

query Parameters
type
required
string
Enum: "JSON" "XML"
Example: type=JSON

The format of the alert data to be posted to the 'deliverTo' address: 'JSON' or 'XML'.

deliverTo
required
string

Where the alert data will be delivered - the URL of an HTTP/HTTPS service that accepts POST data. For testing and evaluation purposes (no production use, please), we will also deliver alert data via email if the URL is of the form smtp://username@domain.com.

alertType
required
string
Default: "EN_ROUTE"
Enum: "EN_ROUTE" "LANDED" "DIVERTED" "CANCELLED" "PRE_DEPARTURE_STATUS" "PRE_ARRIVAL_STATUS" "DEPARTURE_DELAY" "ARRIVAL_DELAY" "TIME_ADJUSTMENT" "DEPARTURE_GATE" "ARRIVAL_GATE" "GATE_ADJUSTMENT" "EQUIPMENT_ADJUSTMENT" "BAGGAGE" "TAIL_NUMBER"

The type of the event to trigger an alert on.

extendedOptions
Array of strings
Items Enum: "useHttpErrors" "useInlinedReferences" "languageCode:en" "languageCode:ar" "languageCode:de" "languageCode:es" "languageCode:fr" "languageCode:ja" "languageCode:ko" "languageCode:pt" "languageCode:zh"

Extended options for modifying standard API behavior to fit special use cases

Responses

Response samples

Content type
No sample

Single Flight

By arrival

Create a flight rule to be monitored for a specific flight arriving at an airport on the given day. Returns the fully constructed flight rule that was created.

path Parameters
format
required
string
Enum: "json" "jsonp" "xml"
Example: json

The data format returned in the response

carrier
required
string
Example: AS

Carrier (airline) code

flightNumber
required
string
Example: 412

Flight number

arrivalAirport
required
string
Example: PIT

Airport code

year
required
string
Example: 2021

Four-digit year

month
required
integer <int64> [ 1 .. 12 ]
Example: 12

Month

day
required
integer <int64> [ 1 .. 31 ]
Example: 1

Day of month

query Parameters
name
string <= 64 characters
Default: "Default"
Example: name=AS412 - 12/1/2021

The name of the rule to be created, for descriptive purposes

desc
string <= 256 characters
Example: desc=AS412 - 12/1/2021

A description of the rule to be created, for descriptive purposes

type
required
string
Enum: "JSON" "XML"
Example: type=JSON

The format of the alert data to be posted to the 'deliverTo' address: 'JSON' or 'XML'.

deliverTo
required
string

Where the alert data will be delivered - the URL of an HTTP/HTTPS service that accepts POST data. For testing and evaluation purposes (no production use, please), we will also deliver alert data via email if the URL is of the form smtp://username@domain.com.

events
required
string

A comma separated list of events that should be emitted for the flight, for example 'dep,arr,div,can,preDep240,preDep60,bag240'. If omitted, all change events will be sent. See documentation for full example.

codeType
string
Enum: "IATA" "ICAO" "FS"
Example: codeType=FS

Airport code type. If not specified, the code searches in the order: IATA, ICAO, FS.

extendedOptions
Array of strings
Items Enum: "useHttpErrors" "useInlinedReferences" "testRun" "skipValidation" "languageCode:en" "languageCode:ar" "languageCode:de" "languageCode:es" "languageCode:fr" "languageCode:ja" "languageCode:ko" "languageCode:pt" "languageCode:zh"

Extended options for modifying standard API behavior to fit special use cases

Responses

Response samples

Content type
Example

Create Alert response

Loading...

By departure

Create a flight rule to be monitored for a specific flight departing from an airport on the given day. Returns the fully constructed flight rule that was created.

path Parameters
format
required
string
Enum: "json" "jsonp" "xml"
Example: json

The data format returned in the response

carrier
required
string
Example: AS

Carrier (airline) code

flightNumber
required
string
Example: 412

Flight number

departureAirport
required
string
Example: SEA

Airport code

year
required
string
Example: 2021

Four-digit year

month
required
integer <int64> [ 1 .. 12 ]
Example: 12

Month

day
required
integer <int64> [ 1 .. 31 ]
Example: 1

Day of month

query Parameters
name
string <= 64 characters
Default: "Default"
Example: name=AS412 - 12/1/2021

The name of the rule to be created, for descriptive purposes

desc
string <= 256 characters

A description of the rule to be created, for descriptive purposes

type
required
string
Enum: "JSON" "XML"
Example: type=JSON

The format of the alert data to be posted to the 'deliverTo' address: 'JSON' or 'XML'.

deliverTo
required
string

Where the alert data will be delivered - the URL of an HTTP/HTTPS service that accepts POST data. For testing and evaluation purposes (no production use, please), we will also deliver alert data via email if the URL is of the form smtp://username@domain.com.

events
required
string
Example: events=dep,arr,div,can,preDep240,preDep60,bag240

A comma separated list of events that should be emitted for the flight. If omitted, all change events will be sent. See documentation for full example.

codeType
string
Enum: "IATA" "ICAO" "FS"
Example: codeType=FS

Airport code type. If not specified, the code searches in the order: IATA, ICAO, FS.

extendedOptions
Array of strings
Items Enum: "useHttpErrors" "useInlinedReferences" "testRun" "skipValidation" "languageCode:en" "languageCode:ar" "languageCode:de" "languageCode:es" "languageCode:fr" "languageCode:ja" "languageCode:ko" "languageCode:pt" "languageCode:zh"

Extended options for modifying standard API behavior to fit special use cases

Responses

Response samples

Content type
Example

Create Alert response (example is for arrival)

Loading...
)