Sample API Call

Below is a practical example tailored to the ADS‑B Exchange v2 “Get aircraft by ICAO” endpoint, along with a clear breakdown of the response structure. See ADS-B Exchange API Documentation for full details and examples.

1. Endpoint Overview

Operation: GetApiAircraftV2Icao
Purpose: Retrieve live positional data for one or more aircraft by ICAO hex code
Base URL:
https://gateway.adsbexchange.com/api/aircraft/v2/icao/{icao}
Authentication:
Required via HTTP header:
api-auth: YOUR_API_KEY

2. Sample API Call

Example: Get live data for ICAO A465DF
HTTP Request (JSON)
GET /api/aircraft/v2/icao/A465DF HTTP/1.1 Host: gateway.adsbexchange.com Accept: application/json api-auth: YOUR_API_KEY
cURL Equivalent
curl -X GET "https://gateway.adsbexchange.com/api/aircraft/v2/icao/A465DF" \ -H "Accept: application/json" \ -H "api-auth: YOUR_API_KEY"
✅ Multiple ICAOs can be comma‑separated (up to API limits), for example:
/api/aircraft/v2/icao/A465DF,A1B2C3

Python

import requests

    ICAO_HEX = “A465DF”  # 6-hex ICAO (Mode S)

    API_KEY = “YOUR_API_KEY”

    url = f”https://gateway.adsbexchange.com/api/aircraft/v2/icao/{ICAO_HEX}”

    headers = {

        “Accept”: “application/json”,

        “api-auth”: API_KEY,  # ADS-B Exchange uses api-auth header [^1]

    }

    resp = requests.get(url, headers=headers, timeout=15)

    resp.raise_for_status()

    data = resp.json()

    print(data)

    # Example: pull first aircraft (if present)

    ac_list = data.get(“ac”, [])

    if ac_list:

        first = ac_list[0]

        print(“hex:”, first.get(“hex”))

        print(“lat/lon:”, first.get(“lat”), first.get(“lon”))

    else:

        print(“No aircraft returned. msg:”, data.get(“msg”))
C# (.NET) using HttpClient)

using System;

    using System.Net.Http;

    using System.Net.Http.Headers;

    using System.Text.Json;

    using System.Threading.Tasks;

    public class AdsbxExample

    {

        public static async Task Main()

        {

            var icaoHex = “A465DF”;

            var apiKey = “YOUR_API_KEY”;

            var url = $”https://gateway.adsbexchange.com/api/aircraft/v2/icao/{icaoHex}”;

            using var http = new HttpClient();

            http.DefaultRequestHeaders.Accept.Clear();

            http.DefaultRequestHeaders.Accept.Add(

                new MediaTypeWithQualityHeaderValue(“application/json”));

            // ADS-B Exchange uses api-auth header [^1]

            http.DefaultRequestHeaders.Add(“api-auth”, apiKey);

            using var response = await http.GetAsync(url);

            response.EnsureSuccessStatusCode();

            var json = await response.Content.ReadAsStringAsync();

            Console.WriteLine(json);

            // Optional: parse to JsonDocument to inspect fields safely

            using var doc = JsonDocument.Parse(json);

            if (doc.RootElement.TryGetProperty(“ac”, out var ac) && ac.ValueKind == JsonValueKind.Array && ac.GetArrayLength() > 0)

            {

                var first = ac[0];

                Console.WriteLine(“hex: ” + (first.TryGetProperty(“hex”, out var hex) ? hex.GetString() : “(missing)”));

                Console.WriteLine(“lat: ” + (first.TryGetProperty(“lat”, out var lat) ? lat.GetDouble().ToString() : “(missing)”));

                Console.WriteLine(“lon: ” + (first.TryGetProperty(“lon”, out var lon) ? lon.GetDouble().ToString() : “(missing)”));

            }

            else

            {

                Console.WriteLine(“No aircraft returned. msg: ” +

                    (doc.RootElement.TryGetProperty(“msg”, out var msg) ? msg.GetString() : “(missing)”));

            }

        }

    }

3. Top‑Level Response Structure

The v2 API returns a wrapper object with metadata plus an aircraft array.

{

“ac”: [ … ],

“msg”: “No error”,

“now”: 1675633671226,

“total”: 1,

“ctime”: 1675633671226,

“ptime”: 0

}

Top‑Level Fields Explained

Field	Type	Description
ac	array	List of aircraft objects
msg	string	Status message (“No error” if OK)
now	number	Response generation time (ms since Unix epoch)
total	number	Number of aircraft returned
ctime	number	Cache timestamp (ms since Unix epoch)
ptime	number	Server processing time (ms)

These fields are defined in the ADS‑B Exchange v2 API field reference

4. Sample Aircraft Object (ac[])

Below is a realistic, trimmed example of a single aircraft entry returned by this endpoint.

{

“hex”: “a465df”,

“type”: “adsb_icao”,

“flight”: “UAL1310”,

“r”: “N38257”,

“t”: “B738”,

“lat”: 37.358322,

“lon”: -93.374147,

“alt_baro”: 38000,

“alt_geom”: 38275,

“gs”: 338.9,

“track”: 276.1,

“baro_rate”: 0,

“squawk”: “3301”,

“emergency”: “none”,

“category”: “A2”,

“nav_qnh”: 1013.6,

“nav_altitude_mcp”: 38016,

“nav_heading”: 280.55,

“nav_modes”: [“autopilot”, “althold”, “lnav”],

“nic”: 9,

“rc”: 75,

“seen_pos”: 3.486,

“messages”: 24844,

“seen”: 0.7,

“rssi”: -15.8

}

5. Key Aircraft Fields (Most Commonly Used)

Field	Meaning
hex	ICAO 24‑bit hex identifier
flight	Callsign (may be padded)
r	Aircraft registration
t	ICAO aircraft type (DOC 8643)
lat / lon	Latitude / Longitude
alt_baro	Barometric altitude (ft)
alt_geom	Geometric altitude (ft)
gs	Ground speed (knots)
track	True track (degrees)
baro_rate	Vertical rate (ft/min)
squawk	Transponder squawk
emergency	Emergency state
category	ICAO emitter category
seen_pos	Seconds since last position update
messages	Total messages received
rssi	Signal strength (dB)