How to Track a Flight — Developer Guide to Flight Identification and Lifecycle

How to track a flight — developer guide. Five ways to identify any flight, the complete flight lifecycle from scheduled to landed, which API endpoint returns what data at each stage, time zone handling, codeshare detection and tracking edge cases.

Sergey St.

Published on Jun 5th 26

Share:

• 
• 
• 

The Problem Nobody Talks About — Identifying the Flight First

Most flight tracking tutorials start with a flight number and immediately call a status endpoint. In production, this is the easy case. The hard part — the part that breaks real applications — is identifying the right flight in the first place. A user might give you a flight number that exists three times today (different airlines codeshare it). A logistics platform might have only the tail number. An aviation hobbyist might have only the ICAO24 hex from an ADS-B receiver. A traveler might know the route but not the carrier.

A proper flight tracking implementation handles all of these identification cases. This guide walks through the five canonical ways to identify a flight, what the API returns at each phase of the flight's lifecycle, and the edge cases that trip up most production tracking systems — codeshares, diversions, time zones and cancellations.

"Flight tracking has two halves: identification and observation. Most tutorials only cover observation. The reason flight tracking apps break in production is usually wrong or ambiguous identification — the wrong flight gets tracked, or no flight gets found, because the input was not normalized correctly."

Five Ways to Identify a Flight

Every flight in the world can be identified in at least five different ways. Each identifier is useful in different contexts, and the AirLabs API supports lookups by any of them.

1. IATA Flight Number

The most common identifier — the one passengers see on their boarding passes. It combines the airline's 2-letter IATA code with a flight number: BA117, AA100, LH401. This is the marketing flight number — the one the ticket-issuing airline uses to refer to the flight.

GET https://airlabs.co/api/v9/flight?flight_iata=BA117&api_key={KEY}

The IATA flight number is what users typically type into "track my flight" interfaces. It is the natural starting point for passenger-facing applications.

2. ICAO Flight Code

The ICAO version uses 3-letter airline codes: BAW117 instead of BA117, AAL100 instead of AA100. ICAO codes are used in air traffic control, flight planning and aviation operations. They are what you hear on ATC radio. Some systems return ICAO codes natively, and your tracking implementation needs to handle both.

GET https://airlabs.co/api/v9/flight?flight_icao=BAW117&api_key={KEY}

For applications that consume data from operational sources (ADS-B aggregators, ATC feeds, flight planning tools), ICAO codes are often the primary identifier.

3. Aircraft Registration Number (Tail Number)

The painted code on the aircraft itself — N790AN, G-ZBKA, D-AIME. Tail numbers identify the airframe, not the flight. A single airframe operates many flights per day, so looking up by tail number returns the flight that aircraft is currently operating (if any).

GET https://airlabs.co/api/v9/flights?reg_number=N790AN&api_key={KEY}

This identification method is essential for logistics applications (tracking cargo by aircraft), aviation enthusiasts (plane spotting) and MRO systems (linking maintenance records to current operations). See our Aircraft Tail Numbers Database guide for details on tail number formats and lookup patterns.

4. ICAO24 Hex Address (Transponder ID)

A 24-bit hexadecimal identifier broadcast by every aircraft's transponder — like A9D286 or 400936. The hex code is the actual technical identifier ADS-B receivers and tracking systems use to correlate live position data with aircraft records. It is permanent for an aircraft (until it is re-registered) and unique worldwide.

GET https://airlabs.co/api/v9/flights?hex=A9D286&api_key={KEY}

ADS-B-based applications and aviation data pipelines work natively in hex codes. If your data comes from a software-defined radio receiver or an ADS-B aggregator, hex is the primary key.

5. Route and Schedule Search

Sometimes you do not have any flight identifier at all — only the route, the date, and possibly the airline. In this case, you search through the schedule for the matching flight:

GET https://airlabs.co/api/v9/schedules?dep_iata=JFK&arr_iata=LHR&api_key={KEY}

