Firehose Documentation Center

Our firehose server port 1501 is available on the wide internet without any restrictions on the FlightAware side. All connections to firehose are TCP/IP established in the direction towards FlightAware.

However, your own corporate firewall might potentially have restrictions on what addresses or port numbers you are permitted to connect to. If this is true with your corporate policy, then you will need to ask your own IT or Network security department to add a rule to allow your application to connect to our servers on that port number.

In some extreme IT policy cases, it may also be easier for you to open a cloud hosted server account (Amazon EC2 or similar) and connect to our Firehose service from that system.

The maximum number of allowable connections for Firehose is four per user account. One connection is suggested for your production environment and one connection for your development environment. Additional connection licenses are available upon request from your account represenative.

When your application connects to Firehose, it sends an initiation command that can optionally specify a version number that indicates the protocol version of the responses that your application has been designed for.

Over time, FlightAware will introduce new version numbers that may add new element names to existing messages or change the behavior of existing elements.

Applications that specify an older version number in their initiation commands will continue to receive messages that conform as closely as technically possible to that older version. If your application does not specify a specific version number in its initiation command, then it will always receive data conforming to the latest version number supported by the server.

We recommend that customers design their applications to always explicitly request the current Firehose version number at the time of publishing. Additionally, it is highly recommended that your application be updated to explicitly request the latest version when new Firehose versions are announced or published. This will ensure that you are able to benefit from all of the latest improvements, which can sometimes improve the data quality.

In general, FlightAware will send an email to all Firehose customers at least a month in advance of any new version number being officially released. The email will include a description of the changes and provide an opportunity for accessing a test server containing a preview version prior to its release.

The expected downlink message volume is approximately 1 Mb/s average with typical peaks of 4 Mb/s for a full feed, but this will vary depending on the type of events and filtering being requested.

The Keepalive command is a way to instruct the Firehose server to generate a minimum amount of activity on the connection for the purpose of demonstrating that the connection is still active. The message interval is based on realtime seconds, represented as the serverTime field in the message. If the keepalive message is not received in the stated interval it is an indication that there is no longer connectivity to the Firehose server and the connection should be retried.

Keepalive messages will also contain a pitr value. This value should also be advancing, but not necessarily at the same rate as the keepalive interval, to indicate a low message volume connection is still following the event stream. If this value stops advancing it is another indication that there is no longer proper connectivity and the connection should be retried.

It is still best practice to have an idle connection handler that will still automatically re-connect even if keepalive messages are received.

The initiation command, including whitespace, can be up to 5120 characters in length.

Some users may have connections that last over a month while others are connected for a few hours. This is primarily dependent on the public internet connectivity between FlightAware and receiving system. Even with poor connectivity, an application with robust pitr tracking and re-connection logic can still pull reliable data due to Firehose being capable of emitting data over 100x faster than realtime.

An application with high availability requirements should maintain an active-active connection to a pair of host pools provided by FlightAware. The host names for these pools can be requested from your account representative if needed. These host pools represent geographically distinct hosting locations and provide identical service. The application should be prepared to automatically de-duplicate data received over the pair of connections.

The "id" field in Firehose (named "faFlightID" in AeroAPI) is a unique identifier that is generated by FlightAware for referencing a specific instance of a flight. All Firehose messages that contain the same "id" value can be assumed to be in reference to the same flight.

The meaning of the components within the flight id are not documented as having any public meaning and are purely an artifact of how we generate the ids to be unique. External customers should consider the flight id to be entirely opaque. The FlightAware flight id is meant to be a unique identifier for a particular flight, which comprises of one takeoff and one full-stop landing.

Times are specified as POSIX time also known as UNIX epoch format. Specifically, the number of seconds since 00:00:00 UTC on 1 January 1970. If subsecond resolution is available, the time can be specified floating point. Otherwise the value should be an integer. For example, 1375117735.797 is Monday 29 July 2013 17:08:55.797.

All messages sent by FlightAware on the downlink will be JavaScript Object Notation (JSON) encoded and the character encoding will be plain ASCII.

We use intelligent rate limiting algorithms to minimize the number of positions that are sent when the flight is at cruise, and not at low altitude or maneuvering. During those non interesting phases of flight, a minimum of at least one position per minute is available. During the more interesting phases, there might be 5 positions per minute or so.

At this time, FlightAware is making data available from 2008-01-01 to current. We will consider the possibility of making older data available if there is sufficient user interest in this. By default, all Firehose accounts are limited to accessing data back to the date your Firehose service contract was established unless other arrangements have been made in advance. If you have business needs to access data prior to your start of service, please contact your account representative.

OOOI data may appear in different fields according to which data layers are enabled. As a general rule Off and On events appear in the Flight Status subscription layer (flightplan, arrival, departure) while Out and In events appear in the Extended Flight Info layer (extendedFlightInfo). Customers consuming earlier versions of Firehose may receive Out and In events in the legacy Block Events layer instead.

