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 multiple use cases:
You want to open a persistent connection and receive target updates continuously, as soon as possible as they’re available to Spire
You want to connect periodically, for example once an hour or once every 15 minutes, to retrieve all data produced since the last time you connected using the
position_tokenYou want to retrieve data up to 24h old, by selecting the data in time buckets.
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
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, or a standard REST HTTP GET request when using batch mode.
Streaming mode
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.
Batch mode
In batch mode, the server will only send the target updates between the desired dates and then stop the connection.
Curl Example
The following curl command connects to the streaming endpoint and prints the received data to the console.
Streaming mode
curl -H 'Authorization: Bearer {your_token}' https://api.airsafe.spire.com/v2/targets/stream?compression=none
Batch mode
curl -H 'Authorization: Bearer {your_token}' https://api.airsafe.spire.com/v2/targets/stream?start=2021-04-25T07:00:00Z&end=2021-04-25T07:05:00Z&compression=none"
Messages
The messages are separated by a new line and are encoded in the JSON format.
Target Update The Target Update contains all the fields describing a positional update for an aircraft, the target is delivered in the following format:
{"target": {...}}. The fields included in the Target Update are described below.Position token The position token is only present in streaming mode for reconnection purposes. In case the connection is interrupted the client needs to reconnect, to avoid losing any messages which have been received in the meantime the client can send the stream position token in order to continue to receive the stream from the last known location. The position token is only sent occasionally and is intended to guarantee an “at least once” reception of each Target Update sent by the stream.
The steam position token is delivered in this format:{"position_token": “your_position_token”}Status message The message is used to communicate errors, warnings and info level information back to the client. The level can be set to ERROR (3xx codes), WARN (2xx codes) or INFO (1xx codes). The code can be used by clients to detect certain conditions and act on them. The status is delivered in this format:
{"status": {"level": "severity", "message"; "message_text", "code:": message_code}}
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:
BEGINNINGto start from oldest still available target updateLATEST(default) to start from last available target updatetokento resume the stream from a certain position, the invocation must return a token that was previously sent and is not older than 6 hours
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 updateLATEST (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 compressionnone to disable compression |
In batch mode those additional query parameters are required in order to retrieve data.
| Query Parameters | Type | Description |
|---|---|---|
start |
datetime | Batch mode data extraction starting date, format is in ISO 8601 |
end |
datetime | Batch mode data extraction ending date, format is in ISO 8601 |
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.