Output

The messages output by the endpoint are separated by a new line and are encoded in the JSON format. Two different types of messages can appear when calling the endpoint (target update and status message), which you can distinguish by their associated JSON keys.

Target Update#

The Target Update message contains all the fields describing a positional update for an aircraft. It is delivered in the following format: {"target": {...}}. The fields included in the Target Update message are described below.

Contents#

ADS-B position information#

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

Spire target update metadata#

These fields are merged into each record to give additional information regarding the ADS-B message details:

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"

Aircraft Information#

The following fields are enhanced data and may be present in the record depending on information availability:

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#

The following fields are enhanced data and may be present in the record depending on information availability:

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#

The following fields are enhanced data and may be present in the record depending on information availability:

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"

Sample#

Here is how a typical Target Updated broadcasted by our API looks like:

{
    "target": {
        "icao_address": "896331",
        "timestamp": "2021-05-19T13:27:24Z",
        "latitude": 25.280045,
        "longitude": 55.464223,
        "altitude_baro": 6750,
        "heading": 120,
        "vertical_rate": -1340,
        "on_ground": false,
        "callsign": "FDB1164",
        "tail_number": "A6-FDZ",
        "collection_type": "terrestrial",
        "flight_number": "FZ1164",
        "ingestion_time": "2021-05-19T13:27:26.368Z",
        "speed": 290,
        "aircraft_type_icao": "B738",
        "aircraft_type_name": "Boeing 737-8KN",
        "airline_iata": "FZ",
        "airline_name": "flydubai",
        "departure_utc_offset": "+0300",
        "departure_airport_icao": "LLBG",
        "departure_airport_iata": "TLV",
        "departure_scheduled_time": "2021-05-19T10:25:00Z",
        "takeoff_time": "2021-05-19T10:55:42Z",
        "arrival_utc_offset": "+0400",
        "arrival_airport_icao": "OMDB",
        "arrival_airport_iata": "DXB",
        "arrival_scheduled_time": "2021-05-19T13:45:00Z"
    }
}

Status message#

The message is used to communicate errors, warnings and info level codes back to the client. The level can be set to:

ERROR (3xx codes)
WARN (2xx codes)
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": {
        "timestamp": "ISO timestamp",
        "level": "severity",
        "message": "message_text",
        "code": "message_code"
    }
}

Sample#

{
    "status": {
        "timestamp": "2021-05-19T13:27:22Z",
        "level": "INFO",
        "message": "Welcome to Spire's /v2/target/history",
        "code": 100
    }
}