ADS-B Aircraft Tracking

Track aircraft in real-time using ADS-B (Automatic Dependent Surveillance-Broadcast) data. The API maintains a persistent TCP connection to an ADS-B data hub and enriches raw position data with aircraft registration, type, and airline information from a 615,000+ aircraft database.

Get Tracked Aircraft

GET /v3/adsb/aircraft

Returns a list of all currently tracked aircraft with their latest position and flight data. Supports extensive filtering by location, altitude, speed, callsign, registration, and airline.

Parameters

All parameters are optional. When no filters are applied, all currently tracked aircraft are returned.

Parameter	Type	In	Required	Description
icao24	string	query	No	Filter by ICAO24 hex identifier (6 hex characters, e.g., 40621D)
callsign	string	query	No	Filter by callsign (partial match, case-insensitive)
lat	float	query	No	Center latitude for radius search (-90 to 90)
lon	float	query	No	Center longitude for radius search (-180 to 180)
radius	float	query	No	Search radius in kilometers (0 to 1,000). Requires lat and lon.
bbox	string	query	No	Bounding box as lat1,lon1,lat2,lon2 (SW corner, NE corner)
min_alt	float	query	No	Minimum altitude in feet (0 to 60,000)
max_alt	float	query	No	Maximum altitude in feet (0 to 60,000)
min_speed	float	query	No	Minimum ground speed in knots (0 to 1,000)
max_speed	float	query	No	Maximum ground speed in knots (0 to 1,000)
registration	string	query	No	Filter by aircraft registration (exact match, case-insensitive)
airline	string	query	No	Filter by airline ICAO code or name (partial match, case-insensitive)
photos	bool	query	No	Include aircraft photos from airport-data.com (default: false)

Performance

Set photos=false (the default) for faster responses when you only need position data. When photos=true, photo fetching is capped at 50 aircraft to limit response time.

Response Fields

Field	Type	Description
aircraft	array	List of aircraft objects
total_count	integer	Total number of aircraft in the response
timestamp	string	ISO 8601 timestamp of the response

Aircraft Object Fields

Field	Type	Description
icao24	string	ICAO24 hex transponder address
callsign	string	Flight callsign (e.g., BAW123)
latitude	float	Current latitude
longitude	float	Current longitude
altitude	float	Altitude in feet
ground_speed	float	Ground speed in knots
track	float	Track angle in degrees (0-360)
vertical_rate	float	Vertical rate in feet per minute
is_on_ground	bool	Whether the aircraft is on the ground
last_seen	string	ISO 8601 timestamp of last received message
first_seen	string	ISO 8601 timestamp of first received message
registration	string	Aircraft registration / tail number (if available)
aircraft_type	string	Aircraft type name (if available)
airline	string	Operating airline name (if available)
photo_url	string	Aircraft photo URL (only when photos=true)

Response Example

{
  "aircraft": [
    {
      "icao24": "40621D",
      "callsign": "BAW123",
      "latitude": 51.4706,
      "longitude": -0.4619,
      "altitude": 35000.0,
      "ground_speed": 450.5,
      "track": 89.2,
      "vertical_rate": 0.0,
      "is_on_ground": false,
      "last_seen": "2026-02-11T12:00:00Z",
      "first_seen": "2026-02-11T11:45:00Z",
      "registration": "G-STBC",
      "aircraft_type": "Boeing 777-36N",
      "airline": "British Airways",
      "photo_url": "https://image.airport-data.com/aircraft/001912010.jpg"
    }
  ],
  "total_count": 4691,
  "timestamp": "2026-02-11T12:00:30Z"
}

---

Tracking Statistics

GET /v3/adsb/aircraft/statistics

Returns aggregate statistics about currently tracked aircraft, including total counts, altitude distribution, and speed statistics. No parameters required.

Response Example

{
  "total_aircraft": 4691,
  "with_position": 4200,
  "on_ground": 312,
  "airborne": 3888,
  "altitude_distribution": {
    "below_10000": 520,
    "10000_to_20000": 380,
    "20000_to_30000": 610,
    "30000_to_40000": 2100,
    "above_40000": 278
  },
  "average_speed_kts": 385.2,
  "max_speed_kts": 612.0
}

---

Service Health

GET /v3/adsb/health

Returns the health status of the ADS-B data ingestion service. No parameters required.

Health Response Fields

Field	Type	Description
status	string	Service status: healthy, connected_no_data, degraded, offline
connected	bool	Whether the TCP connection is established
active_aircraft_count	integer	Number of aircraft currently being tracked
connection_uptime	string	Connection uptime duration (or null)
last_message_received	string	ISO 8601 timestamp of the last received message

Health Response Example

{
  "status": "healthy",
  "connected": true,
  "active_aircraft_count": 4691,
  "connection_uptime": null,
  "last_message_received": "2026-02-11T12:00:30Z"
}

