Firehose (Live Flight Data API) Documentation ✈ FlightAware

Related Commercial Information: Live ADS-B Flight Data Feed (Worldwide)

FlightAware Firehose API Documentation

Purpose

Firehose is a FlightAware API for receiving streaming flight positions (e.g., RADAR, ADS-B, Mode S multilateration (MLAT), datalink, etc) as well as flight status data (e.g., flight plans, departure/arrival messages, flight updates) and surface movement positions. This page defines a protocol for establishing a connection and receiving data from the Firehose interface.

If you have a question that is not answered by this document, please check our frequently asked questions to see if your topic has already been answered there before contacting your account representative for support.

Connection Protocol

All requests must include a username and FlightXML API Key (don't have one?). In addition to obtaining an API Key, the user's account must be specially enabled by a FlightAware representative for access to the firehose service.

If you have a firewall that needs authorization, then please authorize both of the CIDR network block ranges:

70.42.6.128/25
206.123.125.0/25

A customer's application will connect via a TCP socket secured with Secure Socket Layer/Transport Layer Security (SSL/TLS) protocol to FlightAware. The port for downlink connections will be 1501. The hostname will be firehose.flightaware.com, unless FlightAware has instructed the customer otherwise.

On the downlink connection customer's application will send an initiation command followed by a newline character, to specify the credentials, time range, and any filtering of messages to be provided, and both sides will keep the connection open indefinitely for FlightAware to send messages to the customer as they become available. If an error in the syntax or credentials of the initiation command occurs, the firehose server will transmit an error message and disconnect.

The customer's application should be designed to detect socket disconnection and attempt to reconnect to the FlightAware server when necessary. It is also recommended to have an idle connection handler that will disconnect and reconnect if no messages have been received in the last 5 minutes. When reconnecting to the FlightAware server, the "pitr" or "range" initiation command can be used to resume playback from the pitr timestamp of the last received message, if desired.

Testing Connectivity

An important initial diagnostic technique is to confirm your outbound network connectivity over the necessary port number. For testing and development purposes, the OpenSSL command-line tools can be used to check the ability to open a SSL/TLS connection to FlightAware:

openssl s_client -host firehose.flightaware.com -port 1501 -tls1

If the connection is successfully established, OpenSSL will display the server's certificate information and then pause. Should it fail to connect, contact your network administrator to ensure that your application server has access to make outbound TCP connections on port 1501 to the FlightAware datacenter.

Initiation Command Syntax

Initiation Command Options

Required
- username <argument> - Supply the credentials for authentication. This should be the username of the FlightAware account that has been granted access.
- password <argument> - Supply the credentials for authentication. In most cases, this should actually be the FlightXML API Key and not the password of the account.
- the following time range options are mutually exclusive; only one may be used in an initiation command.
  - live - Request live data from the present time forward.
  - pitr <epoch> - Request data from a specified time, in POSIX epoch format, in the past until the current time, and continue with the live behavior.
  - range <start epoch> <end epoch> - Send data between two specified times, in POSIX epoch format. FlightAware will disconnect the connection when last message has been sent.
Optional
- filter "<airline code list>" - Send flight information only related to the listed airlines. The list is a series of space separated ICAO airline codes wrapped in double quotes. For example: filter "FIN" or filter "FIN BAW AAL".
- idents "<ident reg list>" - Send flight information only related to the listed idents or aircraft registration/tails. The list is a series of space separated idents or registrations wrapped in double quotes, optionally using wildcard patterns. For example: idents "N1234 N2345 N456 CXYZA" or idents "N1*UA N2*UA UAL12 UAL34".
- version <version number> - Protocol version the client expects. The latest version is assumed if this is not specified.
- format <format type> - Specifies the output mode of the responses. At this time, "json" is the only supported format, however other formats including "csv", "tsv", "xml" may be offered in the future. If format is not specified, then "json" is assumed.
- events "<event code list>" - Specifies a list of which downlink messages should be sent. The available event codes include: flightplan, departure, arrival, cancellation, position, offblock, onblock, extendedFlightInfo, ground_position, vehicle_position, fmswx. This argument may be a list of space separated terms wrapped in double quotes. When requesting surface movement (ground_position or vehicle_position) messages, you will be prevented from simultaneously requesting any non-surface messages in the same initiation command. Similarly, the weather messages (fmswx) may not be requested simultaneously with any non-weather messages in the same initiation command. For example: events "flightplan departure arrival position" or events "ground_position vehicle_position".
- latlong "<lowLat> <lowLon> <hiLat> <hiLon>" - Specifies that only positions within the specified rectangle should be sent and any others will be ignored, unless the flight has already been matched by other criteria. Once a flight has been matched by a latlong rectangle, it becomes remembered and all subsequent messages until landing for that flight id will continue to be sent even if the flight no longer matches a specified rectangle. For example: latlong "29 -95 30 -94". This command may be repeated multiple times in a single initiation command, allowing positions within any of the specified rectangles to be matched.
- airport_filter "<airport pattern list>" - Send flight information only for flights originating from or destined for airports matching the space separated list of glob patterns provided. For example: airport_filter "CYUL" or airport_filter "K??? P??? TJSJ".
- compression <mode> - Requests that the server response should use data compression to reduce network bandwidth. The initiation command sent to the server must not be compressed. The mode argument indicates the compression algorithm and must be "gzip", "compress", or "deflate". For example: compression gzip.
- keepalive <interval> - Requests that the server should periodically send a "keepalive" message at the specified interval, measured in whole integer seconds (must be 15 seconds or greater). The keepalive messages contain the current timestamp on the server and the pitr timestamp within the data stream. This can be especially useful for feeds that are very low data volume due to heavy filtering, where it may be difficult to distinguish between a failed network connection and a period of time with few aircraft events. For example: keepalive 60.
- strict_unblocking <boolean> - When the argument is 1, then the server will ONLY send messages for aircraft that have been authorized to your FlightAware Global account, avoiding the need to explicitly name them using the "idents" command. Messages for aircraft that have not been added to your Global account, even if they are public and not blocked, will not be sent. When the argument is 0, then all aircraft are visible to your account, including public and non-blocked aircraft, will be sent. Default value is 0. For example: strict_unblocking 1.
- ratelimit_secs_between <interval> - Requests that the server should rate limit the connection by discarding position messages if the last position from the same aircraft was less than the specified interval (specified in whole seconds). Data availability and/or your account's service contract may limit the lowest effective interval that may be specified. Default value is determined by your service contract. For example: ratelimit_secs_between 30.
- optype_filter <mode> - Send only messages relating to flight idents based on the operator type. Supported modes are "ga", "airline", or "cargo". For example: optype_filter airline.
Example downlink initiation commands:
- live filter "BAW" version 6.0 username james password 1234abcd
- range 1377204966 1377214966 filter "AAL BAW FIN" username joe password 34567abdef
- pitr 13772104996 username andrew password bcdef1235
- live version 5.0 user mary password 123abc events "position"
- live version 6.0 username daniel password abcd1234 events "position" latlong "29 -95 30 -94"
- live version 8.0 username alonzo password abcd1234 events "ground_position vehicle_position" airport_filter "KBOS"

Keeping a Persistent Connection

Network connectivity for long-lived network connections over the internet are not always reliable and will tend to stall or hang occasionally, beyond our control. Additionally, we can occasionally have internal network connections that might disrupt communications between our Firehose server and the internal messaging bus that might also cause this type of condition. Very long-lived Firehose connections do eventually need to be disconnected by our server-side (system updates, feed maintenance, resource leaks), but that condition should result in a "connection closed by peer" rather than a "series of end of lines". Be sure that your application has logic to handle the condition of the connection being actively closed by the server.
Keeping a persistent connection open is the expected use-case. We also recommend disconnecting and reconnecting if you receive no data after an extended period of time. When reconnecting, using the "pitr" command to resume data from the timestamp that you last received is recommended.
The maximum number of allowable connections for Firehose is three per user account. One connection is suggested for your production environment and one connection for your development environment. Additional connection licenses are available.

Notes

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. 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 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 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, you will currently need to open two separate Firehose connections and fuse the data within your application.
For technical/commercial support for Firehose, please contact a FlightAware Representative (email).

Access Levels

Your access level will consist of any combination of the following data layers:

ADS-B: Worldwide

[Position message]

MLAT: Worldwide

[Position message]

RADAR: USA, Canada, New Zealand, *Australia, Belize, Costa Rica, El Salvador, Guatemala, Honduras, Nicaragua

[Position message]

Transoceanic/ACARS/Estimated: Worldwide

[Position message]

FLIFO (Flight Status): Worldwide

[Flightplan, Departure, Arrival, and Cancellation messages]

Predicted ETAs: Worldwide

[Flightplan messages with computed_eta fields]

Block Events: Worldwide

[Offblock and Onblock messages]

Extended Flight Info: Worldwide

[extendedFlightInfo message]

Surface Movement: Most major USA airports (ASDE-X and ADS-B), Worldwide (ADS-B only)

[Ground_position and Vehicle_position messages]

Weather and Extended FMS information: Worldwide (Mode-S and ADS-B only)

[fmswx messages]

Please ask a FlightAware representative if you would like access to additional data layers. Firehose is billed at a monthly rate for unlimited use, dependent on what data layers you choose to access and the scope of how you repurpose/redistribute the data within your application. Discounts are available for long-term commitment, up-front payment, and/or public attribution to FlightAware.

Firehose can also be used in conjunction with FlightAware Global for added satellite uplinks and EUROCONTROL data. Other aircraft operator's data can be integrated as well: read about Improving Tracking of Your Flights on FlightAware.

*Australia RADAR and ADS-B is only available for internal consumption (e.g., not for redistribution to third parties beyond yourself).

Data Coverage

For more information on FlightAware's position data coverage, please see FlightAware's coverage map.

Downlink Messages

Messages have two categories of data fields, "Mandatory" and "Optional":

Mandatory fields must be included in every message.
Optional fields are not provided by some sources, but provide important additional information to improve the quality of flight tracking.

Flightplan - a new or modified flightplan (Schema)
Summary	Field name	Description
Mandatory
Filed Departure Time	`fdt`	Timestamp that was originally listed in the filed flight plan for the departure. POSIX epoch format
FlightAware flight id	`id`	Unique identifier associated with each flight (faFlightID)
Flight Identifier	`ident`	Callsign identifying the flight. Typically, ICAO airline code plus IATA/ticketing flight number, or the aircraft registration.
Point In Time Recovery	`pitr`	Timestamp value that should be supplied to the "pitr" connection initiation command when reconnecting and you wish to resume firehose playback at that approximate position
Flight Status	`status`	Single letter code for current flight status, can be S Scheduled, F Filed, A Active, Z Completed, or X Cancelled.
Message type	`type`	Value is always flightplan
Optional
4D waypoints	`4d_waypoints`	4D waypoints of latitude, longitude, altitude, and time, where available, rounded to 4 decimal points
Aircraft Type	`aircrafttype`	FAA or ICAO aircraft type code
Cruising altitude	`alt`	In feet (MSL). For flightplan messages occurring before the actual departure, this field will typically represent the filed initial cruising altitude in the flight plan. After departure, subsequent flightplan messages may contain an updated value in this field that reflects ATC approval of additional altitude clearances.
ATC Ident	`atcident`	Identifier used for ATC, if it differs from flight identifier
Predicted ETA	`computed_eta`	Timestamp of when the flight is predicted to arrive (If enabled for the account). POSIX epoch format.
Predicted ETA Computational Method	`computed_eta_source`	Prediction method used for Predicted ETA. Emitted if feature enabled for the account.
Destination	`dest`	ICAO airport code, waypoint, or latitude/longitude pair. May be missing if not known.
Estimated Departure Time	`edt`	Revised timestamp of when the flight is expected to depart. POSIX epoch format
Estimated Arrival Time	`eta`	POSIX epoch format
En route Time	`ete`	In seconds. May be missing if not known.
Reporting facility hash	`facility_hash`	A consistent and unique obfusticated identifier string for each source reporting positions to FlightAware
Reporting facility name	`facility_name`	A description of the reporting facility intended for end-user consumption. May be a blank string if undefined.
Groundspeed	`gs`	In knots
Transponder Mode S code	`hexid`	24-bit Mode S transponder code assigned by aircraft registrar. Formatted in upper case hexadecimal
Latitude	`lat`	In decimal degrees
Longitude	`lon`	In decimal degrees
Origin	`orig`	ICAO airport code, waypoint, or latitude/longitude pair
Aircraft Prefix	`prefix`	Used to denote Heavy aircraft
Aircraft Registration	`reg`	The tail number or registration of the aircraft, if known and it differs from the ident.
Text route	`route`	Textual route string
Filed cruising speed	`speed`	In knots
Aircraft Suffix	`suffix`	FAA or ICAO aircraft equipment code suffix
True Cancellation	`trueCancel`	Set to 1 when a confirmed flight cancellation was received from the airline. A value of 0 or lack of this field means that this is a presumed cancellation due to expiration or lack of data. (version 10.0+)
Waypoints	`waypoints`	2D, 3D, or 4D list of locations, times, and altitudes formatted as a list of JSON arrays

Waypoint Formatting - for waypoints and 4d_waypoints fields (Schema)
Summary	Field name	Description
Mandatory
Latitude	`lat`	In decimal degrees
Longitude	`lon`	In decimal degrees
Optional
Altitude	`alt`	In feet (MSL)
Time	`clock`	In POSIX epoch format
Groundspeed	`gs`	In knots
Name	`name`	Airport, navaid, waypoint, intersection, or other identifier

Departure - indicates a flight has departed off the runway (Schema)
Summary	Field name	Description
Mandatory
Departure Time	`adt`	POSIX epoch format
FlightAware flight id	`id`	Unique identifier associated with each flight (faFlightID)
Flight Identifier	`ident`	ICAO airline code plus IATA/ticketing flight number
Origin	`orig`	ICAO airport code, waypoint, or latitude/longitude pair
Point In Time Recovery	`pitr`	Timestamp value that should be supplied to the "pitr" connection initiation command when reconnecting and you wish to resume firehose playback at that approximate position
Message type	`type`	Value is always departure
Optional
Arrival Time	`aat`	POSIX epoch format
Aircraft Type	`aircrafttype`	ICAO aircraft type code
ATC Ident	`atcident`	Identifier used for ATC, if it differs from flight identifier
Destination	`dest`	ICAO airport code, waypoint, or latitude/longitude pair
Estimated Departure Time	`edt`	Revised timestamp of when the flight is expected to depart. POSIX epoch format
ETA	`eta`	Estimated Time of Arrival. POSIX epoch format
En route Time	`ete`	In seconds. May be missing if not known.
Reporting facility hash	`facility_hash`	A consistent and unique obfusticated identifier string for each source reporting positions to FlightAware
Reporting facility name	`facility_name`	A description of the reporting facility intended for end-user consumption. May be a blank string if undefined.
Aircraft Registration	`reg`	The tail number or registration of the aircraft, if known and it differs from the ident.
Synthetic flag	`synthetic`	Boolean used to indicate if the departure was triggered by some event other than an explicit departure message. 1 indicates true, 0 indicates false.
Departure Time Type	`timeType`	Possible values are "actual", "estimated", or "enroute"

Arrival - indicates a flight has arrived on the runway (Schema)
Summary	Field name	Description
Mandatory
Arrival Time	`aat`	POSIX epoch format
FlightAware flight id	`id`	Unique identifier associated with each flight (faFlightID)
Flight Identifier	`ident`	Callsign identifying the flight. Typically, ICAO airline code plus IATA/ticketing flight number, or the aircraft registration.
Point In Time Recovery	`pitr`	Timestamp value that should be supplied to the "pitr" connection initiation command when reconnecting and you wish to resume firehose playback at that approximate position
Arrival Time Type	`timeType`	Possible values are "actual", "estimated", or "enroute"
Message type	`type`	Value is always arrival
Optional
ATC Ident	`atcident`	Identifier used for ATC, if it differs from flight identifier
Destination	`dest`	ICAO airport code, waypoint, or latitude/longitude pair
Estimated Departure Time	`edt`	Revised timestamp of when the flight is expected to depart. POSIX epoch format
ETA	`eta`	Estimated Time of Arrival. POSIX epoch format
En route Time	`ete`	In seconds. May be missing if not known.
Reporting facility hash	`facility_hash`	A consistent and unique obfusticated identifier string for each source reporting positions to FlightAware
Reporting facility name	`facility_name`	A description of the reporting facility intended for end-user consumption. May be a blank string if undefined.
Origin	`orig`	ICAO airport code, waypoint, or latitude/longitude pair
Aircraft Registration	`reg`	The tail number or registration of the aircraft, if known and it differs from the ident.
Synthetic flag	`synthetic`	Boolean used to indicate if the arrival was triggered by some event other than an explicit arrival message. 1 indicates true, 0 indicates false.

Cancellation - cancels an existing flightplan (Schema)
Summary	Field name	Description
Mandatory
FlightAware flight id	`id`	Unique identifier associated with each flight (faFlightID)
Flight Identifier	`ident`	Callsign identifying the flight. Typically, ICAO airline code plus IATA/ticketing flight number, or the aircraft registration.
Origin	`orig`	ICAO airport code, waypoint, or latitude/longitude pair
Point In Time Recovery	`pitr`	Timestamp value that should be supplied to the "pitr" connection initiation command when reconnecting and you wish to resume firehose playback at that approximate position
Message type	`type`	Value is always cancellation
Optional
Aircraft Type	`aircrafttype`	FAA or ICAO aircraft type code
Filed cruising altitude	`alt`	In feet (MSL)
ATC Ident	`atcident`	Identifier used for ATC, if it differs from flight identifier
Destination	`dest`	ICAO airport code, waypoint, or latitude/longitude pair
Estimated Departure Time	`edt`	Revised timestamp of when the flight is expected to depart. POSIX epoch format
ETA	`eta`	Estimated Time of Arrival. POSIX epoch format
En route Time	`ete`	In seconds. May be missing if not known.
Reporting facility hash	`facility_hash`	A consistent and unique obfusticated identifier string for each source reporting positions to FlightAware
Reporting facility name	`facility_name`	A description of the reporting facility intended for end-user consumption. May be a blank string if undefined.
Filed Departure Time	`fdt`	Timestamp that was originally listed in the filed flight plan for the departure. POSIX epoch format
Groundspeed	`gs`	In knots
Transponder Mode S code	`hexid`	24-bit Mode S transponder code assigned by aircraft registrar. Formatted in upper case hexadecimal
Aircraft Registration	`reg`	The tail number or registration of the aircraft, if known and it differs from the ident.
Text route	`route`	Textual route string
Filed cruising speed	`speed`	In knots
Flight Status	`status`	Single letter code for current flight status, can be S Scheduled, F Filed, A Active, Z Completed, or X Cancelled.
True Cancellation	`trueCancel`	Set to 1 when a confirmed flight cancellation was received from the airline. A value of 0 or lack of this field means that this is a presumed cancellation due to expiration or lack of data. (version 10.0+)
Waypoints	`waypoints`	2D, 3D, or 4D list of locations, times, and altitudes formatted as a list of JSON arrays

Position - a position report (Schema)
Summary	Field name	Description
Mandatory
Air/Ground	`air_ground`	Air/Ground or Weight-on-Wheel (WOW) switch... "A" air, "G" ground
Report Time	`clock`	POSIX epoch format. Time should be the time generated by flight hardware if possible
Reporting facility hash	`facility_hash`	A consistent and unique obfusticated identifier string for each source reporting positions to FlightAware
Reporting facility name	`facility_name`	A description of the reporting facility intended for end-user consumption. May be a blank string if undefined.
FlightAware flight id	`id`	FlightAware flight id
Flight Identifier	`ident`	Callsign identifying the flight. Typically, ICAO airline code plus IATA/ticketing flight number, or the aircraft registration.
Latitude	`lat`	In decimal degrees, rounded to 4 decimal points
Longitude	`lon`	In decimal degrees, rounded to 4 decimal points
Point In Time Recovery	`pitr`	Timestamp value that should be supplied to the "pitr" connection initiation command when reconnecting and you wish to resume firehose playback at that approximate position
Message type	`type`	Value is always position
Update Type	`updateType`	Specifies source of message, A for ADS-B, Z for radar, O for transoceanic, P for estimated, D for datalink, M for Multilateration (MLAT), X for ASDE-X, S for Space-based ADS-B
Optional
Aircraft Type	`aircrafttype`	ICAO aircraft type code
Altitude	`alt`	In feet (MSL)
Altitude Change	`altChange`	"C" for climbing, "D" for descending, " " when undetermined
ATC Ident	`atcident`	Identifier used for ATC, if it differs from flight identifier
Barometric altitude	`baro_alt`	Barometric altitude in feet
Destination	`dest`	ICAO airport code, waypoint, or latitude/longitude pair. May be missing if not known.
Estimated Departure Time	`edt`	Revised timestamp of when the flight is expected to depart. POSIX epoch format
ETA	`eta`	Estimated Time of Arrival. POSIX epoch format
En route Time	`ete`	In seconds. May be missing if not known.
Fuel on board	`fob`	In kilograms
GPS altitude	`gps_alt`	GPS altitude in feet
Groundspeed	`gs`	In knots
Course	`heading`	In degrees
Transponder Mode S code	`hexid`	24-bit Mode S transponder code assigned by aircraft registrar. Formatted in upper case hexadecimal
Outside air temperature	`oat`	In Celsius
Origin	`orig`	ICAO airport code, waypoint, or latitude/longitude pair
Aircraft Registration	`reg`	The tail number or registration of the aircraft, if known and it differs from the ident.
Text route	`route`	Textual route string
Next expected reported position altitude	`rp1alt`	In feet
Next expected reported position time	`rp1clock`	POSIX epoch format
Next expected reported position latitude	`rp1lat`	In decimal degrees
Next expected reported position longitude	`rp1lon`	In decimal degrees
Filed cruising speed	`speed`	In knots
Transponder squawk code	`squawk`	4 digit octal transponder beacon code assigned by ATC
Waypoints	`waypoints`	2D, 3D, or 4D list of locations, times, and altitudes formatted as a list of JSON arrays
Winds aloft	`winds`	3 digit direction in whole degrees and 3 digit speed in knots concatenated

Offblock - indicates a flight has departed the gate (Schema)
Summary	Field name	Description
Mandatory
Report Time	`clock`	POSIX epoch format. Time should be the time generated by flight hardware if possible
FlightAware flight id	`id`	Unique identifier associated with each flight (faFlightID)
Flight Identifier	`ident`	Callsign identifying the flight. Typically, ICAO airline code plus IATA/ticketing flight number, or the aircraft registration.
Point In Time Recovery	`pitr`	Timestamp value that should be supplied to the "pitr" connection initiation command when reconnecting and you wish to resume firehose playback at that approximate position
Message type	`type`	Value is always offblock
Optional
Destination	`dest`	ICAO airport code, waypoint, or latitude/longitude pair. May be missing if not known.
Reporting facility hash	`facility_hash`	A consistent and unique obfusticated identifier string for each source reporting positions to FlightAware
Reporting facility name	`facility_name`	A description of the reporting facility intended for end-user consumption. May be a blank string if undefined.
Origin	`orig`	ICAO airport code, waypoint, or latitude/longitude pair

Onblock - indicates a flight has arrived at the gate (Schema)
Summary	Field name	Description
Mandatory
Report Time	`clock`	POSIX epoch format. Time should be the time generated by flight hardware if possible
FlightAware flight id	`id`	Unique identifier associated with each flight (faFlightID)
Flight Identifier	`ident`	Callsign identifying the flight. Typically, ICAO airline code plus IATA/ticketing flight number, or the aircraft registration.
Point In Time Recovery	`pitr`	Timestamp value that should be supplied to the "pitr" connection initiation command when reconnecting and you wish to resume firehose playback at that approximate position
Message type	`type`	Value is always onblock
Optional
Destination	`dest`	ICAO airport code, waypoint, or latitude/longitude pair. May be missing if not known.
Reporting facility hash	`facility_hash`	A consistent and unique obfusticated identifier string for each source reporting positions to FlightAware
Reporting facility name	`facility_name`	A description of the reporting facility intended for end-user consumption. May be a blank string if undefined.
Origin	`orig`	ICAO airport code, waypoint, or latitude/longitude pair

ExtendedFlightInfo - block, gate, terminal, and baggage information for a flight (Schema)
Summary	Field name	Description
Mandatory
FlightAware flight id	`id`	Unique identifier associated with each flight (faFlightID)
Flight Identifier	`ident`	Callsign identifying the flight. Typically, ICAO airline code plus IATA/ticketing flight number, or the aircraft registration.
Point In Time Recovery	`pitr`	Timestamp value that should be supplied to the "pitr" connection initiation command when reconnecting and you wish to resume firehose playback at that approximate position
Message type	`type`	Value is always extendedFlightInfo
Optional
Actual Arrival Gate	`actual_arrival_gate`	The gate at which the plane has arrived.
Actual Arrival Terminal	`actual_arrival_terminal`	The terminal at which the plane has arrived.
Actual Departure Gate	`actual_departure_gate`	The gate from which the plane has departed.
Actual Departure Terminal	`actual_departure_terminal`	The terminal at which the plane has departed.
Actual In	`actual_in`	The actual in (gate arrival) time. (POSIX epoch format)
Actual Out	`actual_out`	The actual out (gate departure) time. (POSIX epoch format)
ATC Ident	`atcident`	Identifier used for ATC, if it differs from flight identifier
Baggage Claim	`baggage_claim`	The carousel at which the baggage will or has arrived at the destination airport.
Destination	`dest`	ICAO airport code, waypoint, or latitude/longitude pair. May be missing if not known.
Estimated Arrival Gate	`estimated_arrival_gate`	The gate at which the plane is estimated to arrive.
Estimated Departure Gate	`estimated_departure_gate`	The gate from which the plane is estimated to depart.
Estimated In	`estimated_in`	The estimated in (gate arrival) time. (POSIX epoch format)
Estimated Out	`estimated_out`	The estimated out (gate departure) time. (POSIX epoch format)
Reporting facility hash	`facility_hash`	A consistent and unique obfusticated identifier string for each source reporting positions to FlightAware
Reporting facility name	`facility_name`	A description of the reporting facility intended for end-user consumption. May be a blank string if undefined.
Origin	`orig`	ICAO airport code, waypoint, or latitude/longitude pair. May be missing if not known.
Scheduled Arrival Terminal	`scheduled_arrival_terminal`	The terminal at which the plane is scheduled to arrive.
Scheduled Departure Terminal	`scheduled_departure_terminal`	The terminal at which the plane is scheduled to depart.
Scheduled In	`scheduled_in`	The scheduled in (gate arrival) time. (POSIX epoch format)
Scheduled Out	`scheduled_out`	The scheduled out (gate departure) time. (POSIX epoch format)

fmswx - Weather and Extended FMS information (Schema)
Summary	Field name	Description
Mandatory
Report Time	`clock`	POSIX epoch format. Time should be the time generated by flight hardware if possible
Transponder Mode S code	`hexid`	24-bit Mode S transponder code assigned by aircraft registrar. Formatted in upper case hexadecimal.
Latitude	`lat`	Latitude position value (decimal degrees) of the aircraft when the report was given
Longitude	`lon`	Longitude position value (decimal degrees) of the aircraft when the report was given
Point In Time Recovery	`pitr`	Timestamp value that should be supplied to the "pitr" connection initiation command when reconnecting and you wish to resume firehose playback at that approximate position
Message type	`type`	Value is always fmswx
Optional
Altitude	`alt`	Uncorrected pressure altitude reported by the aircraft in feet.
GNSS Altitude	`alt_gnss`	Reported GNSS altitude (feet above WGS84 ellipsoid)
Reporting facility hash	`facility_hash`	A consistent and unique obfusticated identifier string for each source reporting positions to FlightAware
Reporting facility name	`facility_name`	A description of the reporting facility intended for end-user consumption. May be a blank string if undefined.
Groundspeed	`gs`	The groundspeed of the aircraft, reported in knots.
Heading	`heading`	The direction of the aircraft's ground track, in degrees, relative to true north.
Magnetic Heading	`heading_magnetic`	The aircraft's heading, in degrees, relative to magnetic north.
True Heading	`heading_true`	The aircraft's heading, in degrees, relative to true north.
Mach Number	`mach`	The mach number of the aircraft.
Derived from Multilateration	`mlat`	If this value is present and non-zero, the position was derived from multilateration, not ADS-B, therefore the lat/lon may be less accurate.
Computed Static Air Pressure	`pressure`	The computed static air pressure, given in hPa.
Roll Angle	`roll`	The roll angle of the aircraft, in degrees. A positive value indicates the right wing is down.
Airspeed	`speed_tas`	The true airspeed of the aircraft, reported in knots.
Computed Outside Air Temperature	`temperature`	The computed outside air temperature, given in degrees Celsius.
Temperature Quality	`temperature_quality`	The value is 0 if the derived temperature is likely to be inaccurate due to quantization errors, 0 otherwise.
Track Rate	`track_rate`	The rate of change of the ground track, given in degrees per second.
Vertical Rate	`vertRate`	The aircraft's vertical rate of climb/descent derived from pressure altitude, reported in feet per minute.
Geometric Vertical Rate	`vertRate_geom`	The aircraft's vertical rate of climb/descent derived from GNSS altitude, reported in feet per minute.
Computed Wind Direction	`wind_dir`	The computed wind direction, in degrees, relative to true north. The value uses the normal convention where the direction is opposite the wind vector (i.e. wind_dir = 0 means wind from the north).
Wind Quality	`wind_quality`	The value is 1 if the aircraft is stable (not maneuvering) and 0 if the aircraft is maneuvering. Derived wind data is less reliable if the aircraft is maneuvering.
Computed Wind Speed	`wind_speed`	The computed wind speed, given in knots.

Ground_position - a surface movement position report (Schema)
Summary	Field name	Description
Mandatory
Airport	`airport`	The ICAO code of the airport the position is associated with.
Report Time	`clock`	POSIX epoch format. Time should be the time generated by flight hardware if possible
Flight Identifier	`ident`	Callsign identifying the flight. Typically, ICAO airline code plus IATA/ticketing flight number, or the aircraft registration. May sometimes be "Unknown-XXXXX" if not known.
Latitude	`lat`	In decimal degrees, rounded to 4 decimal points
Longitude	`lon`	In decimal degrees, rounded to 4 decimal points
Point In Time Recovery	`pitr`	Timestamp value that should be supplied to the "pitr" connection initiation command when reconnecting and you wish to resume firehose playback at that approximate position
Message type	`type`	Value is always ground_position
Optional
Air/Ground	`air_ground`	Air/Ground or Weight-on-Wheel (WOW) switch... "A" air, "G" ground. (Will typically be "G" for ground_positions, but switch confusion may sometimes indicate otherwise.)
Aircraft Equipment Type	`aircrafttype`	ICAO aircraft type code, as determined from registration information looked up using the transponder's hexid.
Airport Location	`airport_location`	Aircraft position if within a defined location boundary (such as "Atlantic Aviation", "Signature Flight Support (West)", "Customs Ramp")
Airport Location Id	`airport_location_id`	A consistent and unique obfuscated identifier string for each location
Altitude	`alt`	In feet (MSL). Will generally be very close to airport surface elevation.
Altitude Source	`altSource`	is "FL" if the altitude source variable was derived from flightLevel reported by ASDE-X.
Arrival	`arrival`	Set as 1 only when an ASDE-X ground status of "arrival" is received in the upstream message
Barometric Pressure Altitude	`baroAlt`	Most recent barometric pressure altitude reported by the aircraft (uncorrected). 204775 means >= 204775
Reporting facility hash	`facility_hash`	A consistent and unique obfuscated identifier string for each source reporting positions to FlightAware
Reporting facility name	`facility_name`	A description of the reporting facility intended for end-user consumption. May be a blank string if undefined.
Fix	`fix`	For departing flights will generally be first three characters of the departure fix, or the ICAO four-letter airport name for arrival flights
Groundspeed	`gs`	In knots
Course	`heading`	In degrees
Transponder Mode S code	`hexid`	24-bit Mode S transponder code assigned by aircraft registrar. Formatted in upper case hexadecimal
Surface ID	`id`	Each discernible track will have a FlightAware-created unique track ID that will last from the time the target is first seen until a period of time has elapsed without receiving any new positions for or from the target, currently ten minutes.
Geospatial Layer	`layer`	If not present or empty, aircraft is within the airport boundary. If set to near, aircraft is within 5 miles of the airport center point, at a groundspeed over 100knots and at an altitude less than or equal to 5000 feet above the airport's published elevation
Aircraft Equipment Type	`manual_aircrafttype`	ICAO aircraft type code, as manually entered by ATC. Sometimes "VEH" for vehicles.
On Runway	`on_runway`	If aircraft is on a runway, populated with the runway identifier
On Ground	`onground`	Set as 1 only when an ASDE-X ground status of "onground" is received in the upstream message
Aircraft Registration	`reg`	The tail number or registration of the aircraft, if known and it differs from the ident.
scratchpad	`scratchpad1`	controller-entered scratchpad entries
scratchpad	`scratchpad2`	controller-entered scratchpad entries
Transponder squawk code	`squawk`	4 digit octal transponder beacon code assigned by ATC
Track Identifier	`track`	For ASDE-X, a track ID that should be temporally unique to this track but can roll over or restart.
Update Type	`updateType`	Specifies source of message, A for ADS-B, X for ASDE-X
Vertical Rate	`vertRate`	In feet per minute. number is positive if ascending; negative if descending

Vehicle_position - a surface movement position report from a ground vehicle (non-aircraft) (Schema)
Summary	Field name	Description
Mandatory
Airport	`airport`	The ICAO code of the airport the position is associated with.
Report Time	`clock`	POSIX epoch format. Time should be the time generated by flight hardware if possible
Flight Identifier	`ident`	Callsign identifying the flight. Typically, ICAO airline code plus IATA/ticketing flight number, or the aircraft registration. May sometimes be "Unknown-XXXXX" if not known.
Latitude	`lat`	In decimal degrees, rounded to 4 decimal points
Longitude	`lon`	In decimal degrees, rounded to 4 decimal points
Point In Time Recovery	`pitr`	Timestamp value that should be supplied to the "pitr" connection initiation command when reconnecting and you wish to resume firehose playback at that approximate position
Message type	`type`	Value is always vehicle_position
Optional
Air/Ground	`air_ground`	Air/Ground or Weight-on-Wheel (WOW) switch... "A" air, "G" ground. (Will typically be "G" for ground_positions, but switch confusion may sometimes indicate otherwise.)
Aircraft Equipment Type	`aircrafttype`	ICAO aircraft type code, as determined from registration information looked up using the transponder's hexid.
Airport Location	`airport_location`	Aircraft position if within a defined location boundary (such as "Atlantic Aviation", "Signature Flight Support (West)", "Customs Ramp")
Airport Location Id	`airport_location_id`	A consistent and unique obfuscated identifier string for each location
Altitude	`alt`	In feet (MSL). Will generally be very close to airport surface elevation.
Altitude Source	`altSource`	is "FL" if the altitude source variable was derived from flightLevel reported by ASDE-X.
Arrival	`arrival`	Set as 1 only when an ASDE-X ground status of "arrival" is received in the upstream message
Barometric Pressure Altitude	`baroAlt`	Most recent barometric pressure altitude reported by the aircraft (uncorrected). 204775 means >= 204775
Reporting facility hash	`facility_hash`	A consistent and unique obfuscated identifier string for each source reporting positions to FlightAware
Reporting facility name	`facility_name`	A description of the reporting facility intended for end-user consumption. May be a blank string if undefined.
Fix	`fix`	For departing flights will generally be first three characters of the departure fix, or the ICAO four-letter airport name for arrival flights
Groundspeed	`gs`	In knots
Course	`heading`	In degrees
Transponder Mode S code	`hexid`	24-bit Mode S transponder code assigned by aircraft registrar. Formatted in upper case hexadecimal
Surface ID	`id`	Each discernible track will have a FlightAware-created unique track ID that will last from the time the target is first seen until a period of time has elapsed without receiving any new positions for or from the target, currently ten minutes.
Geospatial Layer	`layer`	If not present or empty, aircraft is within the airport boundary. If set to near, aircraft is within 5 miles of the airport center point, at a groundspeed over 100knots and at an altitude less than or equal to 5000 feet above the airport's published elevation
Aircraft Equipment Type	`manual_aircrafttype`	ICAO aircraft type code, as manually entered by ATC. Sometimes "VEH" for vehicles.
On Runway	`on_runway`	If aircraft is on a runway, populated with the runway identifier
On Ground	`onground`	Set as 1 only when an ASDE-X ground status of "onground" is received in the upstream message
Aircraft Registration	`reg`	The tail number or registration of the aircraft, if known and it differs from the ident.
scratchpad	`scratchpad1`	controller-entered scratchpad entries
scratchpad	`scratchpad2`	controller-entered scratchpad entries
Transponder squawk code	`squawk`	4 digit octal transponder beacon code assigned by ATC
Track Identifier	`track`	For ASDE-X, a track ID that should be temporally unique to this track but can roll over or restart.
Update Type	`updateType`	Specifies source of message, A for ADS-B, X for ASDE-X
Vertical Rate	`vertRate`	In feet per minute. number is positive if ascending; negative if descending

Keepalive - periodic heartbeat message generated at a specific interval (Schema)
Summary	Field name	Description
Mandatory
Point In Time Recovery	`pitr`	Timestamp value that should be supplied to the "pitr" connection initiation command when reconnecting and you wish to resume firehose playback at that approximate position
Server Time	`serverTime`	POSIX epoch format. Current system time on the firehose server when the keepalive message was generated
Message type	`type`	Value is always keepalive
Optional

Revision History and Version

Version 1.0 - Initial release
Version 2.0 - Lat/lon and waypoints are truncated to 5 digits of decimal precision
Version 3.0 - Adds squawk attribute
Version 4.0 - Adds hexid attribute
Version 5.0 (August 2015)
- add airport_filter command to match origin/destination
- add support for multiple latlon boxes
- make successful latlon matches trigger matching for further messages from that same flight_id
- make expression matching use logical-OR when multiple are specified
- add facility_hash/facility_name to JSON messages.
- increase maximum initiation command length to 5120
- add command aliases for "latlon vs latlong" and "filter vs airline_filter"
Version 6.0 (February 2016)
- add "pitr" element to all messages, for use with resuming via the "pitr" (point in time recovery) initiation command
- add "fdt" (filed departure time) element to flightplan messages
Version 7.0 (June 2016)
- add "compression" command to allow streamed responses to use data compression, useful for lower-bandwidth connections.
- add support for "onblock" and "offblock" events, approved users only.
- add support for "positions" from MLAT sources (updateType = "M"), approved users only.
- add support for datalink sources (updateType = "D"), approved users only.
- fields with blank values will now be omitted.
- flight "id" (faFlightID) field now omits the colon and fork identifier suffix.
- add support for receiving data on blocked aircraft, for customers with FlightAware Global accounts.
Version 8.0 (February 13, 2017)
- add surface movement support by adding new "ground_position" and "vehicle_position" message types (updateType = "X" or updateType = "A"), approved users only.
- add support for receiving obfuscated data on blocked aircraft, approved users only.
- add "keepalive" command to allow periodic heartbeat/progress messages to be transmitted, useful when requesting very specific filters that produce low-traffic volume.
- (April 9, 2017) add "strict_unblocking" command to simplify requesting only aircraft belonging to a FlightAware Global account.
- (July 27, 2017) add "ratelimit_secs_between" command to allow rate limiting of positions per aircraft.
- (August 9, 2017) add support for space-based ADS-B airborne "position" message types (updateType = "S"), approved users only.
Version 9.0 (August 9, 2017)
- add support for near-airport ASDE-X radar airborne "position" message types (updateType = "X"), approved users only. These ASDE-X positions will also be remapped to and combined with updateType = "Z" in earlier versions when available.
Version 10.0 (April 5, 2018)
- With deployment of this version, a significant backend rewrite has occurred providing significant replay speed improvements. Although best efforts have been made to ensure close backwards compatiblity when requesting older version numbers, there may be subtle, unavoidable server differences.
- The opaque data format used by the "facility_hash" member has changed starting with version 10.0, making comparison of values retrieved from earlier versions incomparable. Applications that depend on comparing saved data that use the older format of this field are recommended to request version 9.0 or lower when connecting.
- The "cancellation" message has a new optional "trueCancel" field when requesting version 10.0 or higher, indicating that confirmed flight cancellation was received from the airline, rather than a presumed cancellation due to expiration or lack of data.
- When specifying an ending epoch timestamp with the "range" command, you will now receive all messages that match the final timestamp rather than just the first matching message.
- The "filter" command may potentially match flights that have a non-US aircraft registration that happens to match the first 3 characters of the requested airline codes.
- Server improvements to obfuscated access to blocked flights allows users with that privilege to see more blocked flights than before.
Version 11.0 (May 11, 2018)
- Add extendedFlightInfo message type which contains block, gate, terminal, and baggage information for a flight. (approved users only)
- Add Predicted ETA (computed_eta) fields to flightplan message. (approved users only)
Version 12.0 (July 2018)
- Add fmswx message type which contains weather and FMS extended information for a flight. (approved users only)

Firehose Examples

Java

This open source code provides an example with google-gson parsing.
Another example with json-simple parsing.

C#

This open source code provides an example with Json.NET.

Python

This open source code provides an example using Python 3.

Perl

This open source code provides an example of how to get data using Perl 5.

PHP

This open source code provides an example of how to get data using PHP 5.

Tcl

This open source code provides an example of how to get and parse the data using tcl and its JSON library.

FlightAware Firehose API Documentation

Purpose

Connection Protocol

Testing Connectivity

Initiation Command Syntax

Keeping a Persistent Connection

Notes

Access Levels

Data Coverage

Downlink Messages

Revision History and Version

Firehose Examples

Java

C#

Python

Perl

PHP

Tcl

ログイン