This article will help users in understanding Spire's Airsafe Historical API.
AirSafe Historical API
The Historical API offers the ability to search back in time to the start of the database to research trends, track specific aircraft, etc. You will be able to search for position information, altitude, heading, as well as information like scheduled arrival times, scheduled departure times, and ETA.
Calling the Historical API using cURL:
*Please note, you will need an active Spire token to initiate the cURL command below.
(1) curl -X PUT 'https://api.airsafe.spire.com/archive/job?time_interval=2020-03-12T00:00:00Z/2020-03-12T00:10:00Z' -H 'Authorization: spire-api-key=xxxxxxxxxxxxxxxxxxxxxxx' -H 'Content-Length: 0'
(2) curl 'https://api.airsafe.spire.com/archive/job?job_id=HzwSA_CSV_o' -H 'Authorization: spire-api-key=xxxxxxxxxxxxxxxxxxxxx'
Query Parameters:
The following query parameters can be used to limit the scope of your Historical Call to retrieve the data according to your business needs.
They are:
Query Parameter | Required? | Type | Description |
time_interval | yes | timestamp |
|
icao_address | no | string | comma-separated list (limit results to ANY of the provided values) |
callsign | no | string |
comma-separated list (limit results to ANY of the provided values) |
latitude_between | no | float |
|
longitude_between | no | float |
|
altitude_baro_between | no | integer |
|
out_format | no | string |
Specifies the format of the downloadable files. Must be one of these options:
*Default is CSV *JSON means newline delimited JSON |
compression | no | string |
For CSV or JSON:
For AVRO:
*If the string is empty, it defaults to no compression. An error will be raised if the compression algorithm is not compatible with the selected format. |
ingestion_time_interval | no | timestamp |
Ingestion time records the timestamp when a record was made live into the database. ● Format: ISO 8601 Time Interval. Note the right-hand limit is excluded, so requesting two consecutive intervals does not lead to data duplication. For example, intervals “2019-01-01T00:00:00Z/P1D” and “2019-01-02T00:00:00Z/P1D” return non-intersecting data. ● Any timezone is accepted, as long as the date-time is in ISO 8601 formal, for example: “2019-01-01T00:00:00-08:00”. ● Interval can be specified using two date-times, e.g. “2019-01-01T00:00:00Z/2019-01-02T00:00:00Z”. ● The period can be specified as the first part. The date-time then would mark the end of the requested period. E.g. “P1D/2019-01-02T00:00:00Z”. At least one of the parts must be a date-time. |
Example of using query parameters:
(1) curl -X PUT 'https://api.airsafe.spire.com/archive/job?time_interval=2020-03-12T00:00:00Z/2020-03-12T00:10:00Z&out_format=JSON' -H 'Authorization: spire-api-key=xxxxxxxxxxxxxxxxxxxxxxx' -H 'Content-Length: 0'
In the above query parameter, we are using the (1) time interval parameter to set the extraction data to be between 2020-03-12T00:00:00Z & 2020-03-12T00:10:00Z and (2) setting the output format of this class to be returned as a JSON object.
Field Descriptions of data returned:
Field | Type | Description | Example |
callsign | string | call sign | "RAM200" |
icao_address | string | Hexadecimal representation of ICAO 24 - bit address | "02902A" |
latitude | float | Latitude in degrees, between -90 and 90 (both inclusive) | -27.08932 |
longitude | float | Longitude in degrees, between -180 (exclusive) and 180 (inclusive) | 27.2009820 |
altitude_baro | integer | Barometric altitude in feet | 37000 |
heading | float | Aircraft heading in degrees (0 is north) | 273.2000 |
speed | float | Aircraft speed in knots | 455.6 |
vertical_rate | integer | Vertical rate of ascent/descent | 235 |
Squawk_code | string | Mode-A squawk code | 6617 |
timestamp | timestamp | Timestamp when the message was received by the ADS-B receiver |
“2019 06-06T07:55:25Z” |
source | string | NULL for terrestrial, FM value for satellite | "FM83" |
Ingestion_time | timestamp | Timestamp when the record was stored to the database |
“2019-06-06T07:55:25Z” |
collection_type | string | Collection type | "satellite" or "terrestrial" |
icao_actype | string | Aircraft type (ICAO code) | "B387" |
tail_number | string | Aircraft registration | "A6-EEq" |
Flight_number | string | Flight number (IATA format) | "WN7892" |
origin_airport_icao | string | Origin airport ICAO code | "EHAM" |
destination_airport_icao | string | Destination airport ICAO code | "KDTW" |
scheduled_departure_time_utc |
timestamp |
scheduled departure time, format is in ISO 8601 |
"2019-06-06T07:55:25Z" |
scheduled_departure_time_loc al |
timestamp |
scheduled departure time, format is in ISO 8601 |
"2019-06-06T07:55:25Z" |
scheduled_arrival_time_utc |
timestamp |
scheduled arrival time, format is in ISO 8601 |
"2019-06-06T07:55:25Z" |
scheduled_arrival_time_local |
timestamp |
scheduled arrival time, format is in ISO 8601 |
"2019-06-06T07:55:25Z" |
estimated_arrival_time_utc |
timestamp |
scheduled arrival time, format is in ISO 8601 |
"2019-06-06T07:55:25Z" |
estimated_arrival_time_local |
timestamp |
scheduled arrival time, format is in ISO 8601 |
"2019-06-06T07:55:25Z" |
{
"target": {
"icao_address": "8007C9",
"timestamp": "2019-12-03T06:17:58Z",
"altitude_baro": 7000,
"heading": 180,
"speed": 250,
"latitude": 22.701096,
"longitude": 88.583213,
"callsign": "IGO596",
"vertical_rate": 0,
"collection_type": "terrestrial",
"ingestion_time": "2019-12-03T06:18:02Z",
"tail_number": "VT-IFM",
"icao_actype": "A320",
"flight_number": "6E596",
"origin_airport_icao": "VEGT",
"destination_airport_icao": "VECC",
"scheduled_departure_time_utc": "2019-12-03T02:20:00Z",
"scheduled_departure_time_local": "2019-12-03T07:50:00",
"scheduled_arrival_time_utc": "2019-12-03T03:50:00Z",
"scheduled_arrival_time_local": "2019-12-03T09:20:00",
"estimated_arrival_time_utc": "2019-12-03T06:31:00Z",
"estimated_arrival_time_local": "2019-12-03T12:01:00"
}
}