Flight Delay API for Travel Insurance Claims
Your travel insurance platform needs to verify whether a customer’s flight was delayed, cancelled, or diverted, and by how much—without manual research. By the end of this guide, you’ll be able to automate claim adjudication using FlightLabs: fetch real-time status, compute delay minutes from scheduled vs. actual/estimated times, corroborate with schedules and historical data, and handle edge cases like cancellations and diversions.
What insurers need from flight data to automate claims
For delay, cancellation, and missed-connection benefits, your system has to confirm three things quickly and reliably:
- What was scheduled: the original departure/arrival times, terminals, and gates.
- What actually happened: status (en-route, landed, cancelled, diverted), actual departure/arrival, and any estimated changes.
- How big the variance was: delay minutes from the airline’s published schedule, with UTC-normalized timestamps to avoid timezone drift.
FlightLabs provides these building blocks via real-time tracking, schedules, historical flights, and delay predictions—all returned as JSON over a simple REST interface authenticated with an API key. You can review the platform at https://www.goflightlabs.com and get started with a 7-day or 50-request trial on the Starter plan at $24.99/mo.
Endpoints that map to the claim workflow
Below is how to align claim adjudication steps to the FlightLabs feature set. Each capability is accessible at the base API host and documented here: Documentation.
| Claim Task | FlightLabs Capability | Use It To | Key Fields You’ll Read |
|---|---|---|---|
| Confirm current status and delay | Real-time Flight Tracking | Check if a flight is en-route, landed, cancelled, or diverted; get actual/estimated times | flight.status, departure.scheduled, departure.actual, arrival.scheduled, arrival.estimated, terminals/gates |
| Validate the published schedule | Flight Schedules | Fetch the airline’s scheduled departure/arrival for a given date | schedules[].departure.scheduled, schedules[].arrival.scheduled, airline, aircraft |
| Corroborate past flights | Flight History | Verify outcomes for completed flights (landed, cancelled, diverted) | Status and actual timestamps (structure aligns with real-time for auditing) |
| Flag likely claims proactively | Flight Delay Predictions | Identify flights at higher risk of delays to notify customers | Predicted delay metrics and confidence (use for alerts, not adjudication) |
Real-time status: the adjudication “source of truth”
In practice, your claim engine will query real-time flight data as soon as a claim is submitted (and optionally on a periodic basis while a flight is in progress). Use this to compute delay minutes and to detect cancellations or diversions.
Sample JSON you’ll receive for a live flight
{
"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
}
}
}
}
Fields that matter for claims:
- flight.status: adjudication branch—examples include en-route, landed, cancelled, diverted.
- departure.scheduled/actual: compute departure delay in minutes.
- arrival.scheduled/estimated (or actual once landed): compute arrival delay in minutes (often used for eligibility).
- terminal/gate: optional but useful for customer support reconciliation.
- All timestamps are ISO 8601; “Z” indicates UTC. Convert to local time only for UI—keep UTC internally for calculations.
Copy-paste cURL for live status
Replace YOUR_API_KEY with your FlightLabs key. This example fetches real-time status; filter parameters vary by implementation and should be added per your query strategy.
curl -G "https://api.goflightlabs.com/real-time" \
--data-urlencode "access_key=YOUR_API_KEY"
Tip: store your API key securely (e.g., environment variables, vault). Never commit it to a repository.
Python example to compute delay minutes
import os
import requests
from datetime import datetime, timezone
API_KEY = os.getenv("FLIGHTLABS_API_KEY", "YOUR_API_KEY")
BASE_URL = "https://api.goflightlabs.com/real-time"
def parse_iso_utc(ts):
# Expecting timestamps like 2024-03-20T10:05:00Z
if not ts:
return None
dt = datetime.fromisoformat(ts.replace("Z", "+00:00"))
return dt.astimezone(timezone.utc)
def minutes_diff(a, b):
if not a or not b:
return None
return int((a - b).total_seconds() // 60)
def get_flight_and_delay():
params = {"access_key": API_KEY}
r = requests.get(BASE_URL, params=params, timeout=20)
r.raise_for_status()
data = r.json()
flight = data.get("data", {}).get("flight", {})
status = flight.get("status")
dep = flight.get("departure", {})
arr = flight.get("arrival", {})
dep_sched = parse_iso_utc(dep.get("scheduled"))
dep_actual = parse_iso_utc(dep.get("actual"))
arr_sched = parse_iso_utc(arr.get("scheduled"))
arr_est = parse_iso_utc(arr.get("estimated")) # or "actual" once landed
departure_delay_min = minutes_diff(dep_actual, dep_sched) if dep_actual and dep_sched else None
arrival_delay_min = minutes_diff(arr_est, arr_sched) if arr_est and arr_sched else None
result = {
"status": status,
"departure_delay_min": departure_delay_min,
"arrival_delay_min": arrival_delay_min,
"dep_terminal": dep.get("terminal"),
"dep_gate": dep.get("gate"),
"arr_terminal": arr.get("terminal"),
"arr_gate": arr.get("gate"),
}
return result
if __name__ == "__main__":
delay_info = get_flight_and_delay()
print(delay_info)
Adjudication logic usually keys off arrival_delay_min because policy language often references arrival delays. For ongoing flights (en-route), arrival.estimated is your best proxy. For completed flights (landed), prefer arrival.actual if available in your data model.
Validate the schedule your customer booked
Many policies compare actual outcomes against the published schedule on the date of travel. Pull the schedule for the route/day to cross-check the customer’s claim details and to normalize time calculations in UTC.
Sample schedule response
{
"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"
}
}
]
}
}
Use schedules[].departure.scheduled and schedules[].arrival.scheduled as the canonical baseline. If you receive multiple schedule entries for code-shares, pick the one matching the claimant’s airline and flight number. For pagination, implement cursors or page parameters as documented to iterate over large schedule sets by date and route.
Corroborate outcomes with history and predict delays for notifications
Historical data is your audit trail after a flight is complete. For a post-travel claim, a single lookup can confirm status (landed, cancelled, diverted) and the final times used to compute benefits. For proactive customer comms, delay predictions help you notify travelers of likely disruptions, but use real-time and history as the basis for actual claim decisions.
When to call which dataset
- Before departure: consult schedules and delay predictions to prime your cache and warn customers.
- During operations: poll real-time to track status changes and refresh estimated times.
- After arrival: query history to lock in final actuals and archive the record for compliance.
Implementation details that save time
Time zones and UTC
- All example timestamps end with “Z” (UTC). Keep everything in UTC internally to avoid DST and locale pitfalls.
- Convert to local time only in the UI layer. Store the original string alongside parsed datetimes for auditability.
Caching and polling strategy for live tracking
- Cache schedule responses per flight/date for 24 hours; they change infrequently.
- For live flights, poll real-time more frequently near departure/arrival (e.g., every 1–2 minutes within ±45 minutes of STD/STA) and back off to every 5–10 minutes mid-flight. Apply conditional requests or ETags if supported.
- De-duplicate updates by comparing timestamps and status; persist the latest record to a claim’s timeline.
Handling cancellations and diversions
- Cancelled: flight.status = "cancelled" should short-circuit delay math. Store departure.scheduled as the baseline and mark the claim as eligible per your policy rules.
- Diverted: treat diversion as special handling. You may compute partial delay to the diversion point and then a separate segment for onward transport if your policy covers it. Persist the status and any terminal/gate changes for audit.
- Unknown or missing times: if actual or estimated times are missing, retry and record “insufficient data.” Fall back to history after the day of operation.
Codeshares
- Match the claim’s airline/flight number. Where codeshares exist, confirm the operating carrier; terminals and gates often follow the operating flight.
- If multiple schedule entries appear, pick the one whose airline.iata matches the submitted carrier code and whose flight number matches the claimant’s ticket.
Data fields to persist per claim
- Identifiers: airline IATA/ICAO, flight number, date of travel, departure and arrival airports (IATA codes).
- Times: scheduled, actual, and estimated for both departure and arrival (UTC).
- Status snapshots: all status transitions (scheduled → active → en-route → landed/cancelled/diverted) with timestamps.
- Operational details: terminal and gate for both ends, aircraft registration if relevant for auditing.
Designing the adjudication flow
1) Ingest the claim
- Inputs: airline + flight number, travel date, origin/destination, claimant’s local time (UI only).
- Normalize: build a UTC “day of operation” window from 00:00Z to 23:59Z to query schedules and real-time.
2) Fetch schedule and baseline times
- Query schedules to obtain departure.scheduled and arrival.scheduled in UTC.
- Cache the schedule keyed by flight/date; associate it with the claim.
3) Check real-time status and compute variance
- If status = "cancelled": set outcome = cancelled; determine benefit per policy without delay math.
- If status = "diverted": flag for manual or special rules; attach known times to the record.
- If status in {"en-route", "landed"}: compute delay minutes using departure.actual vs departure.scheduled and arrival.estimated/actual vs arrival.scheduled.
4) Confirm with history (post-arrival)
- After the flight date, reconcile with history and lock the claim record. Store both the real-time and historical payloads for audit.
5) Payout logic
- Compare arrival delay minutes against the policy threshold (e.g., 3 hours). Round consistently (down or nearest) and document your approach.
- Emit a human-readable summary for the claimant and attach raw JSON to the case for compliance review.
Airport and timezone context when you need it
If your workflow needs local display times or terminal context, you can fetch airport metadata. Here’s a sample structure for John F. Kennedy International Airport (JFK) including timezone and terminals:
{
"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
}
}
}
}
}
Use the timezone field to convert UTC timestamps to the airport’s local time in your UI. Keep UTC as the adjudication reference so the math stays consistent across jurisdictions.
Operational guidance: rate limits, retries, and auditing
- Retries: implement exponential backoff on 429/5xx responses. Record the last successful payload per flight to reduce unnecessary polling.
- Pagination: when requesting multiple schedules for a route or date, iterate with the documented pagination fields and cap page size to keep response times predictable.
- Auditing: persist the full JSON payloads used for each decision, the UTC computation steps for delay minutes, and the user-visible summary. This makes compliance checks straightforward.
Where to build and test
Sign up for an API key and start testing endpoints in minutes. Register here: Register. You can also explore data models and sample queries in the Documentation and manage your keys in the MCP. For an overview of capabilities and pricing tiers, see www.goflightlabs.com.
FAQ
-
Which timestamp should I use for eligibility—departure or arrival delay?
Use arrival delay (arrival.actual or arrival.estimated vs arrival.scheduled) unless your policy explicitly specifies departure delay. Arrival delay is the most common basis for benefits. -
How do I handle flights that are still en-route when a claim is filed?
Compute interim delay using arrival.estimated. Recheck upon landing to finalize the outcome and adjust payout if needed. -
What if the API returns missing actual/estimated times?
Retry with backoff. If still missing, store the status snapshot and consult historical data the next day to finalize actuals. -
How often should I poll real-time data?
Increase frequency near scheduled departure and arrival (1–2 minutes), and reduce mid-flight (5–10 minutes). Cache schedule data and only refresh when the status or timestamps change. -
Can I use delay predictions to auto-approve claims?
Use predictions for proactive notifications and customer experience. For adjudication, rely on real-time status and historical records that reflect actual operations.
Ready to ship delay, cancellation, and diversion adjudication with clean JSON? Get your API key now and start integrating: Register.