Below is how each of these events are mapped, in the format of message.field:

	OUT Block out (gate out)	OFF Wheels up (departure)	ON Wheels down (arrival)	IN Block in (gate in)
Filed	extendedFlightInfo.scheduled_out	flightplan.fdt	flightplan.fdt+flightplan.ete	extendedFlightInfo.scheduled_in
Estimated	extendedFlightInfo.estimated_out	flightplan.edt	flightplan.eta OR departure.eta OR position.eta	extendedFlightInfo.estimated_in
Predicted (machine learning)	extendedFlightInfo.predicted_out	flightplan.predicted_off	flightplan.predicted_on	extendedFlightInfo.predicted_in
Actual	extendedFlightInfo.actual_out	departure.adt	arrival.aat	extendedFlightInfo.actual_in

The "ident" is the normalized callsign identifying the flight. Typically, ICAO airline code plus ticketing flight number. If the flight is not operating as an airline operator, then this will just be the aircraft registration.

The "atcident" field is populated only if the flight is actually using a callsign that differs from their flight number (such as with an alpha suffix and a truncated form of the flight number). This practice is more commonly done in Europe to avoid the possibility of multiple instances of the same ident being flown in the same day (see Eurocontrol's call sign similarity service).

The "reg" field will contain the aircraft's registration when the flight is operating as an airline flight. (If the flight was not operating as an airline flight, then the "ident" field is registration and the "reg" field will typically not be included.) In some cases, there is not enough information for us to determine the aircraft's registration for a flight, so this field may not always be available.

By default, only flights operating under a flightplan that we have received are exposed in Firehose. If a flight is operating in a region where FlightAware does not receive public flightplans from the ANSP, then we suppress those flights by default.

Additionally, flights may be missing if the owner/operator has requested that an aircraft be blocked. FlightAware honors blocking requests worldwide, regardless of the current location of the aircraft.

Upon request, your account representative can enable access to "position-only" flights (aka "ad hoc" flights) for your Firehose account. This will enable you to receive data about flights that we do not have full information about. Your application must be prepared to accept flights with: "orig" or "dest" fields that are blank or is a lat/lon position instead of an airport, "ete" and "eta" may be blank, "aircrafttype" may be missing, etc.

Unfortunately we don’t receive block events (also known as OUT of gate or IN gate times) for all airline flights. Smaller general aviation aircraft generally lack the equipment needed to send these events. It mostly depends on the air carrier and whether they send us this info and rights associated with that data. The larger carriers tend to have the best coverage. Additionally, onblock messages may not always be available even if an offblock message is received for the same flight, or vice versa. Approximately 70% of flights have offblock messages and about 60% of flights have onblock messages.

Occasionally there are flightplans that will simply expire because we never receive a departure for it (nor positions that would trigger a synthetic departure). Not all flightplans filed by aircraft operators are actually flown. In some cases though, those flights are actually operating but they simply happen in geographical areas where we do not have coverage for us to detect the departure/arrival.

The "heading" field does not differentiate between the source used to calculate it. In some cases, it may be a magnetic compass heading returned by the aircraft, or it might be the radar track as determined the ANSP, or it might be calculated by FlightAware based on successive lat/lon positions.

The field marked "airspeed_kts" and "airspeed_mach" will actually be airspeed measurements as reported by the aircraft. There is a separate "gs" field that is specifically labelled as groundspeed, if that is what you require.

The "ident" is the normalized identifier that typically consists of the airline identifier and the actual flight number, or just the aircraft registration if it was not an airline flight. When present, the "atcident" will generally be the de-conflicted version of the ident that the flight is identified to ATC as (which typically keeps the same airline identifier in the ident, but truncates or modifies the flight number and sometimes appends up to two letters). For example, a handful of European operators are assigned such an identifier in order to avoid possible similarities in verbal readback of flights that are operating at the same time. The "reg" is the aircraft registration when it is an airline flight, if known. See Eurocontrol's call sign similarity service.

If your application has received details about a flight through the airborne Firehose feed, you can allow your users to view the FlightAware flight tracking page for that specific flight by taking the "id" field (aka faFlightID in AeroAPI) and forming a URL like this: "https://flightaware.com/live/flight/id/" + id Note that "id" values retrieved through the surface-movement Firehose feed are not compatible with this technique, since surface movement data is not currently visible on the FlightAware website.

Firehose employs a sticky matching system for flights based on the filters set in the initiation command. Once a flight matches the filter argument for at least one message all subsequent messages for that flight will be sent until its completion.

FlightAware will generate new predictions as a complete set of times. However, Firehose will deliver Predicted On and Predicted In times in separate messages according to the Firehose message schema definition. This allows possibility that times from different predictions to be combined for taxi time calculation and generate the appearance of invalid predictions. The following are a set of rules to help guarantee that prediction updates are handled in a manner that makes sense. This only applies to cases where both On and In predictions are subscribed to.

• Prediction updates will always appear as ordered matched pairs in Firehose. The Predicted On will appear first in a flightplan message and then the Predicted In in an extendedFlightInfo message.
• The ordered matched pair will appear on the same pitr and contain the same FlightAware flight id.
• A newer prediction (determined by larger pitr value) should always take precedence over an older one

For users that have the Radar Subscription Layer enabled, FlightAware may send estimated position updates if the aircraft is outside of FlightAware's coverage network. These position updates are based on several factors, including last known speed, heading, and route plan. They are indented to demonstrate that the flight is still active, but an actual position update has not been received.

Actual position updates between sets of estimated positions may show unusual track patterns. For tracking and display purposes it is strongly recommended that estimated positions between actual position updates be discarded. If plotting the position updates visually, a great circle line should be used to connect the actual position updates.

The clock field should represent the time a message is emitted from source hardware, idealy the aircraft transponder. In the case of estimated positions this value represents when we made the estimation.

The 'flifo' event standardized the OOOI time fields to 'scheduled', 'estimated', 'predicted' and 'actual' out, off, on and in. If your account is provisioned for both predicted times and out/in extended flifo data, then your client should handle all 16 OOOI time combinations. Of particular note are the following fields with new names:

alt → filed_alt/cruise_alt
edt → estimated_off
eta → estimated_on
fdt → scheduled_off
speed → filed_airspeed

Included in 'flifo' messages are the new fields 'actual_runway_off' and 'actual_runway_on' which will contain the actual runway used by the departing / arriving aircraft if available. Those values will typically be delivered in a separate 'flifo' message at the arrival / departure time.

FlightAware can make available anonymized position reports for aircraft that are blocked from public tracking. Identifying information like the callsign, registration and Mode S Hexid will appear as the value "BLOCKED". This is intended to provide users with traffic awareness for blocked targets and is not useful for tracking purposes.

If an authorized user needs to track blocked tails through Firehose, then a FlightAware Global account can be combined with Firehose to provide a feed with selective unblocking.

This Subscription Layer enhances terrestrial ADS-B position messages to include FMS weather report values. This data is only available where ANSPs are interrogating the aircraft for weather data. Current coverage can be observed on the FlightAware ADS-B Coverage Map by using the Weather filter option.

The additional fields include: heading_magnetic, heading_true, mach, pressure, speed_ias, speed_tas, temperature, temperature_quality, wind_dir, wind_speed, and wind_quality.

This Subscription Layer enhances terrestrial and space-based ADS-B position messages to include GPS accuracy and precision information. These are also known as NIC, NAC, NUC and SIL.

The additional fields include: nac_p, nac_v, nic, nic_baro, pos_rc, sil, and sil_type.

This Subscription Layer enhances terrestrial ADS-B position messages to include emitted autopilot or navigation system settings.

The additional fields include: nav_altitude, nav_heading, nav_modes and nav_qnh.

The latency of the connection can be monitored by comparing the difference between "pitr" value and your system's current UTC time. When your application is caught up and following live data, the difference should generally be less than 15 seconds. If you observe that the difference continues to increase rather than decrease and remain less than 15, then that is an indication that your application is not able to process the datafeed quickly enough and you need to investigate ways of improving its performance.

When your application is requesting "live" in the initiation command (or resuming from a point in time with the intent of catching up to live), you might notice that data appears to be gradually getting further and further behind realtime. If this occurring, then that is possibly an indication that your application or your network bandwidth is too slow to keep up with the rate of data we are sending to you. We recommend that your application's monitoring include printing the difference between your server's system clock and the "pitr" value that is in every message. Normally, that difference should approach zero as your application catches up to realtime, and then remain between 0 and 30. If you see that difference gradually increase and continue to increase, then you will need to take some corrective actions. If your application's performance is underperforming, consider using multithreading to receive Firehose network data in one thread and processing the data in another. If your application stores Firehose events in a database, consider doing bulk inserts and committing transactions in batches. If your network connection is limited, consider specifying more filtering criteria in the initiation command, or using the data compression mode of Firehose.

Prior to Firehose version 24.0: When requesting surface movement (ground_position or vehicle_position) messages, you will be prevented from also requesting any non-surface messages in the same initiation command. If you are developing an application that requires the ability to receive both types of messages simultaneously and are using release 23 or prior, you will need to open two separate Firehose connections and then fuse the data within your application.

New with Firehose Version 24.0: You can now obtain both surface and and non-surface data with a single connection when requesting flight data dated 11/11/2021 and beyond. Note that the version can be specified in the initiation command (verify if you have that set), or alternately not specifying a version will result in using the latest version.