openapi: 3.1.0 info: title: AviationService API version: 1.0.0 paths: /api/aviation/v1/list-airport-delays: get: tags: - AviationService summary: ListAirportDelays description: ListAirportDelays retrieves current airport delay alerts. operationId: ListAirportDelays parameters: - name: page_size in: query description: Maximum items per page (1-100). required: false schema: type: integer format: int32 - name: cursor in: query description: Cursor for next page. required: false schema: type: string - name: region in: query description: Optional region filter. required: false schema: type: string - name: min_severity in: query description: Optional minimum severity filter. required: false schema: type: string responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/ListAirportDelaysResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: Error: type: object properties: message: type: string description: Error message (e.g., 'user not found', 'database connection failed') description: Error is returned when a handler encounters an error. It contains a simple error message that the developer can customize. FieldViolation: type: object properties: field: type: string description: The field path that failed validation (e.g., 'user.email' for nested fields). For header validation, this will be the header name (e.g., 'X-API-Key') description: type: string description: Human-readable description of the validation violation (e.g., 'must be a valid email address', 'required field missing') required: - field - description description: FieldViolation describes a single validation error for a specific field. ValidationError: type: object properties: violations: type: array items: $ref: '#/components/schemas/FieldViolation' description: List of validation violations required: - violations description: ValidationError is returned when request validation fails. It contains a list of field violations describing what went wrong. ListAirportDelaysRequest: type: object properties: pageSize: type: integer format: int32 description: Maximum items per page (1-100). cursor: type: string description: Cursor for next page. region: type: string enum: - AIRPORT_REGION_UNSPECIFIED - AIRPORT_REGION_AMERICAS - AIRPORT_REGION_EUROPE - AIRPORT_REGION_APAC - AIRPORT_REGION_MENA - AIRPORT_REGION_AFRICA description: AirportRegion represents the geographic region of an airport. minSeverity: type: string enum: - FLIGHT_DELAY_SEVERITY_UNSPECIFIED - FLIGHT_DELAY_SEVERITY_NORMAL - FLIGHT_DELAY_SEVERITY_MINOR - FLIGHT_DELAY_SEVERITY_MODERATE - FLIGHT_DELAY_SEVERITY_MAJOR - FLIGHT_DELAY_SEVERITY_SEVERE description: |- FlightDelaySeverity represents the severity of flight delays at an airport. Maps to TS union: 'normal' | 'minor' | 'moderate' | 'major' | 'severe'. description: ListAirportDelaysRequest specifies filters for retrieving airport delay alerts. ListAirportDelaysResponse: type: object properties: alerts: type: array items: $ref: '#/components/schemas/AirportDelayAlert' pagination: $ref: '#/components/schemas/PaginationResponse' description: ListAirportDelaysResponse contains airport delay alerts matching the request. AirportDelayAlert: type: object properties: id: type: string minLength: 1 description: Unique alert identifier. iata: type: string description: IATA airport code (e.g., "JFK"). icao: type: string description: ICAO airport code (e.g., "KJFK"). name: type: string description: Airport name. city: type: string description: City where the airport is located. country: type: string description: Country code (ISO 3166-1 alpha-2). location: $ref: '#/components/schemas/GeoCoordinates' region: type: string enum: - AIRPORT_REGION_UNSPECIFIED - AIRPORT_REGION_AMERICAS - AIRPORT_REGION_EUROPE - AIRPORT_REGION_APAC - AIRPORT_REGION_MENA - AIRPORT_REGION_AFRICA description: AirportRegion represents the geographic region of an airport. delayType: type: string enum: - FLIGHT_DELAY_TYPE_UNSPECIFIED - FLIGHT_DELAY_TYPE_GROUND_STOP - FLIGHT_DELAY_TYPE_GROUND_DELAY - FLIGHT_DELAY_TYPE_DEPARTURE_DELAY - FLIGHT_DELAY_TYPE_ARRIVAL_DELAY - FLIGHT_DELAY_TYPE_GENERAL description: FlightDelayType represents the type of flight delay. severity: type: string enum: - FLIGHT_DELAY_SEVERITY_UNSPECIFIED - FLIGHT_DELAY_SEVERITY_NORMAL - FLIGHT_DELAY_SEVERITY_MINOR - FLIGHT_DELAY_SEVERITY_MODERATE - FLIGHT_DELAY_SEVERITY_MAJOR - FLIGHT_DELAY_SEVERITY_SEVERE description: |- FlightDelaySeverity represents the severity of flight delays at an airport. Maps to TS union: 'normal' | 'minor' | 'moderate' | 'major' | 'severe'. avgDelayMinutes: type: integer format: int32 description: Average delay in minutes. delayedFlightsPct: type: number format: double description: Percentage of delayed flights. cancelledFlights: type: integer format: int32 description: Number of cancelled flights. totalFlights: type: integer format: int32 description: Total flights scheduled. reason: type: string description: Human-readable reason for delays. source: type: string enum: - FLIGHT_DELAY_SOURCE_UNSPECIFIED - FLIGHT_DELAY_SOURCE_FAA - FLIGHT_DELAY_SOURCE_EUROCONTROL - FLIGHT_DELAY_SOURCE_COMPUTED description: FlightDelaySource represents the source of delay data. updatedAt: type: integer format: int64 description: 'Last data update time, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript' required: - id description: |- AirportDelayAlert represents a flight delay advisory at an airport. Sourced from FAA and Eurocontrol. GeoCoordinates: type: object properties: latitude: type: number maximum: 90 minimum: -90 format: double description: Latitude in decimal degrees (-90 to 90). longitude: type: number maximum: 180 minimum: -180 format: double description: Longitude in decimal degrees (-180 to 180). description: GeoCoordinates represents a geographic location using WGS84 coordinates. PaginationResponse: type: object properties: nextCursor: type: string description: Cursor for fetching the next page. Empty string indicates no more pages. totalCount: type: integer format: int32 description: Total count of items matching the query, if known. Zero if the total is unknown. description: PaginationResponse contains pagination metadata returned alongside list results.