Traffic API V1

This API is used to receive the air traffic data collected by the network of INVOLI receivers or other sources, which are feeding the INVOLI.live server.

The traffic REST API is on the endpoint:

https://api.involi.live/v1/traffic

Authorization is granted via a bearer token in the HTTP header.

Example: Authorization: bearer <token>

The token must be requested from the authentication server with your client id and client secret.

Sources

The API provides aircraft data from multiple sources. A list of available sources can be obtained by making a GET request on https://api.involi.live/v1/traffic/sources. The response contains the ID of each source alongside a human-readable description.

Example Response:

[ 
    {
        "id": "986e94de-4a20-42ad-ab10-1206cb7e2846",
        "label": "ADS-B"
        "description": "ADS-B data from INVOLI receivers"
    },
    {
        "id": "a1f0dd50-04d8-410c-87e6-b8bd1771b5d9",
        "label: "UAT"
        "description": "UAT data from INVOLI receivers"
    }
]

Field	Type	Description
id	string	ID of the data source
label	string	Label of the data source
description (optional)	string	Description of the data source

Request

An HTTP GET request on the endpoint returns a full snapshot of current air traffic.

It is also possible to send a POST request with a JSON body containing settings to narrow down the data. All settings in this JSON are optional.

Examples of request body with source selection or with all settings:

{
    "selectedTrafficSourceIds": [
        "986e94de-4a20-42ad-ab10-1206cb7e2846"
    ]
}

{
    "boundingBox":
    {
        "southLatitude": 48.0,
        "northLatitude": 51.0,
        "westLongitude": 6.0,
        "eastLongitude": 7.0
    },
    "upperAltitude": 10000,
    "lowerAltitude": 0,
    "selectedTrafficSourceIds": [
        "986e94de-4a20-42ad-ab10-1206cb7e2846"
    ]
}

Field	Type	Unit	Description
boundingBox.southLatitude (optional)	float	°	South latitude limit
boundingBox.northLatitude (optional)	float	°	North latitude limit
boundingBox.westLongitude (optional)	float	°	West longitude limit
boundingBox.eastLongitude (optional)	float	°	East longitude limit
upperAltitude (optional)	float	m	Upper limit on aircraft altitude
lowerAltitude (optional)	float	m	Lower limit on aircraft altitude
selectedTrafficSourceIds (optional)	string array		List of source IDs to get traffic from (see Sources above) ; if not provided all available sources are included

Altitude corresponds to elevation above WGS84 reference ellipsoid.

Warning: if request options are used, aircraft without known altitude will not be returned.

Data format

The API returns a list of aircraft and (optionally) adsb records.

The response data is always compressed and cannot be requested in plain format. Attempting to do so will result in a "406 Not Acceptable" error. Supported encoding: gzip, deflate.

Example aircraft record:


{
  "aircraft": {
    "ids": {
      "icao": "3006b5",
      "iid": "e1399607-ad09-46c3-9854-337bfa27d378"
    },
    "latitude": 48.51804571636652,
    "longitude": 13.047421242285054,
    "position_timestamp": [
      1711100527,
      277885249
    ],
    "wgs84_altitude": 9372.6,
    "barometric_altitude": 9144,
    "ground_speed": 195.19201354382324,
    "vertical_speed": 0,
    "ground_status": "airborne",
    "timestamp": [
      1711100527,
      652503876
    ],
    "course": 299.8759926916894,
    "aircraft_type": "large_plane",
    "call_sign": "DLA97F",
    "source_id": "dc19dbbd-186a-4dad-9593-342461e20309"
  },
  "adsb": {
    "gva": 2,
    "nac_p": 9,
    "nac_v": 1,
    "nic": 8,
    "q_bit": true,
    "rebroadcast": false,
    "sda": 2,
    "sil": 3
  }
}

Aircraft Fields Description:

Field	Type	Unit	Description
source_id	string		ID of the source
ids.iid	string		Internal aircraft ID
ids.icao	string		ICAO
ids.tisb_site_id	int		Site ID for TIS-B messages only for source: UAT, 0 otherwise
ids.track	string		Track ID only for source: MLAT Mode A/C
ids.serial_number	string		LEMAN tracker serial number only for sources: Remote ID Broadcast, Remote ID Network
ids.uas_id	string		UAS ID only for sources: Remote ID Broadcast, Remote ID Network
ids.wifi_mac	string		MAC address of the broadcasting device only for source: Remote ID Broadcast
aircraft_type	string	enum	Type of the aircraft, for example, small_plane (see full list below).
latitude	float	°
longitude	float	°
position_timestamp	array	[s, ns]	Timestamp of the last position update (latitude and longitude). It is older than “timestamp”, if current message does not contain the new position information. If it contains position information, it is equal to “timestamp”(****)
wgs84_altitude	float	m	Elevation above WGS84 reference ellipsoid
barometric_altitude	float	m	Air pressure in terms of altitude in the Internal Standard Atmosphere
call_sign	string		Call sign advertised by the aircraft
registration (*)	string		Official registration of the aircraft.
squawk	string		4-digit transponder squawk
course (**)	float	°	Aircraft tracking over ground. Degrees from North
heading (***)	float	°	Aircraft orientation (nose). Degrees from North
ground_speed	float	m/s	The horizontal speed of the aircraft relative to the ground
ground_status	string	enum	- airborne - on_ground - unknown
timestamp	array	[s, ns]	Original message timestamp indicating reception time, set in the receiver (separated in seconds and nanoseconds)
vertical_speed	float	m/s	The vertical component of the aircraft's speed. The vertical speed is positive when gaining altitude (going up) and negative when losing altitude.

All fields are optional except ids and source_id. This is because not all information is available depending on the source.

(*) - Often the registration field is not present, because it is not transmitted by the airplane

(**), (***) - These two information elements are not always the same, even if they look similar. The heading is the direction in which the airplane nose is pointing and is often not included. Instead, the course is used.

(****) Due to the characteristic of the Internet, it can sometimes happen, that the later message without position arrive at our server before earlier message with the new position. We do not discard such messages and in this case the “timestamp” is earlier than “position_timestamp”.

Aircraft Types:

unknown
small_plane
large_plane
helicopter
paraglider
parachute
balloon
drone
ground_obstacle
ground_vehicle
ground_operator

ADS-B Fields Description (only available for ADSB sources):

Field	Type	Description
adsb_version	integer	ADS-B version
nac_p	integer	Navigation accuracy category (position)
nac_v	integer	Navigation accuracy category (velocity)
nic	integer	Navigation integrity category
sil	integer	Surveillance integrity level
sda	integer	System design assurance
q_bit	boolean	Atitude quantization bit
gva	integer	Geometric vertical accuracy
rebroadcast	boolean	true if this is a rebroadcast ADS-B message

Restrictions

The INVOLI server receives and responds to the requests for a given client ID. The recommended rate is 1 request per 1 second. If the number of requests increases, the server will reply with status code 429: "Too many requests". If multiple servers or clients need to access an API, each should have its unique client ID.

PreviousNext