AviationService

Flight delay data from FAA and Eurocontrol

The AviationService provides APIs for accessing current airport delay alerts from the FAA (Federal Aviation Administration) and Eurocontrol.

Base Path

/api/aviation/v1

ListAirportDelays

Retrieves current airport delay alerts with filtering by region and severity.

Endpoint: GET /api/aviation/v1/list-airport-delays

Request Parameters

page_size · int32

Maximum items per page (1-100)

cursor · string

Cursor for next page

region · AirportRegion

Optional region filter: AIRPORT_REGION_AMERICAS, AIRPORT_REGION_EUROPE, AIRPORT_REGION_APAC, AIRPORT_REGION_MENA, or AIRPORT_REGION_AFRICA

min_severity · FlightDelaySeverity

Optional minimum severity filter: FLIGHT_DELAY_SEVERITY_NORMAL, FLIGHT_DELAY_SEVERITY_MINOR, FLIGHT_DELAY_SEVERITY_MODERATE, FLIGHT_DELAY_SEVERITY_MAJOR, or FLIGHT_DELAY_SEVERITY_SEVERE

Response

alerts · AirportDelayAlert[]

The list of airport delay alerts

Show AirportDelayAlert

id · string · required

Unique alert identifier

iata · string

IATA airport code (e.g., “JFK”)

icao · string

ICAO airport code (e.g., “KJFK”)

name · string

Airport name

city · string

City where the airport is located

country · string

Country code (ISO 3166-1 alpha-2)

location · GeoCoordinates

Airport location

region · AirportRegion

Geographic region

delay_type · FlightDelayType

Type of delay: FLIGHT_DELAY_TYPE_GROUND_STOP, FLIGHT_DELAY_TYPE_GROUND_DELAY, FLIGHT_DELAY_TYPE_DEPARTURE_DELAY, FLIGHT_DELAY_TYPE_ARRIVAL_DELAY, FLIGHT_DELAY_TYPE_GENERAL, or FLIGHT_DELAY_TYPE_CLOSURE

severity · FlightDelaySeverity

Delay severity

avg_delay_minutes · int32

Average delay in minutes

delayed_flights_pct · double

Percentage of delayed flights

cancelled_flights · int32

Number of cancelled flights

total_flights · int32

Total flights scheduled

reason · string

Human-readable reason for delays

source · FlightDelaySource

Data source: FLIGHT_DELAY_SOURCE_FAA, FLIGHT_DELAY_SOURCE_EUROCONTROL, or FLIGHT_DELAY_SOURCE_COMPUTED

updated_at · int64

Last data update time, as Unix epoch milliseconds

pagination · PaginationResponse

Pagination metadata

Example Request

curl "https://your-domain.com/api/aviation/v1/list-airport-delays?region=AIRPORT_REGION_AMERICAS&min_severity=FLIGHT_DELAY_SEVERITY_MODERATE&page_size=50"

Example Response

{
  "alerts": [
    {
      "id": "jfk-delay-20240301",
      "iata": "JFK",
      "icao": "KJFK",
      "name": "John F. Kennedy International Airport",
      "city": "New York",
      "country": "US",
      "location": {
        "latitude": 40.6413,
        "longitude": -73.7781
      },
      "region": "AIRPORT_REGION_AMERICAS",
      "delay_type": "FLIGHT_DELAY_TYPE_DEPARTURE_DELAY",
      "severity": "FLIGHT_DELAY_SEVERITY_MODERATE",
      "avg_delay_minutes": 32,
      "delayed_flights_pct": 68.5,
      "cancelled_flights": 12,
      "total_flights": 287,
      "reason": "Weather: Low visibility and strong winds",
      "source": "FLIGHT_DELAY_SOURCE_FAA",
      "updated_at": 1709251200000
    },
    {
      "id": "ord-delay-20240301",
      "iata": "ORD",
      "icao": "KORD",
      "name": "Chicago O'Hare International Airport",
      "city": "Chicago",
      "country": "US",
      "location": {
        "latitude": 41.9742,
        "longitude": -87.9073
      },
      "region": "AIRPORT_REGION_AMERICAS",
      "delay_type": "FLIGHT_DELAY_TYPE_GROUND_DELAY",
      "severity": "FLIGHT_DELAY_SEVERITY_MAJOR",
      "avg_delay_minutes": 58,
      "delayed_flights_pct": 82.3,
      "cancelled_flights": 34,
      "total_flights": 412,
      "reason": "Snow and ice accumulation on runways",
      "source": "FLIGHT_DELAY_SOURCE_FAA",
      "updated_at": 1709251800000
    }
  ],
  "pagination": {
    "cursor": "eyJvZmZzZXQiOjUwfQ==",
    "has_more": true
  }
}

Delay Severity Levels

The FlightDelaySeverity enum provides standardized severity classifications:

• NORMAL: Normal operations with no delays
• MINOR: Minor delays under 15 minutes
• MODERATE: Moderate delays 15-45 minutes
• MAJOR: Major delays 45-90 minutes
• SEVERE: Severe delays over 90 minutes

Delay Types

The FlightDelayType enum classifies different types of delays:

• GROUND_STOP: No departures or arrivals permitted
• GROUND_DELAY: Ground delay program in effect
• DEPARTURE_DELAY: Delays affecting departing flights
• ARRIVAL_DELAY: Delays affecting arriving flights
• GENERAL: General delay condition
• CLOSURE: Airport or airspace closure