Details of the Historical API

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. 

cURL calling AirSafe Historical API: 
(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'
In the example above, the cURL query requests data for a one day period by submitting a PUT request. The response from the PUT request (1) returns a job_id. Use the job_id as a query parameter in (2), in our example it is HZwSA__CSV_0. Trigger a GET request and when the job has completed a set of URLs with download URLs is returned from which the data can be retrieved. If data is returned as a CSV output file, you are now all set!

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
  • “2019-09-01T00:00:00-08:00”

  • Interval can be specified using two date-times, e.g. “2019-09-09T00:00:00Z/2019-09-09T00:00:00Z”.

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
  • Two numbers, separated by a comma
  • The first value must be smaller than the second, specifies south-to north-range.
  • The first value is inclusive, the last value is exclusive
longitude_between no 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.
  • The first value is inclusive, last is exclusive
altitude_baro_between no integer
  • Barometric altitude in ft, two integers separated by a comma.
  • The first value is inclusive, the last value is exclusive
out_format no string

Specifies the format of the downloadable files. Must be one of these options:

  • "CSV" (encoded as UTF-8, and separated by a comma)
  • "JSON"(encoded as UTF-8 and new line delimited)
  • "AVRO"

*Default is CSV

*JSON means newline delimited JSON

compression no string

For CSV or JSON: 

  • GZIP

For AVRO:

  • Deflate 
  • SNAPPY

*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-​01​T00:00:00Z/P1D” and “2019-01-​02​T00: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"

 

JSON return data structure of a single 'target_update' from Aviation Historical API call: 
 
{
"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"
}
}