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-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"

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"
  }
}