Ever looked up near an airport and wondered where all those planes are going?

Turns out you don't need a Flightradar subscription to answer that. There's a free, community-run network called adsb.lol where hobbyists share data from their own ADS-B receivers, and it has an open API.

I wrote a small, zero-dependency TypeScript client for it: @matmuenzel/adsblol-ts. Let's build a tiny "what's flying around here?" CLI with it.

Setup 

mkdir sky && cd sky npm init -y npm i @matmuenzel/adsblol-ts

Node 22+ is all you need. No API key required.

The script 

// overhead.ts import { AdsbLol, callsign, altitudeFt, isMilitary } from "@matmuenzel/adsblol-ts"; const adsb = new AdsbLol(); const home = { lat: 50.03, lon: 8.57 }; // Frankfurt Airport – put your own coordinates here const { ac } = await adsb.aircraft.near({ ...home, radiusNm: 25 }); const airborne = ac .filter((a) => typeof a.alt_baro === "number") // skip planes on the ground .sort((a, b) => (a.dst ?? Infinity) - (b.dst ?? Infinity)); console.log(`✈️ ${airborne.length} aircraft within 25 NM\n`); for (const a of airborne.slice(0, 10)) { const km = a.dst !== undefined ? (a.dst * 1.852).toFixed(1) : "?"; console.log( `${(callsign(a) ?? a.hex).padEnd(9)} ${(a.t ?? "????").padEnd(5)} ` + `${String(altitudeFt(a)).padStart(6)} ft ${km.padStart(5)} km` + (isMilitary(a) ? " 🪖" : ""), ); } const { ac: emergencies } = await adsb.aircraft.bySquawk("7700"); console.log(`\n🚨 ${emergencies.length} aircraft squawking 7700 worldwide`);

Run it:

npx tsx overhead.ts

The output

This is what was flying around Frankfurt Airport (FRA) while I wrote this:

✈️ 33 aircraft within 25 NM CFG4KC A319 -100 ft 2.6 km DLA7KY E190 475 ft 4.8 km DLH3LX A320 2250 ft 5.9 km DEQFE A210 600 ft 6.8 km TUI92W B38M 2350 ft 8.4 km CFG8CT ???? 1075 ft 9.0 km DLH7AJ A320 9850 ft 13.1 km TVS2DZ BCS3 36000 ft 14.7 km DLA2LM E195 7225 ft 19.2 km CFG4CF A21N 2975 ft 19.3 km 🚨 0 aircraft squawking 7700 worldwide

You can literally watch the approach: a Condor A319 about to touch down, Air Dolomiti Embraers at a few hundred feet, and a Smartwings A220 cruising overhead at 36,000 ft without caring about Frankfurt at all. Good to know nobody worldwide was squawking 7700 (general emergency).

Fun detail: -100 ft isn't a bug. alt_baro is barometric altitude relative to standard pressure (1013.25 hPa), so on a high-pressure day an aircraft on short final can show slightly below zero.

What the client handles for you

  • Fully typed responses, generated from the OpenAPI spec, with helpers like callsign(), altitudeFt() and isMilitary()
  • Input validation before any request (bad coordinates or a radius above 250 NM throw a ValidationError without touching the network)
  • Retries with exponential backoff, honouring Retry-After on 429s
  • Typed errors (RateLimitError, TimeoutError, HttpError …)
  • Zero runtime dependencies, ESM and CJS

Other endpoints: byCallsign, byRegistration, byType, military(), closest(), airport lookups and more.

Ideas to take it further

  • A Raspberry Pi display on your desk showing the closest plane
  • A Discord/Telegram bot that pings you when an A380 or a military aircraft passes nearby
  • Logging traffic over your town for a week and charting it

Be nice to the API

adsb.lol is free and run by volunteers. Poll only as often as you need, cache where you can, and if you use the data a lot, consider feeding: a Raspberry Pi with a cheap SDR stick is enough.

Data © adsb.lol contributors, available under the ODbL.

The package is on npm and GitHub. Feedback, issues and stars are very welcome. What would you build with it? ✈️