✈️ FreeFlight API

A free, self-hosted live flight tracking API. No API key, no quotas, no credit card.

FreeFlight merges three volunteer ADS-B receiver networks (adsb.lol, airplanes.live and adsb.fi) with the OpenSky Network's global snapshot, and serves them through one clean JSON API. It also gives you flight routes, aircraft details, photos, a live map, a streaming feed, OpenSky- and ADSBExchange-compatible endpoints, and an MCP server for AI agents.

Quick start · Endpoints · Live map · Drop-in compatibility · MCP · How it works · Coverage & limits

docker run -d -p 8000:8000 ghcr.io/ethos6/free-flight-api:latest
curl "http://localhost:8000/v1/flights/nearby?lat=51.47&lon=-0.45&radius_nm=30"

{
  "count": 87,
  "aircraft": [
    {
      "hex": "406b0f", "callsign": "BAW117", "registration": "G-XWBA", "type": "A35K",
      "lat": 51.4701, "lon": -0.905, "altitude_ft": 12025, "altitude_m": 3665,
      "ground_speed_kt": 311.0, "speed_kmh": 576.0, "track": 265.1, "vertical_rate_fpm": 1984,
      "squawk": "2301", "on_ground": false, "military": false, "position_source": "adsb",
      "seen_pos_s": 0.1, "distance_nm": 17.9, "providers": ["adsb.fi", "adsb.lol", "airplanes.live"]
    }
  ],
  "providers": [ { "name": "adsb.lol", "ok": true, "aircraft": 90, "elapsed_ms": 212 }, "…" ],
  "cached": false
}

Why?

Related MCP server: adsb.lol MCP Server

✨ Features

• Three networks merged. Each aircraft is matched by its ICAO address across networks. The freshest position wins, and gaps (registration, type, callsign) are filled in from the others, so you get better coverage than any single network.

• World snapshot. /v1/flights/world returns every aircraft OpenSky is tracking worldwide (typically 10,000–13,000 aircraft), cached so it stays within OpenSky's free credit budget.

• Polite by design. Each network gets its own request pacing (about 1 req/s), with a circuit breaker on 429 or 5xx errors and automatic failover. Requests are coalesced and grid-cached, so 1,000 clients looking at the same area cost one upstream call.

• Flight lookups: callsign, ICAO hex, registration, aircraft type, military, squawk, and emergencies (7500/7600/7700).

• /v1/track/{callsign} returns the live position, origin and destination airports and airline (from adsbdb), aircraft owner and model, and a photo (from planespotters.net).

• Streaming. /v1/stream/nearby is a Server-Sent Events feed that pushes a fresh snapshot every few seconds.

• Filters: altitude, on-ground, military, aircraft type, and limit.

• Units: both aviation and metric (ft and m, kt and km/h).

• Live map at /, built with Leaflet. Click any plane for its route and photo, or search by callsign.

• Drop-in replacement for the OpenSky REST API and the ADSBExchange v2 / adsb.lol API.

• An MCP server, a CLI, Docker, and optional API keys and rate limiting.

🚀 Quick start

# Docker (one command)
docker run -d -p 8000:8000 ghcr.io/ethos6/free-flight-api:latest

# or from source
git clone https://github.com/Ethos6/free-flight-api && cd free-flight-api && docker compose up -d

# or pip
pip install "free-flight-api[mcp] @ git+https://github.com/Ethos6/free-flight-api"
freeflight serve

Open http://localhost:8000 for the live map, or /docs for the interactive API.

CLI:

freeflight nearby 40.64 -73.78 -r 25        # planes around JFK
freeflight track BAW117                     # live position + route + aircraft + photo
freeflight world                            # how many aircraft are flying right now
freeflight check                            # health table for every data network

📡 Endpoints

Filters work on every list endpoint: min_alt, max_alt (feet), on_ground, military, type=A320,B738, and limit.

🗺️ Live map

