AirSafe Tracking History
Description
Spire’s AirSafe Tracking History delivers recently acquired (with a 4 hour delay) and up to 3 months old Target Updates from both Satellite and Terrestrial sources via a REST endpoint delivering JSON formatted target updates. It can be used to retrieve historical data in a specific region, for a fleet or a single aircraft during a particular time.
Overview
Get Started
Authentication
Before accessing the APIs, Spire must provide users with an API token for the AirSafe Tracking History API.
Host | https://api.airsafe.spire.com/v2/targets/history |
API Token (Example) | AbcDEfghIJklmn0pQrstuvWXYZ012345 |
Header Value | Authorization: Bearer your_token |
Curl Example
The following curl command connects to the history endpoint and prints the received data to the console.
curl -H 'Authorization: Bearer {your_token}' https://api.airsafe.spire.com/v2/targets/history?icao_address=4072EA&start=2020-10-26T00:00:00Z&end=2020-10-26T23:59:59Z
Output data
Each output data entry is separated by a new line and are encoded in the JSON format. Each entry can contain one of the following:
Target Update The Target Update entry contains all the fields describing a positional update for an aircraft, as well as additional flight and aircraft information. Each target update is delivered in the following format:
{"target": {...}}
. The fields included in the Target Update are described below.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” or “status” keys in the JSON object.
Query Parameters
The following parameters can be specified to retrieve historical data with more accuracy. Since these are query parameters the total number of filters that can be specified is limited by the maximum URL length.
The query parameters start
and end
are mandatory in order to retrieve data.
You then also need add at least one additional filtering parameters such as a list of icao_address
or latitude_between
and longitude_between
to specify your query.
Query Parameters | Type | Description |
---|---|---|
start |
datetime | Required - History data extraction starting date, format is in ISO 8601 |
end |
datetime | Required - History data extraction ending date, format is in ISO 8601 |
icao_address |
string | Comma separated list of ICAO addresses (6 hex characters) |
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 |
Target Update Fields
The fields in this table are taken directly from ADS-B messages:
Note: The content may vary based on your subscription plan.
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" |
departure_utc_offset |
string | Departure airport timezone offset from UTC | "+0600" |
arrival_utc_offset |
string | Arrival airport timezone offset from UTC | "-0700" |
Flight Analytics
Field | Type | Description | Example |
---|---|---|---|
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" |
Example
You can find an example and interactive playground in our Jupyter Notebook here.
Contact Us
Please contact our customer service aviation@spire.com for any questions.