Skip to main content

Output

The messages output by the endpoint are separated by a new line and are encoded in the JSON format. Three types of messages can appear when calling the endpoint (target update, position token 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:

FieldTypeDescriptionExample
icao_addressstringHexadecimal representation of ICAO 24-bit address"02013F"
latitudefloatLatitude in degrees, between -90 and 90 (both inclusive)-26.80491819
longitudefloatLongitude in degrees, between -180 (exclusive) and 180 (inclusive)28.64151588
altitude_barointegerBarometric altitude in feet38000
on_groundbooleanSpecifies if the aircraft is on the ground. true if the aircraft is on the ground, false if the aircraft is airbornefalse
headingfloatAircraft heading in degrees (0 is North)273
speedfloatAircraft speed in knots477
vertical_rateintegerVertical rate of ascent/descent, in ft/min100
callsignstringCall sign"RAM200"
squawkstringMode-A squawk code6617

Spire target update metadata#

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

FieldTypeDescriptionExample
timestampdatetimeTimestamp when the message was received by ADS-B receiver"2019-06-06T07:55:25Z"
sourcestringThe identification of the satellite in Satellite ADS-B data“FM83”
ingestion_timedatetimeTimestamp when record was stored to the database"2019-06-06T07:55:25.602Z"
collection_typestringCollection type satellite or terrestrial"satellite"

Aircraft Information#

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

FieldTypeDescriptionExample
aircraft_type_icaostringAircraft type (ICAO code)"A320"
tail_numberstringAircraft Registration"G-EUUL"
aircraft_type_namestringAircraft type name"Airbus A320-232"
airline_iatastringIATA code of the airline"BA"
airline_namestringHuman 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:

FieldTypeDescriptionExample
flight_numberstringFlight number (IATA format)"WN9002"
departure_airport_icaostringDeparture airport ICAO code"EHAM"
departure_airport_iatastringDeparture airport IATA code"AMS"
arrival_airport_icaostringArrival airport ICAO code"EGNX"
arrival_airport_iatastringArrival airport IATA code'EMA"
departure_scheduled_timedatetimeScheduled departure time, format is in ISO 8601"2019-06-06T07:55:25Z"
departure_estimated_timedatetimeDeparture estimated time, format is in ISO 8601"2019-06-06T07:55:25Z"
arrival_scheduled_timedatetimeScheduled arrival time, format is in ISO 8601"2019-06-06T07:55:25Z"
arrival_estimated_timedatetimeEstimated arrival time, format is in ISO 8601"2019-06-06T07:55:25Z"
departure_utc_offsetstringDeparture airport timezone offset from UTC"+0600"
arrival_utc_offsetstringArrival 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:

FieldTypeDescriptionExample
takeoff_timedatetimeTake off time, format is in ISO 8601"2019-06-06T07:55:25Z"
landing_timedatetimeLanding 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"
}
}

Position token#

info

The position token is only present in streaming mode for reconnection purposes.

In case the connection is interrupted the client needs to reconnect, to avoid losing any messages which have been received in the meantime the client can send the stream position token in order to continue to receive the stream from the last known location. The position token is only sent occasionally and is intended to guarantee an “at least once” reception of each Target Update sent by the stream.

The steam position token is delivered in this format:

{
"position_token": "your_position_token"
}

Sample#

{
"position_token": "eyIwIjo0ODk0MDM4MTE5LCIxIjo0NzkyOTY0MzkxLCIyIjo0NzA2NjM3MTg1LCIzIjo0NzAzMDE3MDgwLCI0Ijo0NzYzNDA2MDgyLCI1Ijo0NzM5NjA4MjQ3fQ=="
}

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/stream",
"code": 100
}
}