http://localhost:8000 opens a full-screen live map. When you zoom in, it shows rotated plane icons that refresh every 8 seconds. When you zoom out to a continent or the whole world, it switches to a fast dot view. Click a plane to see its route, aircraft type, registration and a photo. The search box finds any callsign or ICAO hex.

🔁 Drop-in replacement

So tar1090-style tools, OpenSky scripts and existing ADS-B dashboards can use FreeFlight without code changes.

🤖 MCP server for AI agents

{ "mcpServers": { "freeflight": { "command": "freeflight", "args": ["mcp"] } } }

This gives your assistant four tools: flights_near, track_flight, emergencies and military_aircraft. You can then ask things like "What's flying over my house right now?" or "Where is BA117 and when did it leave London?"

🧠 How it works

flowchart LR
    C[Clients · map · MCP] --> API[FreeFlight API]
    API --> K{Grid cache +<br>request coalescing}
    K -- miss --> P[Paced fan-out<br>~1 req/s per network]
    P --> L[adsb.lol]
    P --> A[airplanes.live]
    P --> F[adsb.fi]
    API -->|large areas / world| O[OpenSky global snapshot<br>cached 90 s – 15 min]
    L & A & F --> M[Merge by ICAO hex<br>freshest position wins]
    M --> K
    API --> E[adsbdb routes · planespotters photos<br>cached 24 h]

1. Grid cache. A request is snapped to a 0.25° grid and a fixed set of radius sizes, so nearby users share the same upstream request. Results are then filtered to each user's exact circle.

2. Coalescing. If 1,000 identical requests arrive at once, they wait for one upstream call.

3. Pacing and circuit breaking. No network is called more than about once per second. A network that returns 429 or errors cools down while the others keep answering.

4. Merge. Records are de-duplicated by ICAO address, the freshest position is kept, and missing fields are filled from the other networks.

📊 Coverage: honest numbers

• Where coverage comes from. Live data comes from thousands of volunteer ADS-B and MLAT receivers. Coverage is excellent over North America, Europe, and much of Asia and Oceania. It is patchy over oceans, polar regions and parts of Africa, because there are no ground receivers there.

• What gets tracked. Aircraft are tracked when they carry an ADS-B or Mode-S transponder that a receiver can hear. That covers virtually all airliners and most business jets and general aviation. Gliders and aircraft without transponders may be missing.

• The world snapshot. /v1/flights/world is OpenSky's global view. Anonymous access gets about 100 global queries per day, so FreeFlight refreshes it every 15 minutes by default. Create a free OpenSky API client and set FREEFLIGHT_OPENSKY_CLIENT_ID and FREEFLIGHT_OPENSKY_CLIENT_SECRET to refresh it every 90 seconds.

• Some networks restrict datacenter IPs. In our GitHub Actions check, adsb.fi and OpenSky answered (12,063 aircraft in the world snapshot) while airplanes.live returned 403 and adsb.lol timed out from GitHub's cloud runners. From home and residential connections all networks normally work. FreeFlight fails over automatically, so you get the networks that are reachable from your server.

• Daily health check. The Provider health workflow queries every network from a GitHub runner and posts the results.

⚖️ Data sources & terms

FreeFlight is a client. The data belongs to the networks that collect it. Please respect their terms and support them, ideally by feeding a receiver.

For commercial use, get a commercial license from the providers, or switch networks off with FREEFLIGHT_PROVIDERS and FREEFLIGHT_OPENSKY=false.

⚙️ Configuration

See .env.example.

🛠 Development

pip install -e ".[dev]"
pytest              # offline: every upstream is mocked from fixtures
ruff check .
freeflight check    # live check from your machine

PRs are welcome, especially new data networks, airport and airline databases, and map features.

📄 License

MIT. If FreeFlight is useful to you, please ⭐ star the repo and consider feeding ADS-B data to one of the networks.

See also: FreeSearch API · FreeNews API