How to Get Flight Status by Flight Number with an API
You need to show a traveler or dispatcher the live status of a specific flight when they enter a flight number (like AA123). By the end of this guide, you’ll query FlightLabs for a flight’s status, departure and arrival times, terminals and gates, and position data, and render a clean status line in your app.
What you will build
We’ll build a simple lookup that:
- Accepts a flight number (IATA-style like AA123, or airline + number).
- Fetches live status from FlightLabs.
- Outputs the status, UTC timestamps, terminals, gates, and—if available—en‑route position.
We’ll focus on live tracking first and show where to add schedules and history to handle departures that haven’t left yet or flights that already landed. The live examples below use the same fields you’ll parse in production.
Which FlightLabs endpoints to use and when
You can cover the full “status by flight number” use case with a small set of endpoints. Here’s a quick comparison to help you decide which one to call first and how to fall back:
| Endpoint (Docs) | Primary purpose | Key fields (see examples below) | Typical use in status lookup |
|---|---|---|---|
| Real-time Flight Tracking /real-time |
Live in-air and gate events | flight.status, departure.scheduled/actual/terminal/gate, arrival.scheduled/estimated/terminal/gate, position | First call when you want “what’s happening now” |
| Detailed Flight Info by Flight Number /flight-info-by-flight-number |
Single-flight lookups keyed by number | Flight identification and operational details | Direct lookup if you only have a flight number |
| Flight Schedules /flights-schedules |
Planned times and terminals | schedules[].departure/arrival.scheduled, terminals, aircraft, airline | Fallback if a flight hasn’t gone live yet |
| Flight History /flights-history |
Completed flights and past days | Historical operations to inform ETAs or analytics | Use once a flight is completed or for context |
| Airport Information Airport reference |
Airport metadata and timezone | timezone, terminals, runways, weather | Convert UTC to local time using airport timezones |
You’ll find all categories on goflightlabs.com and can test them via the MCP. To integrate, get an API key and start with real-time, then add schedule and history fallbacks as needed.
Get an API key and test quickly
Sign up for FlightLabs to obtain an API key. The Starter plan is $24.99 per month and includes a 7‑day or 50‑request trial so you can prototype before committing. Create your key here: Register. For reference details and usage patterns, read the Documentation.
Step 1 — Call real-time and read the fields that matter
To retrieve live status, make a request to the Real-time Flight Tracking endpoint. The example below demonstrates a simple call; authenticate with your API key. You can filter in your code by the flight number the user entered.
curl -s "https://api.goflightlabs.com/real-time?api_key=YOUR_API_KEY"
Here’s an official example response structure and fields you’ll parse. We’ll use these exact keys in the code sample.
{
"success": true,
"data": {
"flight": {
"iata": "AA123",
"icao": "AAL123",
"number": "123",
"status": "en-route",
"departure": {
"airport": "JFK",
"scheduled": "2024-03-20T10:00:00Z",
"actual": "2024-03-20T10:05:00Z",
"terminal": "8",
"gate": "B12"
},
"arrival": {
"airport": "LAX",
"scheduled": "2024-03-20T13:15:00Z",
"estimated": "2024-03-20T13:20:00Z",
"terminal": "4",
"gate": "45A"
},
"position": {
"latitude": 39.8729,
"longitude": -98.7372,
"altitude": 35000,
"speed": 495,
"heading": 270
}
}
}
}
Field highlights you’ll render:
- flight.status — Core status string to display (e.g., en‑route). Handle any non-en‑route values by showing a clear state to users.
- departure.scheduled and departure.actual — ISO 8601 in UTC (Z). Use these to compute gate delay at origin.
- arrival.scheduled and arrival.estimated — Scheduled vs. current ETA in UTC.
- departure.terminal/gate and arrival.terminal/gate — Display on departure/arrival cards. These may be missing for some airports/flights.
- position — Live latitude/longitude, altitude (feet), speed (knots), and heading (degrees). Useful for maps and progress bars.
Step 2 — Parse the response and filter by the flight number
Below is a minimal JavaScript example that calls the same endpoint, filters by an expected IATA flight number (AA123), and prints a normalized object for your UI. In production, supply the user’s input for the target flight number and add error states for “not found” or “not live yet.”
async function fetchFlightStatusByNumber(targetIata) {
const url = "https://api.goflightlabs.com/real-time?api_key=YOUR_API_KEY";
const res = await fetch(url);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const json = await res.json();
// The official sample shows a single "data.flight". In practice you may need
// to adapt this if the API returns multiple flights; filter as needed.
const f = json && json.data && json.data.flight ? json.data.flight : null;
if (!f || f.iata !== targetIata) {
return { found: false, message: "Flight not available in real-time data." };
}
return {
found: true,
iata: f.iata,
icao: f.icao,
number: f.number,
status: f.status,
departure: {
airport: f.departure.airport,
scheduled_utc: f.departure.scheduled,
actual_utc: f.departure.actual,
terminal: f.departure.terminal || null,
gate: f.departure.gate || null
},
arrival: {
airport: f.arrival.airport,
scheduled_utc: f.arrival.scheduled,
estimated_utc: f.arrival.estimated,
terminal: f.arrival.terminal || null,
gate: f.arrival.gate || null
},
position: f.position || null
};
}
// Example usage:
fetchFlightStatusByNumber("AA123")
.then(console.log)
.catch(console.error);
Notes for your UI:
- Display UTC times with a clear “UTC” label, or convert to local time zones using airport metadata if you already have it cached.
- If a terminal or gate is missing, hide that row or show a subtle “TBD.”
- When a position is available, show a map or a progress indicator; otherwise, omit the map affordance.
Step 3 — Time zones, UTC conversion, and airport metadata
Flight event times in the real-time example are in UTC (notice the Z). For user-facing boards, you’ll often need local time. You can obtain the timezone per airport from FlightLabs and convert UTC to the local wall clock time in your frontend or backend. Here’s an airport reference sample with timezone:
{
"success": true,
"data": {
"airport": {
"iata": "JFK",
"icao": "KJFK",
"name": "John F. Kennedy International Airport",
"location": {
"lat": 40.6413,
"lon": -73.7781,
"city": "New York",
"country": "United States"
},
"timezone": "America/New_York",
"terminals": [
"1",
"2",
"4",
"5",
"7",
"8"
],
"runways": [
{
"length_ft": 14511,
"width_ft": 150,
"surface": "concrete",
"designator": "13L/31R"
}
],
"weather": {
"temp_c": 22,
"visibility_km": 10,
"wind": {
"speed_kts": 8,
"direction_deg": 180
}
}
}
}
}
Implementation tips:
- Treat API timestamps as authoritative UTC. Convert to local via the airport timezone string when rendering.
- Keep a small cache of airport IATA → timezone to avoid extra lookups on every flight refresh.
- Handle DST and locale formatting in your client (e.g., Intl.DateTimeFormat in JavaScript) rather than hard-coding offsets.
Step 4 — Add schedules and history as fallbacks
When a user searches outside the live window (far before departure or long after arrival), switch to schedules or history. This gives you planned times, terminals, and aircraft even if real-time isn’t available.
Official schedules example:
{
"success": true,
"data": {
"schedules": [
{
"flight_number": "UA456",
"departure": {
"airport": "SFO",
"scheduled": "2024-03-20T08:00:00Z",
"terminal": "3"
},
"arrival": {
"airport": "ORD",
"scheduled": "2024-03-20T14:15:00Z",
"terminal": "1"
},
"aircraft": {
"type": "Boeing 787-9",
"registration": "N123UA"
},
"airline": {
"name": "United Airlines",
"iata": "UA"
}
}
]
}
}
How to use it alongside real-time:
- If real-time data is not found for a given flight number and date, query schedules to show planned times and terminals.
- Once a flight is complete or for reporting, query flight history to retrieve actuals for past operations.
- Plan for pagination when iterating schedules; use the documented page/limit parameters to avoid over-fetching. If you don’t need more than the first page for a specific flight number and day, keep the request narrow and cache the result for the session.
Live tracking refresh, caching, and resiliency
Efficient polling is important for live UIs:
- Refresh frequency: 30–60 seconds is a reasonable default for dashboards. For mobile, update on app foreground or user request.
- Caching: Cache the latest payload for 5–15 seconds in your backend to reduce duplicate calls when multiple clients watch the same flight.
- Backoff: If the API returns an error or your rate is high, back off to a 60–120 second interval automatically.
- Idempotent UI: Update only the fields that changed (e.g., ETA or gate) to reduce UI flicker.
Operational states to support:
- Pre-departure: Show scheduled time and gate. Actual may be missing until pushback.
- En‑route: Show ETA and position if available.
- Post‑arrival: Show actual arrival time and gate. Hide the map.
- Exceptions: Treat the status field as the source of truth. If the status indicates a non‑normal state, surface a clear label and avoid making assumptions about times.
Putting it all together in your app
Search logic
- User submits a flight number (e.g., AA123) and an optional date.
- Call real-time. If the flight matches, render status, terminals/gates, and times immediately.
- If not found, query detailed flight info by number (direct lookup). If still not available, fall back to schedules for the planned leg.
- Optionally, check history for recently completed flights (e.g., if the user searched a flight that landed hours ago).
Presentation
- Show UTC times prominently or convert to local using the airport timezone.
- Label changes clearly: “Gate changed to B12,” “Departure delayed 5m vs scheduled.”
- Only display maps when position is present.
You can explore endpoints and payloads interactively in the MCP and refer back to goflightlabs.com for product context.
Troubleshooting and edge cases
- Missing gates or terminals: Not all airports publish them consistently. Keep these fields optional in your UI.
- Date boundaries: Overnight or long-haul flights can depart one day and arrive the next. Keep both UTC and local in your model to avoid off‑by‑one errors in local calendars.
- Multiple legs with similar numbers: If your app supports dates, constrain your query to the intended operational day before choosing a record to display.
- API availability: Surface a “Data temporarily unavailable” state rather than empty results when the network is down or a call fails.
Security and deployment notes
- Do not ship your API key in public clients. Route requests through your backend and secure environment variables.
- Implement a small normalization layer to keep your UI stable if fields are added over time.
- Log the raw JSON for a sampling of flights in non‑PII storage to debug production issues without re‑calling the API.
FAQ
-
How do I look up a flight directly by its number?
Use the detailed flight info by flight number endpoint to query with the number you have. If you need to combine live status, call real-time first and fall back to the detailed endpoint. See the Documentation for the exact request format. -
Are times in local time or UTC?
The examples here show ISO 8601 timestamps in UTC (Z). Convert to local using each airport’s timezone field from the airport reference data when rendering user-facing times. -
How often should I poll for live status?
30–60 seconds is a good default for dashboards. Add backoff on errors or high load, and cache the last successful response for a short period to prevent duplicate calls. -
What if a flight isn’t returned by real-time?
It may be outside the active window. Query the detailed flight info by number and the schedules endpoint for planned times, or the history endpoint if it already landed. -
How do I get started and test without commitment?
The Starter plan is $24.99/month and includes a 7‑day or 50‑request trial so you can prototype quickly. Create your key here: Register.
Ready to ship your flight status lookup? Create your key in minutes and start integrating today: Register. Explore endpoints and payloads in the Documentation and test calls in the MCP. Visit goflightlabs.com for product details and integration patterns.