Health Status Values

Status	Meaning
healthy	Connected and receiving data
connected_no_data	TCP connection active but no recent aircraft data
degraded	Service running but connection lost
offline	Service is not running

---

Code Examples

cURL

# Get all tracked aircraft (no photos, fastest)
curl -X GET "YOUR_API_BASE_URL/v3/adsb/aircraft" \
  -H "X-RapidAPI-Key: YOUR_API_KEY"

# Filter by callsign
curl -X GET "YOUR_API_BASE_URL/v3/adsb/aircraft?callsign=BAW" \
  -H "X-RapidAPI-Key: YOUR_API_KEY"

# Aircraft within 50km radius of London Heathrow with photos
curl -X GET "YOUR_API_BASE_URL/v3/adsb/aircraft?lat=51.47&lon=-0.46&radius=50&photos=true" \
  -H "X-RapidAPI-Key: YOUR_API_KEY"

# Bounding box over Western Europe
curl -X GET "YOUR_API_BASE_URL/v3/adsb/aircraft?bbox=45.0,-5.0,55.0,10.0" \
  -H "X-RapidAPI-Key: YOUR_API_KEY"

# High-altitude aircraft only (FL300+)
curl -X GET "YOUR_API_BASE_URL/v3/adsb/aircraft?min_alt=30000" \
  -H "X-RapidAPI-Key: YOUR_API_KEY"

# Filter by speed range (cruise speed aircraft)
curl -X GET "YOUR_API_BASE_URL/v3/adsb/aircraft?min_speed=400&max_speed=600" \
  -H "X-RapidAPI-Key: YOUR_API_KEY"

# Lookup specific aircraft by ICAO24
curl -X GET "YOUR_API_BASE_URL/v3/adsb/aircraft?icao24=40621D" \
  -H "X-RapidAPI-Key: YOUR_API_KEY"

# Filter by registration
curl -X GET "YOUR_API_BASE_URL/v3/adsb/aircraft?registration=G-STBC" \
  -H "X-RapidAPI-Key: YOUR_API_KEY"

# Filter by airline
curl -X GET "YOUR_API_BASE_URL/v3/adsb/aircraft?airline=British" \
  -H "X-RapidAPI-Key: YOUR_API_KEY"

# Get tracking statistics
curl -X GET "YOUR_API_BASE_URL/v3/adsb/aircraft/statistics" \
  -H "X-RapidAPI-Key: YOUR_API_KEY"

# Check service health
curl -X GET "YOUR_API_BASE_URL/v3/adsb/health" \
  -H "X-RapidAPI-Key: YOUR_API_KEY"

Python

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "YOUR_API_BASE_URL"

def get_aircraft(
    icao24=None, callsign=None,
    lat=None, lon=None, radius=None,
    bbox=None,
    min_alt=None, max_alt=None,
    min_speed=None, max_speed=None,
    registration=None, airline=None,
    photos=False
) -> dict:
    """Get tracked aircraft with optional filters."""
    params = {"photos": photos}
    if icao24: params["icao24"] = icao24
    if callsign: params["callsign"] = callsign
    if lat is not None: params["lat"] = lat
    if lon is not None: params["lon"] = lon
    if radius is not None: params["radius"] = radius
    if bbox: params["bbox"] = bbox
    if min_alt is not None: params["min_alt"] = min_alt
    if max_alt is not None: params["max_alt"] = max_alt
    if min_speed is not None: params["min_speed"] = min_speed
    if max_speed is not None: params["max_speed"] = max_speed
    if registration: params["registration"] = registration
    if airline: params["airline"] = airline

    response = requests.get(
        f"{BASE_URL}/v3/adsb/aircraft",
        headers={"X-RapidAPI-Key": API_KEY},
        params=params
    )
    response.raise_for_status()
    return response.json()

def get_statistics() -> dict:
    """Get ADS-B tracking statistics."""
    response = requests.get(
        f"{BASE_URL}/v3/adsb/aircraft/statistics",
        headers={"X-RapidAPI-Key": API_KEY}
    )
    response.raise_for_status()
    return response.json()

def get_health() -> dict:
    """Check ADS-B service health."""
    response = requests.get(
        f"{BASE_URL}/v3/adsb/health",
        headers={"X-RapidAPI-Key": API_KEY}
    )
    response.raise_for_status()
    return response.json()

# All aircraft
data = get_aircraft()
print(f"Tracking {data['total_count']} aircraft")

# Aircraft near JFK Airport within 100km
data = get_aircraft(lat=40.64, lon=-73.78, radius=100)
print(f"Aircraft near JFK: {data['total_count']}")
for ac in data["aircraft"][:5]:
    print(f"  {ac['callsign'] or 'N/A'} - {ac['airline'] or 'Unknown'} "
          f"at {ac['altitude']}ft, {ac['ground_speed']}kts")

