Search flights
curl -X GET "http://localhost:3000/v1/flight/search?iata=UA123&icao=UAL123&date=2024-03-20&timezone=America/Los_Angeles" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
Search for flights by identifier and optional date. Returns lightweight flight summaries for selection.
Query parameters
IATA flight numberExample: UA123
ICAO flight numberExample: UAL123
Flight date (ISO format). Filters flights by date if providedExample: 2024-03-20
The timezone from which the request is being madeExample: America/Los_Angeles
Response
Array of flight candidatesShow Flight candidate object
FlightAware flight ID for fetching full details
Flight identifier (e.g., “AC113”)
Origin airport information
Destination airport information (same structure as origin)
Scheduled departure time (ISO 8601)
Scheduled takeoff time (ISO 8601)
Flight status description
Response example
{
"flights": [
{
"faFlightId": "UAL123-1710936000-airline-0123",
"ident": "UA123",
"origin": {
"code": "KLAX",
"codeIata": "LAX",
"codeIcao": "KLAX",
"name": "Los Angeles International Airport",
"city": "Los Angeles"
},
"destination": {
"code": "KJFK",
"codeIata": "JFK",
"codeIcao": "KJFK",
"name": "John F. Kennedy International Airport",
"city": "New York"
},
"scheduledOut": "2024-03-20T08:00:00Z",
"scheduledOff": "2024-03-20T08:15:00Z",
"status": "Scheduled",
"airline": {
"name": "United Airlines",
"iata": "UA",
"icao": "UAL",
"image": "https://cdn.aero.com/airlines/UA.png"
}
}
],
"count": 1
}
Get flight details
curl -X GET "http://localhost:3000/v1/flight?iata=UA123&icao=UAL123&timezone=America/Los_Angeles&faFlightId=UAL123-1710936000-airline-0123" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
Get detailed information about a specific flight including real-time tracking data. Use faFlightId to fetch a specific flight after searching.
Query parameters
IATA flight numberExample: UA123
ICAO flight numberExample: UAL123
Flight date (ISO format). Defaults to current date if not providedExample: 2024-03-20
The timezone from which the request is being madeExample: America/Los_Angeles
Force update the flight data (used to refresh the flight data)
FlightAware flight ID to fetch a specific flight. Use this after searching for flights to get details of a selected flight.
Response
Aircraft details
Aircraft registration/tail number
Whether aircraft is a cargo freighter
Departure information
Airport details including IATA, ICAO, name, timezone, and location
Scheduled time in UTC and local timezone
Arrival information (same structure as departure)
Whether this is a cargo flight
Distance in multiple units (meter, km, mile, nm, feet)
Comprehensive FlightAware data including status, delays, route, codeshares, and more
Bookings associated with this flight
Response example
{
"id": "flight_abc123",
"flightNo": "UA123",
"callSign": "UAL123",
"aircraft": {
"registration": "N12345",
"model": "Boeing 737-900",
"image": "https://cdn.aero.com/aircraft/N12345.jpg",
"age": "8"
},
"airline": {
"name": "United Airlines",
"iata": "UA",
"icao": "UAL",
"image": "https://cdn.aero.com/airlines/UA.png"
},
"departure": {
"airport": {
"iata": "LAX",
"icao": "KLAX",
"name": "Los Angeles International Airport",
"timeZone": "America/Los_Angeles",
"location": {
"lat": 33.9416,
"lon": -118.4085
}
},
"scheduledTime": {
"utc": "2024-03-20T08:00:00Z",
"local": "2024-03-20T00:00:00-08:00"
},
"terminal": "7",
"gate": "75A"
},
"arrival": {
"airport": {
"iata": "JFK",
"icao": "KJFK",
"name": "John F. Kennedy International Airport"
},
"scheduledTime": {
"utc": "2024-03-20T16:30:00Z",
"local": "2024-03-20T12:30:00-04:00"
}
},
"cargo": false,
"greatCircleDistance": {
"km": "3974",
"mile": "2469",
"nm": "2145"
},
"date": "2024-03-20T08:00:00Z"
}
Get flight track/path
curl -X GET "http://localhost:3000/v1/flight/track?iata=UA123&icao=UAL123&date=2024-03-20&timezone=America/Los_Angeles" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
Get the flight path with all position data points for a specific flight
Query parameters
IATA flight numberExample: UA123
ICAO flight numberExample: UAL123
Flight date (ISO format). Defaults to current date if not providedExample: 2024-03-20
The timezone from which the request is being madeExample: America/Los_Angeles or IST
Response
Distance flown in miles as of the latest position pointExample: 2450
Array of flight positions
FlightAware flight ID for this position
Aircraft altitude in hundreds of feetExample: 350 (35,000 feet)
Altitude change indicator: C (climbing), D (descending), - (level)
Groundspeed in knotsExample: 450
Aircraft heading in degrees (0-360)Example: 270
Latitude positionExample: 40.7128
Longitude positionExample: -74.0060
Time that position was receivedExample: 2024-03-20T14:30:00Z
Update type: P (projected), O (oceanic), Z (radar), A (ADS-B), M (multilateration), D (datalink), X (surface), S (space-based), V (virtual)
Response example
{
"actual_distance": 2450,
"positions": [
{
"altitude": 350,
"altitude_change": "C",
"groundspeed": 450,
"heading": 270,
"latitude": 40.7128,
"longitude": -74.0060,
"timestamp": "2024-03-20T14:30:00Z",
"update_type": "A"
},
{
"altitude": 355,
"altitude_change": "C",
"groundspeed": 455,
"heading": 271,
"latitude": 40.8128,
"longitude": -74.1060,
"timestamp": "2024-03-20T14:31:00Z",
"update_type": "A"
}
]
}
Error responses
Invalid request parameters or flight not found{
"message": "Flight not found"
}
User is not authenticated{
"message": "Unauthorized"
}
Internal server error{
"message": "Internal server error"
}