This returns all scheduled flights between the two airports for the current schedule window. Your application then filters by departure time or airline to find the specific flight. This pattern is common when a user describes a flight in natural language ("the JFK to London flight tonight on British Airways") rather than providing a flight number.

The Flight Lifecycle and Which API to Use

A flight passes through several distinct phases between scheduling and landing. Different AirLabs endpoints provide the best data at each phase. Understanding this lifecycle prevents the common bug of querying the wrong endpoint and getting incomplete data.

The most common mistake in tracking implementations is querying the Real-Time Flights API for a flight that has not yet taken off. The flight does not appear because it is not airborne — but it still exists in the schedule and has a known status. A correct implementation falls back to the Schedules or Flight Info endpoint when a flight is not in the live tracking feed.

The opposite mistake is equally common: querying the Flight Info API for a flight that landed two days ago and being surprised that the data is no longer detailed. Historical data is generally outside the operational tracking window. The platform focuses on current and upcoming flights, with the Flight Alert API providing the most granular notifications during active phases.

A Decision Tree for "Which Endpoint Do I Call?"

For implementations that need to handle any input gracefully, the following decision tree maps user input to the right API endpoint:

• User provides a flight number in IATA format (e.g. BA117) → call Flight Info API with flight_iata
• User provides a flight number in ICAO format (e.g. BAW117) → call Flight Info API with flight_icao
• User provides a tail number (e.g. N790AN) → call Real-Time Flights API with reg_number for live position, then Fleets Database for full aircraft details
• User provides an ICAO24 hex code (e.g. A9D286) → call Real-Time Flights API with hex
• User provides a route (origin airport + destination airport) → call Schedules API with dep_iata and arr_iata, then filter results
• User provides a partial name or city (e.g. "Heathrow", "London") → call Name Suggestion API first to resolve the name into a code, then use the code with the appropriate endpoint
• User provides nothing but their location (e.g. "what's flying overhead?") → call Real-Time Flights API with a bbox bounding box around the user's coordinates

This decision tree should live in your application's input layer. Normalize the user input first, route to the correct endpoint, then handle the response. Mixing identification with status retrieval in the same code path is the source of most tracking implementation bugs.

Time Zones, Local Times and the UTC Trap

The single most underestimated source of bugs in flight tracking applications is time zone handling. A flight from JFK to LHR has a departure time in New York time and an arrival time in London time. These are not the same time zone, and the time on the wall when the flight lands is not 6 hours after the time on the wall when it took off — it is 11 hours later.

The AirLabs Flight Info API returns each timestamp in three formats:

{
  "dep_time": "2026-05-29 19:00",
  "dep_time_ts": 1748541600,
  "dep_time_utc": "2026-05-29 23:00",
  "arr_time": "2026-05-30 07:15",
  "arr_time_ts": 1748585700,
  "arr_time_utc": "2026-05-30 06:15"
}

The _ts (Unix timestamp) is unambiguous — it's always the same number of seconds since epoch regardless of where the user is. Use this for any time math: duration calculations, sorting, "time until departure" countdowns.

The _utc field is the same instant expressed in UTC for human reading. Useful for logging and debugging.

The bare field (dep_time, arr_time) is the local airport time — the time displayed on departure boards at that airport. This is what passengers see and what you should display in user interfaces. But never use it for math directly; always convert from the timestamp first.

Combined with the timezone field from the Airports Database (IANA timezone identifiers like America/New_York or Europe/London), you can correctly format any time for any user in any timezone. Most JavaScript and Python date libraries support IANA timezones natively.

Codeshare — When One Flight Is Many Flights

A single physical flight from Miami to San Francisco might be sold under five different flight numbers: BA6984 (British Airways), AA2421 (American Airlines), IB7104 (Iberia), QF3506 (Qantas) and FJ4521 (Fiji Airways). All five passengers board the same plane at gate E4 in Miami, but their boarding passes show different flight numbers.

