Notify ground transportation companies of flight status

Ground transportation companies are routinely responsible for picking up and dropping off customers at an airport. To ensure on-time drop off and pick up, and minimize wasted curb time it’s necessary to know the status of the customer’s flights.

The Flight Alerts API can be integrated with the existing software your drivers use to proactively notify them of any change in estimated departure time, arrival time, or other events.

Audience

  • Ground transportation

Platform

FlightStats APIs

Flight Alerts API

Customers make reservations for pickup and drop-off at airports. Typically, they provide the flight number when making the booking so that drivers can track the customer’s flight, and know where to pick up or drop off the customer at the airport.

If flights are canceled, delayed, or have other irregular operations, ground transportation workers want to be informed. Our Alerts APIs can be used to monitor the flight and update your systems so that dispatch and drivers alike have real-time information on any change to the status of the flight.

The API is configurable to monitor only what is needed so as to not overwhelm the driver with unnecessary alerts. The alerts are delivered to API integration endpoints on your platform, at which time your software can be updated and notifications sent to the driver.

Terminology

Term
Definition
Flight
The flight alert system is tied directly to our flight status system. 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 send an alert when something significant has happened.
Multi-flight Rule
Multi-flight rules tell us to monitor flight status changes for all flights matching a criteria (departing or arriving at an airport or any flight for a carrier) and to send an alert to you when something significant has happened.
Flight Alert
We monitor changes to the status of a flight. If the change matches the criteria you are interested in, we 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 it's unable to do so, the API returns a validation error unless skipValidation is provided as an attribute in the create rule request.

Setting up Flight Alerts

Use the following tasks to set up 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 details about 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) Determine which API to use to create the flight rule

Flight Alert Single Flight Rules are appropriate for monitoring a customer’s flight. How you configure the rules depends on the amount of information you have from your customer and if you are dropping off the customer or picking up the customer.

In the case where you're dropping the customer off at the airport, use the Single Flight rule by departure to monitor potential delays or cancelations.

Picking up the customer is more complex. If the customer’s trip involves connections or stops and they provide a full itinerary, we recommend that you create rules for every flight on the itinerary and watch for delay and cancelation events throughout.

For example, let’s say that your customer is traveling from Portland to New York (JFK) with a stop in Chicago. The full itinerary would be PDX->ORD->JFK. If the PDX-ORD flight is canceled, you won’t be picking up the customer in JFK as expected, so it would be good to know that. In this case, use the create flight rule for the route with departure dates, but adjust the events you are interested in for the earlier flights so that its contextually relevant. You will most likely be more interested in events on the ORD-JFK flight, but the cancelation event is particularly important for the PDX->ORD flight. If the flight is severely delayed at PDX, the likelihood of the customer making the connection at ORD is also a risk worth monitoring.

If all that is provided by a customer is the flight number of the departing flight or arriving flight, we recommend:

  • Single-flight rule by departure to monitor flights on behalf of your customer when you are dropping off the customer at the airport

  • Single-flight rule by arrival to monitor flights on behalf of your customer when you are picking up the customer at the airport

In the above example, if the PDX->ORD->JFK flight were on a single carrier with the same flight number (not uncommon in the industry), don’t be tempted to create a single by route request for PDX-JFK. The flight alert system is based on individual non-stop flights. The rule request may succeed, but the only flight that will be monitored is PDX->ORD and the rule structure that is returned by the request will indicate that.

3) Determine what you want to be alerted about

Flight Alerts can trigger alerts for numerous events. By default, a rule will send alerts on practically every event that occurs with a flight status change. This may be desired, but more than likely you will want to customize the events that trigger alerts based on whether you are dropping off the customer or picking up the customer, and if picking up whether or not the customer provided a complete itinerary or not.

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

The recommended configurations are as follows:

For drop off

Short Description
Event
Description
Canceled
can
Alert for flight cancelation
Pre-departure
preDep120,preDep60
This sets up alerts at two hours and one hour before departure.
Departure Delay
depDelay15
Alert if the flight departure appears to be delayed by 15 minutes. This is computed by comparing the estimated gate departure and scheduled gate departure.
Departure Delay Change
depDelayDelta15
Subsequent alerts will be sent if the delay varies plus or minus 15 minutes from the first delay alert
Departure Delay Monitoring Window
depDelayWindow120
Starts monitoring for delay for two hours before departure
Departure Gate
depGate60
Alert for changes to the departure gate that occur within one hour of departure.
Departure
dep
Alert for departure if you want to know for sure that the customer’s flight departed

For pick up at the arrival airport

Short Description
Event
Description
Canceled
can
Alert for flight cancelation
Diverted
div
Alert if the flight landed at a different airport than scheduled
Pre-arrival
preArr120,preArr60
This provides alerts at two hours and one hour before arrival
Arrival Delay
arrDelay15
Alert 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 will be 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
Baggage Pickup Location
bag60
Alert for changes to the baggage pickup location that occur within 60 minutes of arrival

For upline flights of the customer when picking up the customer

Short Description
Event
Description
Canceled
can
Alert for flight cancelation
Diverted
div
Alert if the flight landed at a different airport than scheduled
Arrival Delay
arrDelay15
Alert if the flight arrivals 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 will be sent if the delay varies plus or minus 15 minutes from the first delay alert
Departure
dep
Alert for departure if you want to know for sure that the customer’s flight departed.
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 to send emails to yourself. 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.

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

To use the Alert APIs, 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, FlightStats sends 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. As the Test Delivery API calls are not 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 from us, 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 for more details.

5) Create a rule

To create a rule, use the appropriate API (Single-flight rule by departure or Single-flight rule by arrival) and specify the flight date and airport, whether you want XML or JSON, and the URL of your endpoint that we'll push alerts to.

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 the “For drop-ff” example configuration above would look like:

events=can,preDep120,preDep60,depDelay15,depDelayDelta15,depDelayWindow120,depGate60,dep

The name and description parameters can optionally be set to help identify the rule for a customer or perhaps help your system match the flight to some identifier for further processing. In addition you can pass in additional name/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 the name/value pair foo/bar was desired, you should add the query parameter &_foo=bar to the request URI string.

When you create a rule, we attempt to immediately match the rule to a scheduled flight within our schedule system. This is so we can ensure that we can monitor the rule appropriately. If for some reason, we can’t find a schedule that matches the criteria specified, the rule will return a 400 status code with a message stating: “The rule relates to no known flights and would be unlikely to produce any alerts."

If you are sure that this is a flight that can be monitored, you can override this validation by specifying skipValidation in the extendedOptions field. We provide validation as an extra check to make sure you aren’t charged for monitoring flights we know nothing about. However, if you override, we’ll attempt to continue monitoring the flight based on information from other data sources or updates that occur closer to departure, and you will be charged for monitoring even if the flight remains unknown.

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

Pro tip

We recommend that you queue rule submissions so that your system can tolerate temporary FlightStats outages or varying latency. In particular, we recommend that you don’t invoke the Alerts API rule create feature on a user interface thread.

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 systems 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 will retry for two hours. After that duration, 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 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 backward through all the flight rules we have 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 you are interested in.

Finally, to delete a 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 delivery of events 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 an airline. These alerts can feed into an Airline or Airport operation database systems that in turn can power FIDS screens.