Firehose Documentation Center

Initiation Command Syntax

Initiation Command Options

Required Commands

The following time range options are mutually exclusive; only one may be used at the start of 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.

The following authentication items must both be used.

password <argument> - Supply the credentials for authentication. In most cases, this should actually be the Firehose API Key and not the password of the account.

username <argument> - Supply the credentials for authentication. This should be the username of the FlightAware account that has been granted access.

Optional Commands

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.

events "<event code list>" - Specifies a list of which downlink messages should be sent. If not specified default behavior is to deliver all Airborne Feed messages enabled in the Firehose Subscription. Supported event codes are listed as message types on the messages page. Which event codes are available will depend on which Subscription Layers are enabled. This argument may be a list of space separated terms wrapped in double quotes. For connections specifying version 24 or higher (or omitting the version argument) with a stream start date on or after 11-11-2021, airborne and surface events may be requested in the same connection. For connections specifying version 23 or lower, messages from only one feed type can be requested in a single initiation command. For all versions, weather events must be requested in a separate connection.
Unified (ground and airborne) connections requesting near_surface_position events will emit that message type starting with version 28 (earlier firehose versions (24 - 27) emitted that data as a position message type).

For example:
When requesting a connection with version 24 or higher (and a stream start date on or after 11-11-2021), you can request surface and airborne messages (flifo, position, surface_onblock, surface_offblock, ground_position, vehicle_position, etc.) in the same connection. When requesting a connection with version 23 or lower and specifying surface messages (ground_position, vehicle_position, etc.), you will be prevented from simultaneously requesting any non-surface messages in the same initiation command. Similarly, the Weather Feed messages (fmswx) may not be requested simultaneously with any non-weather messages in the same initiation command.

Airborne events:
arrival cancellation departure flightplan extendedFlightInfo flifo surface_offblock surface_onblock power_on position hold_entry hold_exit extended_predictions
*'flifo' may not be specified with 'flightplan' or 'extendedFlightInfo' events. 'flightplan' and 'extendedFlightInfo' are being deprecated in favor of 'flifo'

Surface events:
ground_position vehicle_position near_surface_position location_entry location_exit

Weather events:
fmswx

Examples:

Combined airborne/surface feed (version 24 or higher after 11-11-2021):
events "flifo departure arrival position ground_position"

Airbone only feed:
events "flifo departure arrival position"

Surface only feed:
events "ground_position vehicle_position".

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 UAL?? UAL12 UAL34".

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

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.

polygon "lat,lon lat,lon lat,lon lat,lon" - A space separated list of lat,lon pairs defining a polygon in either clockwise or counter-clockwise direction. Specifies that only positions within the specified polygon 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 polygon, all subsequent messages for that flight id will be emitted even if the flight passes outside the specified polygon. For example: polygon "33.13,-102.34 33.13,-102.64 32.13,-102.64 32.13,-102.34 33.13,-102.34". This command may be repeated multiple times in a single initiation command, allowing positions within any of the specified polygons to be matched. For any polygon crossing the international date line, if that polygon will cross the date line more than once it should be split into separate polygons, each crossing the international date line only once. Polar polygons are also supported, but only a single pole should be covered by the polygon.

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.

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). Does not rate limit non-position messages. 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. In version 24 and higher, this command will set rate limiting for both airborne and surface positions if requested in the connection. For example: ratelimit_secs_between 30.

min_seconds_between_airborne <interval> - Requests that the server should rate limit the connection by discarding airborne position messages if the last position from the same aircraft was less than the specified interval (specified in whole seconds). Does not rate limit non-position messages. Data availability and/or your account's service contract may limit the lowest effective interval that may be specified. This value overrides 'ratelimit_secs_between' for airborne positions in a feed and allows different rate limits to be specified in a combined airborne / surface feed. Default value is determined by your service contract. For example: ratelimit_secs_between 30.

min_seconds_between_surface <interval> - Requests that the server should rate limit the connection by discarding surface position messages if the last position from the same aircraft was less than the specified interval (specified in whole seconds). Does not rate limit non-position messages. Data availability and/or your account's service contract may limit the lowest effective interval that may be specified. This value overrides 'ratelimit_secs_between' for surface positions in a feed and allows different rate limits to be specified in a combined airborne / surface feed. Default value is determined by your service contract. For example: ratelimit_secs_between 30.

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.

version <version number> - Protocol version the client expects. The latest version is assumed if this is not specified. It is strongly recommended the latest version be used whenever possible.

Example downlink initiation commands: