DEV Community

Wei Bin
Wei Bin

Posted on

How to track a live flight with one API call (real ADS-B data, no enterprise feed)

Every side project that touches flight data hits the same wall: the well-known flight data feeds are priced for airlines and enterprises, and the "free" tiers are either schedule data dressed up as live, or demos that die the moment you ship.

I wanted actual live positions — where is this aircraft, right now — for a tracker widget I was building. So I built FlightScope on top of the open ADS-B receiver network (adsb.lol) plus the OurAirports and OpenFlights datasets, and I've been running it as a public API since. This post is a walkthrough of what the data really looks like, with responses I captured live while writing it.

One call: the complete live profile of a flight

Give the API a flight number — IATA (TS655) or ICAO (TSC655) form both work — and you get the operator, the aircraft, and its live position in a single response:

{
  "flight": { "iata": "TS655", "callsign": "TSC655",
    "airline": { "name": "Air Transat", "iata": "TS", "icao": "TSC" } },
  "aircraft": { "icao24": "c051d1", "registration": "C-GEZO", "typeCode": "A321" },
  "live": { "latitude": 40.889648, "longitude": -73.986694,
    "altitudeFt": 35025, "groundSpeedKt": 464.3, "trackDeg": 19.76,
    "verticalRateFpm": 128, "onGround": false, "phase": "airborne",
    "squawk": "6166", "lastSeenSecondsAgo": 0 },
  "ageSeconds": 0
}
Enter fullscreen mode Exit fullscreen mode

That's an Air Transat A321 at 35,025 ft doing 464 knots over New Jersey, climbing gently at 128 feet per minute, captured the second I asked. The fields worth noticing:

  • lastSeenSecondsAgo / ageSeconds — ADS-B data is only honest if it tells you how old it is. Every live response carries its freshness, and positions served from the short edge cache say so. A tracker that hides this is showing you a plane that may have landed ten minutes ago.
  • phase — ground vs airborne, derived from the broadcast itself (the barometric altitude field), and labelled as derived in the full response. It is not the airline's official status, and the API says that in the payload rather than in fine print.

"What's flying over me right now?"

The endpoint I end up demoing most is the radius query. One call over JFK (40.6413, −73.7781, 80 km radius) came back with 30 aircraft — callsigns, types, altitudes, speeds, ground flags — everything you need to draw a live map:

GET /flights/near?lat=40.6413&lon=-73.7781&radiusKm=80
→ { "count": 30, "flights": [ { "callsign": "TSC655", "typeCode": "A321",
    "altitudeFt": 35025, "groundSpeedKt": 464.3, "onGround": false }, … ] }
Enter fullscreen mode Exit fullscreen mode

No polling a firehose, no WebSocket plumbing — a stateless GET you can call from a cron job, a Cloudflare Worker, or a browser.

The batch trick: 100 flights, one call

If you're building a fleet board or a multi-flight tracker, per-flight polling burns quota fast. The batch endpoint takes up to 100 flight numbers in one POST and returns one result per flight plus a summary — and the whole batch counts as one call against your quota:

curl -X POST "https://flightscope-live-flight-tracking-and-airport-data-api.p.rapidapi.com/flights/batch" \
  -H "X-RapidAPI-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"flights": ["TS655", "AAL751", "DL123"]}'
Enter fullscreen mode Exit fullscreen mode

That pricing-of-attention detail — batch = 1 call — is deliberate. I'd rather you build the dashboard than ration refreshes.

Airports without a second API

Trackers always end up needing airport context too, so the same API carries profiles for 3,270 commercial airports from OurAirports (public domain): codes, coordinates, elevation, municipality, and links. GET /airport/KJFK returns John F. Kennedy International with its IATA/ICAO codes, position and elevation in the same response shape as everything else. There's also /airports/search for name/city/code lookup and /aircraft/{icao24} for looking an airframe up by transponder hex.

The honest limits of ADS-B

Three things this kind of data cannot do, which I learned to state up front because users discover them anyway:

  1. If it isn't broadcasting, it isn't there. A flight with no live ADS-B signal returns 404 FLIGHT_NOT_LIVE. That means "no receiver heard it just now" — not "cancelled", not "doesn't exist". Military traffic and some regions are simply dark.
  2. No schedules, no gates, no delay minutes. ADS-B tells you where an aircraft physically is. Departure boards, terminals and baggage belts live in airline systems, not in radio broadcasts.
  3. Coverage follows the receiver network. Over the US and Europe it's dense; over oceans it's sparse. The ageSeconds field is how you stay truthful about that in your UI.

Within those limits, though, the data is genuinely live and genuinely open — the sources (adsb.lol, OurAirports, OpenFlights) are credited in every response, as their licences require.

Try it

FlightScope is on RapidAPI with a free tier that's enough to wire up and test a real integration, plus paid tiers if your tracker takes off:

If you build something with it — a spotted-over-my-house bot, a fleet board, a spotter app — I'd love to see it. And if there's a field you wish the response had, tell me; the schema is versioned precisely so it can grow without breaking you.

Top comments (0)