Looking up any of these five flight numbers should return the same physical flight. The AirLabs API handles this through the cs_* codeshare fields in the response:

{
  "flight_iata": "BA6984",
  "cs_airline_iata": "AA",
  "cs_flight_iata": "AA2421",
  "cs_flight_number": "2421"
}

When the cs_* fields are populated, the flight is a codeshare and the cs_flight_iata identifies the operating carrier's flight number — the one used in the actual flight plan and air traffic control. For tracking and display purposes, you typically want to show both: the marketing number (what the passenger booked) and the operating number (what is actually flying). See our Codeshare Flights guide for the complete pattern.

Diversions, Cancellations and Edge Cases

A production flight tracking implementation must handle the unhappy paths. Three edge cases account for the majority of confusing results:

Diversions. An aircraft scheduled to land at JFK might divert to BWI due to weather, medical emergencies or technical issues. The status field returns diverted and the operational data reflects the actual landing airport, which may differ from the originally scheduled arr_iata. Your tracking display should explicitly highlight diversions so users understand why the destination changed.

Cancellations. A cancelled flight returns status: cancelled and typically does not appear in real-time tracking feeds (because it never operated). Always handle this case before assuming a missing flight means an error. A scheduled flight that does not appear in the Real-Time Flights API may simply have been cancelled.

Delays beyond the schedule window. The Schedules API returns results up to roughly 10 hours ahead. If a flight is delayed beyond that window, or if a user queries a flight scheduled for next week, the data may not yet be available at the same granularity as a flight today. Combine the Schedules API with the Routes Database for forward-looking queries that go beyond the operational window.

Putting It All Together — A Tracking Endpoint Pattern

A robust flight tracking endpoint in your application typically looks like this:

• Normalize input. Detect what the user provided (flight number, tail, hex, route) and validate the format. Reject malformed input early with a clear error message.
• Resolve identifiers. If the user provided a name or partial input, use the Name Suggestion API to resolve it to a structured code.
• Pick the right endpoint using the decision tree above. Use a fallback chain: try the most specific endpoint first, then fall back to broader ones.
• Parse the response defensively. Some fields are nullable. The cs_* fields are present only for codeshares. Handle missing or null fields gracefully.
• Handle the lifecycle phase. A flight in scheduled status has no lat/lng. A flight in landed status has actual times but no live position. Render the UI differently for each phase.
• Cache appropriately. Reference data (airport details, airline names, fleet) changes slowly — cache for hours. Real-time data (position, status) changes constantly — cache for seconds at most.
• Use webhooks for proactive tracking. Instead of polling every minute, subscribe via the Flight Alert API to receive webhook callbacks only when a tracked flight's status, gate or delay actually changes.

Flight Tracking for Developers

If you are building a flight tracking application, the AirLabs API provides every identifier method, every lifecycle phase and every edge case handler described in this guide — through a single, consistent REST interface.

Supported API Features

Our Developer API allows you to create a custom experience for your users and increase the value of your product:

• Flight Information API for status lookup by IATA or ICAO flight code.
• Real-Time Flights API for tracking by tail number, ICAO hex, route or bounding box.
• Schedules API for departure and arrival board data and route-based search.
• Flight Alert API for webhook-based notifications when status changes.
• Flight Delay API for real-time delay data across airports.
• Aircraft Fleets Database for resolving tail numbers to aircraft details.
• Airports Database with IANA timezones for correct time zone handling.
• Airlines Database with carrier information for resolving codeshare partners.
• Routes Database for forward-looking route queries beyond the operational window.
• NearBy API for geo-based searches.
• Name Suggestion API for autocomplete and name-to-code resolution.

You can try it right now without any obligation! Get a free flight API plan and see for yourself that we have exactly the data you need!

If you need more information, don't hesitate to contact us. We are always happy to chat with our customers and are sure to find a customized solution for each request.