# High-altitude jets with photos
data = get_aircraft(min_alt=35000, max_alt=45000, photos=True)
for ac in data["aircraft"][:3]:
    print(f"  {ac['callsign']} ({ac['aircraft_type']}) FL{int(ac['altitude']/100)}")
    if ac.get("photo_url"):
        print(f"    Photo: {ac['photo_url']}")

# British Airways flights
data = get_aircraft(airline="British Airways")
for ac in data["aircraft"]:
    print(f"  {ac['callsign']} - {ac['registration']} ({ac['aircraft_type']})")

# Service health check
health = get_health()
print(f"Status: {health['status']}, Tracking: {health['active_aircraft_count']} aircraft")

# Statistics
stats = get_statistics()
print(f"Total: {stats['total_aircraft']}, Airborne: {stats.get('airborne', 'N/A')}")

JavaScript

const API_KEY = "YOUR_API_KEY";
const BASE_URL = "YOUR_API_BASE_URL";

async function getAircraft(filters = {}) {
  const params = new URLSearchParams();
  params.set("photos", filters.photos ?? false);

  if (filters.icao24) params.set("icao24", filters.icao24);
  if (filters.callsign) params.set("callsign", filters.callsign);
  if (filters.lat != null) params.set("lat", filters.lat);
  if (filters.lon != null) params.set("lon", filters.lon);
  if (filters.radius != null) params.set("radius", filters.radius);
  if (filters.bbox) params.set("bbox", filters.bbox);
  if (filters.minAlt != null) params.set("min_alt", filters.minAlt);
  if (filters.maxAlt != null) params.set("max_alt", filters.maxAlt);
  if (filters.minSpeed != null) params.set("min_speed", filters.minSpeed);
  if (filters.maxSpeed != null) params.set("max_speed", filters.maxSpeed);
  if (filters.registration) params.set("registration", filters.registration);
  if (filters.airline) params.set("airline", filters.airline);

  const response = await fetch(`${BASE_URL}/v3/adsb/aircraft?${params}`, {
    headers: { "X-RapidAPI-Key": API_KEY },
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.detail || `HTTP ${response.status}`);
  }

  return response.json();
}

async function getStatistics() {
  const response = await fetch(`${BASE_URL}/v3/adsb/aircraft/statistics`, {
    headers: { "X-RapidAPI-Key": API_KEY },
  });
  return response.json();
}

async function getHealth() {
  const response = await fetch(`${BASE_URL}/v3/adsb/health`, {
    headers: { "X-RapidAPI-Key": API_KEY },
  });
  return response.json();
}

// All aircraft near London Heathrow
getAircraft({ lat: 51.47, lon: -0.46, radius: 50 }).then((data) => {
  console.log(`${data.total_count} aircraft near LHR`);
  data.aircraft.forEach((ac) => {
    console.log(
      `  ${ac.callsign || "N/A"} - Alt: ${ac.altitude}ft, Speed: ${ac.ground_speed}kts`
    );
  });
});

// Specific aircraft by ICAO24 with photos
getAircraft({ icao24: "40621D", photos: true }).then((data) => {
  if (data.aircraft.length > 0) {
    const ac = data.aircraft[0];
    console.log(`${ac.registration} (${ac.aircraft_type})`);
    console.log(`Position: ${ac.latitude}, ${ac.longitude}`);
    if (ac.photo_url) console.log(`Photo: ${ac.photo_url}`);
  }
});

// Bounding box over continental US
getAircraft({ bbox: "25.0,-125.0,50.0,-65.0" }).then((data) => {
  console.log(`${data.total_count} aircraft over CONUS`);
});

// Health check
getHealth().then((health) => {
  console.log(`ADS-B Status: ${health.status}`);
  console.log(`Tracking: ${health.active_aircraft_count} aircraft`);
});

Error Responses

Status	Description
400	Invalid ICAO24 format (must be 6 hex characters)
400	Radius search missing required lat, lon, or radius parameter
400	Invalid bounding box format
400	min_alt must be less than max_alt
400	min_speed must be less than max_speed
500	Failed to retrieve aircraft data

v3 Improvement

The v3 ADS-B endpoint adds an explicit photos toggle (default false). In v2, aircraft photos are never included. Setting photos=true in v3 fetches aircraft photos from airport-data.com for up to 50 aircraft in the response.

Bounding Box Format

The bbox parameter uses the format lat1,lon1,lat2,lon2 where lat1,lon1 is the southwest corner and lat2,lon2 is the northeast corner. Both lat1 < lat2 and lon1 < lon2 must hold true.

Combining Filters

Filters can be combined freely. For example, you can search for aircraft within a radius that are above a certain altitude and belong to a specific airline. Filters are applied sequentially, narrowing the result set with each additional parameter.