NAV

AirSafe Tracking Stream

Description

Spire’s AirSafe Tracking Stream delivers the Target Updates as soon they are received and processed from both Satellite and Terrestrial sources in a data stream. It was designed to support two use cases:

The ADS-B capable aircraft transponders emit several messages with different bits of information several times per second. Spire’s satellites collect these messages that are processed into a Target Update, which is an update for each ICAO address for each 5 second interval.

Overview

AirSafe V2 Stream

Get Started

Authentication

Before accessing the APIs, Spire must provide users with an API token for the AirSafe Tracking Stream API.

Host https://api.airsafe.spire.com/v2/targets/stream
API Token (Example) AbcDEfghIJklmn0pQrstuvWXYZ012345
Header Value Authorization: Bearer your_token

Connecting

The connection to the streaming endpoint is a long lived HTTP GET request. The server will keep sending messages until the connection terminates. The client can reconnect and resume consuming the messages from the last known position token. The position token is sent in short intervals as part of the Target Updates stream.

Curl Example

The following curl command connects to the streaming endpoint and prints the received data to the console.

curl -H 'Authorization: Bearer {your_token}' https://api.airsafe.spire.com/v2/targets/stream?compression=none

Messages

The messages are separated by a new line and are encoded in the JSON format.

To distinguish which message is sent the client should look for the target, position_token or status keys in the JSON object.

Migration from AirSafe Data Stream Version 1

The migration from AirSafe Tracking Stream v1 is fairly straightforward and mostly concerns field names changes.

Changes in API Endpoint

The API endpoint URL has changed to https://api.airsafe.spire.com/v2/targets/stream

Note: Version 1 endpoint was https://api.airsafe.spire.com/stream

Changes in Query Parameters

The query parameter stream_token is now replaced by position_token.

The position_token query parameter can take the following values:

Changes in Output Fields

The content of the output fields didn't change with an exception of local times (see below). Several fields have changed their name and three fields have been added.

Please also note that by default, the datastream will send back GZIP compressed data. If you wish to receive plain JSON data, you need to disable to compression using the query parameter compression.

Field Names Changes

The most changes concern time related fields. The postfixes _local and _utc are no longer used. The time is presented always in UTC and timezone offset is available for both departure and arrival airport in departure_utc_offset and arrival_utc_offset fields. The local time fields are no longer available but can be clculated from relevant *_time and *_utc_offset fields.

Old field New field
ground_speed speed
icao_actype aircraft_type_icao
scheduled_departure_time_utc departure_scheduled_time
scheduled_departure_time_local (removed, calculate from departure_scheduled_time and departure_utc_offset)
scheduled_arrival_time_utc arrival_scheduled_time
scheduled_arrival_time_local (removed, calculate from arrival_scheduled_time and arrival_utc_offset)
estimated_arrival_time_utc arrival_estimated_time
estimated_arrival_time_local (removed, calculate from arrival_estimated_time and arrival_utc_offset)

New Fields

New fields include UTC offsets and estimation time for departure departure_estimated_time.

New field
departure_estimated_time
departure_utc_offset
arrival_utc_offset

Query Parameters

The following parameters can be specified to filter the stream on the server side or to reduce the bandwidth requirements. Since these are query parameters the total number of filters that can be specified is limited by the maximum URL length. All query parameters are optional, if not specified then all the data is sent to the stream.

Query Parameters Type Description
position_token string BEGINNING to start from oldest still available target update
LATEST (default) to start from last available target update
token to resume the stream from a certain position, the invocation must return a token that was previously sent and is not older than 6 hours
icao_address string Comma separated list of ICAO addresses (6 hex characters)
tail_number string Comma separated list of tail numbers
callsign string Comma separated list of callsigns
airline string Comma separated list of airline IATA codes
latitude_between float,float Two numbers, separated by a comma. First value must be smaller than the second; specifies south-to-north range. First value is inclusive, last value is exclusive
longitude_between float,float Two numbers, separated by a comma. Specifies west-to-east range. E.g. range [170, -170) is a 20° range crossing anti-meridian, and [-170, 170) is a 340° range covering most of the globe. First value is inclusive, last value is exclusive
altitude_between integer,integer Altitude in ft, two integers separated by a comma. First value is inclusive, last value is exclusive
late_filter boolean true or false (default)
This filters out non-chronological data. Filters all target updates for an aircraft (based on icao_address) if it is older than the last recent target update for that aircraft
max_age integer This filters out delayed data. If an aircraft timestamp is older than n milliseconds, the target update will not be returned
compression string Compression of the data.
gzip (default) GZip compression
none to disable compression

Target Update Fields

The fields in this table are taken directly from ADS-B messages:

Field Type Description Example
icao_address string Hexadecimal representation of ICAO 24-bit address "02013F"
latitude float Latitude in degrees, between -90 and 90 (both inclusive) -26.80491819
longitude float Longitude in degrees, between -180 (exclusive) and 180 (inclusive) 28.64151588
altitude_baro integer Barometric altitude in feet 38000
on_ground boolean Specifies if the aircraft is on the ground. true if the aircraft is on the ground, false if the aircraft is airborne false
heading float Aircraft heading in degrees (0 is North) 273
speed float Aircraft speed in knots 477
vertical_rate integer Vertical rate of ascent/descent, in ft/min 100
callsign string Call sign "RAM200"
squawk string Mode-A squawk code 6617

These fields are merged into each record to give additional information:

Field Type Description Example
timestamp datetime Timestamp when the message was received by ADS-B receiver "2019-06-06T07:55:25Z"
source string The identification of the satellite in Satellite ADS-B data “FM83”
ingestion_time datetime Timestamp when record was stored to the database "2019-06-06T07:55:25.602Z"
collection_type string Collection type satellite or terrestrial "satellite"

The following fields are enhanced data and may be present in the record:

Aircraft Information

Field Type Description Example
aircraft_type_icao string Aircraft type (ICAO code) "A320"
tail_number string Aircraft Registration "G-EUUL"
aircraft_type_name string Aircraft type name "Airbus A320-232"
airline_iata string IATA code of the airline "BA"
airline_name string Human readable name of the airline "British Airways"

Flight Information

Field Type Description Example
flight_number string Flight number (IATA format) "WN9002"
departure_airport_icao string Departure airport ICAO code "EHAM"
departure_airport_iata string Departure airport IATA code "AMS"
arrival_airport_icao string Arrival airport ICAO code "EGNX"
arrival_airport_iata string Arrival airport IATA code 'EMA"
departure_scheduled_time datetime Scheduled departure time, format is in ISO 8601 "2019-06-06T07:55:25Z"
departure_estimated_time datetime Departure estimated time, format is in ISO 8601 "2019-06-06T07:55:25Z"
arrival_scheduled_time datetime Scheduled arrival time, format is in ISO 8601 "2019-06-06T07:55:25Z"
arrival_estimated_time datetime Estimated arrival time, format is in ISO 8601 "2019-06-06T07:55:25Z"
takeoff_time datetime Take off time, format is in ISO 8601 "2019-06-06T07:55:25Z"
landing_time datetime Landing time, format is in ISO 8601 "2019-06-06T07:55:25Z"
departure_utc_offset string Departure airport timezone offset from UTC "+0600"
arrival_utc_offset string Arrival airport timezone offset from UTC "-0700"

Examples

Airsafe Tracking Stream examples are located here.

Contact Us

Please contact our customer service aviation@spire.com for any questions.