eliott/worldmonitor
1
0
Fork 0
mirror of https://github.com/koala73/worldmonitor.git synced 2026-04-26 01:24:59 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
048bb8bb525393dc4a9c1998b9877c1f8cc8c011
worldmonitor/docs/api/AviationService.openapi.yaml
Elie Habib d01469ba9c feat(aviation): add SearchGoogleFlights and SearchGoogleDates RPCs (#2446) 
* feat(aviation): add SearchGoogleFlights and SearchGoogleDates RPCs

Port Google Flights internal API from fli Python library as two new
aviation service RPCs routed through the Railway relay.

- Proto: SearchGoogleFlights and SearchGoogleDates messages and RPCs
- Relay: handleGoogleFlightsSearch and handleGoogleFlightsDates handlers
  with JSONP parsing, 61-day chunking for date ranges, cabin/stops/sort mappers
- Server handlers: forward params to relay google-flights endpoints
- gateway.ts: no-store for flights, medium cache for dates

* feat(mcp): expose search_flights and search_flight_prices_by_date tools

* test(mcp): update tool count to 24 after adding search_flights and search_flight_prices_by_date

* fix(aviation): address PR review issues in Google Flights RPCs

P1: airline filtering — use gfParseAirlines() in relay (handles comma-joined
  string from codegen) and parseStringArray() in server handlers

P1: partial chunk failure now sets degraded: true instead of silently
  returning incomplete data as success; relay includes partial: true flag

P2: round-trip date search validates trip_duration > 0 before proceeding;
  returns 400 when is_round_trip=true and duration is absent/zero

P2: relay mappers accept user-friendly aliases ('0'/'1' for max_stops,
  'price'/'departure' for sort_by) alongside symbolic enum values;
  MCP tool docs updated to match

* fix(aviation): use cachedFetchJson in searchGoogleDates for stampede protection

Medium cache tier (10 min) requires Redis-level coalescing to prevent
concurrent requests from all hitting the relay before cache warms.
Cache key includes all request params (sorted airlines for stable keys).

* fix(aviation): always use getAll() for airlines in relay; add multi-airline tests

The OR short-circuit (get() || getAll()) meant get() returned the first
airline value (truthy), so getAll() never ran and only one airline was
forwarded to Google. Fix: unconditionally use getAll().

Tests cover: multi-airline repeated params, single airline, empty array,
comma-joined string from codegen, partial degraded flag propagation.
2026-03-28 23:07:18 +04:00

1693 lines
70 KiB
YAML
Raw Blame History

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'
/api/aviation/v1/get-airport-ops-summary:
get:
tags:
- AviationService
summary: GetAirportOpsSummary
description: GetAirportOpsSummary returns operational health metrics for watched airports.
operationId: GetAirportOpsSummary
parameters:
- name: airports
in: query
description: IATA airport codes to query (e.g., ["IST", "ESB", "LHR"]).
required: false
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetAirportOpsSummaryResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/aviation/v1/list-airport-flights:
get:
tags:
- AviationService
summary: ListAirportFlights
description: ListAirportFlights retrieves recent flights at a specific airport.
operationId: ListAirportFlights
parameters:
- name: airport
in: query
description: IATA airport code (e.g., "IST").
required: false
schema:
type: string
- name: direction
in: query
description: Direction filter.
required: false
schema:
type: string
- name: limit
in: query
description: Maximum number of flights to return (1-100).
required: false
schema:
type: integer
format: int32
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListAirportFlightsResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/aviation/v1/get-carrier-ops:
get:
tags:
- AviationService
summary: GetCarrierOps
description: GetCarrierOps returns delay and cancellation metrics grouped by carrier.
operationId: GetCarrierOps
parameters:
- name: airports
in: query
description: IATA airport codes to aggregate carrier metrics from.
required: false
schema:
type: string
- name: min_flights
in: query
description: 'Minimum number of flights required to include a carrier (default: 1).'
required: false
schema:
type: integer
format: int32
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetCarrierOpsResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/aviation/v1/get-flight-status:
get:
tags:
- AviationService
summary: GetFlightStatus
description: GetFlightStatus looks up the current status of a specific flight.
operationId: GetFlightStatus
parameters:
- name: flight_number
in: query
description: IATA flight number (e.g., "TK1952").
required: false
schema:
type: string
- name: date
in: query
description: Departure date in ISO 8601 format (e.g., "2026-03-05").
required: false
schema:
type: string
- name: origin
in: query
description: Optional origin airport IATA code to disambiguate.
required: false
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetFlightStatusResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/aviation/v1/track-aircraft:
get:
tags:
- AviationService
summary: TrackAircraft
description: TrackAircraft retrieves live position stream for a specific aircraft hex.
operationId: TrackAircraft
parameters:
- name: icao24
in: query
description: ICAO 24-bit transponder address (hex, e.g., "4b1805").
required: false
schema:
type: string
- name: callsign
in: query
description: ATC callsign (e.g., "THY7CX").
required: false
schema:
type: string
- name: sw_lat
in: query
description: Optional bounding box south-west latitude.
required: false
schema:
type: number
format: double
- name: sw_lon
in: query
description: Optional bounding box south-west longitude.
required: false
schema:
type: number
format: double
- name: ne_lat
in: query
description: Optional bounding box north-east latitude.
required: false
schema:
type: number
format: double
- name: ne_lon
in: query
description: Optional bounding box north-east longitude.
required: false
schema:
type: number
format: double
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/TrackAircraftResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/aviation/v1/get-youtube-live-stream-info:
get:
tags:
- AviationService
summary: GetYoutubeLiveStreamInfo
description: GetYoutubeLiveStreamInfo retrieves information about a YouTube live stream (status, title, etc).
operationId: GetYoutubeLiveStreamInfo
parameters:
- name: channel
in: query
description: YouTube channel handle or ID.
required: false
schema:
type: string
- name: video_id
in: query
description: Specific video ID to check.
required: false
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetYoutubeLiveStreamInfoResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/aviation/v1/search-flight-prices:
get:
tags:
- AviationService
summary: SearchFlightPrices
description: SearchFlightPrices searches for flight price offers on a route.
operationId: SearchFlightPrices
parameters:
- name: origin
in: query
description: Origin airport IATA code.
required: false
schema:
type: string
- name: destination
in: query
description: Destination airport IATA code.
required: false
schema:
type: string
- name: departure_date
in: query
description: Outbound departure date (ISO 8601).
required: false
schema:
type: string
- name: return_date
in: query
description: Return date (ISO 8601), empty for one-way.
required: false
schema:
type: string
- name: adults
in: query
description: Number of adult passengers (1-9).
required: false
schema:
type: integer
format: int32
- name: cabin
in: query
description: Desired cabin class.
required: false
schema:
type: string
- name: nonstop_only
in: query
description: Whether to restrict to nonstop flights only.
required: false
schema:
type: boolean
- name: max_results
in: query
description: Maximum number of quotes to return (1-50).
required: false
schema:
type: integer
format: int32
- name: currency
in: query
description: ISO 4217 currency code for prices (e.g., "usd", "eur", "try").
required: false
schema:
type: string
- name: market
in: query
description: Market/locale code (e.g., "us", "tr").
required: false
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/SearchFlightPricesResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/aviation/v1/list-aviation-news:
get:
tags:
- AviationService
summary: ListAviationNews
description: ListAviationNews retrieves filtered aviation news articles.
operationId: ListAviationNews
parameters:
- name: entities
in: query
description: Entities to filter by (airline names, airport codes, route strings).
required: false
schema:
type: string
- name: window_hours
in: query
description: Time window in hours to look back (1-168).
required: false
schema:
type: integer
format: int32
- name: max_items
in: query
description: Maximum number of news items to return (1-50).
required: false
schema:
type: integer
format: int32
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListAviationNewsResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/aviation/v1/search-google-flights:
get:
tags:
- AviationService
summary: SearchGoogleFlights
description: SearchGoogleFlights searches Google Flights for available itineraries on a specific date.
operationId: SearchGoogleFlights
parameters:
- name: origin
in: query
description: Departure airport IATA code (e.g. "JFK").
required: false
schema:
type: string
- name: destination
in: query
description: Arrival airport IATA code (e.g. "LHR").
required: false
schema:
type: string
- name: departure_date
in: query
description: Departure date in YYYY-MM-DD format.
required: false
schema:
type: string
- name: return_date
in: query
description: Return date in YYYY-MM-DD format; omit for one-way.
required: false
schema:
type: string
- name: cabin_class
in: query
description: 'Cabin class: ECONOMY, PREMIUM_ECONOMY, BUSINESS, or FIRST.'
required: false
schema:
type: string
- name: max_stops
in: query
description: 'Stop filter: ANY, NON_STOP, ONE_STOP, or TWO_PLUS_STOPS.'
required: false
schema:
type: string
- name: departure_window
in: query
description: Departure time window in HH-HH format (e.g. "6-20").
required: false
schema:
type: string
- name: airlines
in: query
description: Airline IATA codes to filter by (e.g. ["BA", "AA"]).
required: false
schema:
type: string
- name: sort_by
in: query
description: 'Sort order: CHEAPEST, DURATION, DEPARTURE_TIME, or ARRIVAL_TIME.'
required: false
schema:
type: string
- name: passengers
in: query
description: Number of adult passengers (1-9).
required: false
schema:
type: integer
format: int32
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/SearchGoogleFlightsResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/aviation/v1/search-google-dates:
get:
tags:
- AviationService
summary: SearchGoogleDates
description: SearchGoogleDates finds the cheapest travel dates across a flexible date range via Google Flights.
operationId: SearchGoogleDates
parameters:
- name: origin
in: query
description: Departure airport IATA code (e.g. "JFK").
required: false
schema:
type: string
- name: destination
in: query
description: Arrival airport IATA code (e.g. "LHR").
required: false
schema:
type: string
- name: start_date
in: query
description: Start of date range in YYYY-MM-DD format.
required: false
schema:
type: string
- name: end_date
in: query
description: End of date range in YYYY-MM-DD format.
required: false
schema:
type: string
- name: trip_duration
in: query
description: Trip duration in days (required for round-trip searches).
required: false
schema:
type: integer
format: int32
- name: is_round_trip
in: query
description: Whether to search for round-trip flights.
required: false
schema:
type: boolean
- name: cabin_class
in: query
description: 'Cabin class: ECONOMY, PREMIUM_ECONOMY, BUSINESS, or FIRST.'
required: false
schema:
type: string
- name: max_stops
in: query
description: 'Stop filter: ANY, NON_STOP, ONE_STOP, or TWO_PLUS_STOPS.'
required: false
schema:
type: string
- name: departure_window
in: query
description: Departure time window in HH-HH format (e.g. "6-20").
required: false
schema:
type: string
- name: airlines
in: query
description: Airline IATA codes to filter by (e.g. ["BA", "AA"]).
required: false
schema:
type: string
- name: sort_by_price
in: query
description: Whether to sort results by price (lowest first).
required: false
schema:
type: boolean
- name: passengers
in: query
description: Number of adult passengers (1-9).
required: false
schema:
type: integer
format: int32
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/SearchGoogleDatesResponse'
"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
- FLIGHT_DELAY_TYPE_CLOSURE
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
- FLIGHT_DELAY_SOURCE_AVIATIONSTACK
- FLIGHT_DELAY_SOURCE_NOTAM
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.
GetAirportOpsSummaryRequest:
type: object
properties:
airports:
type: array
items:
type: string
maxItems: 20
minItems: 1
description: IATA airport codes to query (e.g., ["IST", "ESB", "LHR"]).
maxItems: 20
minItems: 1
description: GetAirportOpsSummaryRequest specifies which airports to summarize.
GetAirportOpsSummaryResponse:
type: object
properties:
summaries:
type: array
items:
$ref: '#/components/schemas/AirportOpsSummary'
cacheHit:
type: boolean
description: Whether the response was served from cache.
description: GetAirportOpsSummaryResponse contains operational summaries for requested airports.
AirportOpsSummary:
type: object
properties:
iata:
type: string
description: IATA airport code.
icao:
type: string
description: ICAO airport code.
name:
type: string
description: Airport name.
timezone:
type: string
description: IANA timezone (e.g., "Europe/Istanbul").
delayPct:
type: number
format: double
description: Percentage of flights currently delayed (0-100).
avgDelayMinutes:
type: integer
format: int32
description: Average delay in minutes across delayed flights.
cancellationRate:
type: number
format: double
description: Cancellation rate as a percentage (0-100).
totalFlights:
type: integer
format: int32
description: Total flights in the observation window.
closureStatus:
type: boolean
description: Whether the airport is currently closed.
notamFlags:
type: array
items:
type: string
description: Active NOTAM summary flags (e.g., "RWY 06/24 CLSD", "LOW VIS OPS").
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'.
topDelayReasons:
type: array
items:
type: string
description: Top reasons for delays.
source:
type: string
description: Data source identifier.
updatedAt:
type: integer
format: int64
description: 'Last update time as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
description: AirportOpsSummary contains operational health metrics for a single airport.
ListAirportFlightsRequest:
type: object
properties:
airport:
type: string
maxLength: 4
minLength: 3
description: IATA airport code (e.g., "IST").
direction:
type: string
enum:
- FLIGHT_DIRECTION_UNSPECIFIED
- FLIGHT_DIRECTION_DEPARTURE
- FLIGHT_DIRECTION_ARRIVAL
- FLIGHT_DIRECTION_BOTH
description: FlightDirection specifies whether to retrieve departures, arrivals, or both.
limit:
type: integer
maximum: 100
minimum: 1
format: int32
description: Maximum number of flights to return (1-100).
required:
- airport
description: ListAirportFlightsRequest specifies parameters for retrieving recent flights at an airport.
ListAirportFlightsResponse:
type: object
properties:
flights:
type: array
items:
$ref: '#/components/schemas/FlightInstance'
totalAvailable:
type: integer
format: int32
description: Total number of flights available from the provider.
source:
type: string
description: Data source identifier.
updatedAt:
type: integer
format: int64
description: 'Last update time as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
description: ListAirportFlightsResponse contains recent flights at an airport.
FlightInstance:
type: object
properties:
flightNumber:
type: string
description: IATA flight number (e.g., "TK1952").
date:
type: string
description: Departure date in ISO 8601 format (e.g., "2026-03-05").
operatingCarrier:
$ref: '#/components/schemas/Carrier'
origin:
$ref: '#/components/schemas/AirportRef'
destination:
$ref: '#/components/schemas/AirportRef'
scheduledDeparture:
type: integer
format: int64
description: 'Scheduled departure time as Unix epoch milliseconds (UTC).. Warning: Values > 2^53 may lose precision in JavaScript'
estimatedDeparture:
type: integer
format: int64
description: 'Estimated departure time as Unix epoch milliseconds (UTC).. Warning: Values > 2^53 may lose precision in JavaScript'
actualDeparture:
type: integer
format: int64
description: 'Actual departure time as Unix epoch milliseconds (UTC).. Warning: Values > 2^53 may lose precision in JavaScript'
scheduledArrival:
type: integer
format: int64
description: 'Scheduled arrival time as Unix epoch milliseconds (UTC).. Warning: Values > 2^53 may lose precision in JavaScript'
estimatedArrival:
type: integer
format: int64
description: 'Estimated arrival time as Unix epoch milliseconds (UTC).. Warning: Values > 2^53 may lose precision in JavaScript'
actualArrival:
type: integer
format: int64
description: 'Actual arrival time as Unix epoch milliseconds (UTC).. Warning: Values > 2^53 may lose precision in JavaScript'
status:
type: string
enum:
- FLIGHT_INSTANCE_STATUS_UNSPECIFIED
- FLIGHT_INSTANCE_STATUS_SCHEDULED
- FLIGHT_INSTANCE_STATUS_BOARDING
- FLIGHT_INSTANCE_STATUS_DEPARTED
- FLIGHT_INSTANCE_STATUS_AIRBORNE
- FLIGHT_INSTANCE_STATUS_LANDED
- FLIGHT_INSTANCE_STATUS_ARRIVED
- FLIGHT_INSTANCE_STATUS_CANCELLED
- FLIGHT_INSTANCE_STATUS_DIVERTED
- FLIGHT_INSTANCE_STATUS_UNKNOWN
description: FlightInstanceStatus represents the operational status of a flight occurrence.
delayMinutes:
type: integer
format: int32
description: Delay in minutes (0 if on time, negative if early).
cancelled:
type: boolean
description: Whether the flight is cancelled.
diverted:
type: boolean
description: Whether the flight has been diverted.
gate:
type: string
description: Departure gate (if available).
terminal:
type: string
description: Departure terminal (if available).
aircraftIcao24:
type: string
description: ICAO 24-bit transponder address of the aircraft (hex, e.g., "4b1805").
aircraftType:
type: string
description: Aircraft type designator (e.g., "B738").
codeshareFlightNumbers:
type: array
items:
type: string
description: Codeshare flight numbers marketed under this operating flight.
source:
type: string
description: Data source provider name.
updatedAt:
type: integer
format: int64
description: 'Last update time as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
description: FlightInstance represents a specific occurrence of a flight on a given date.
Carrier:
type: object
properties:
iataCode:
type: string
description: IATA two-letter airline code (e.g., "TK").
icaoCode:
type: string
description: ICAO three-letter airline code (e.g., "THY").
name:
type: string
description: Full airline name (e.g., "Turkish Airlines").
description: Carrier represents an airline or aircraft operator.
AirportRef:
type: object
properties:
iata:
type: string
description: IATA airport code (e.g., "IST").
icao:
type: string
description: ICAO airport code (e.g., "LTFM").
name:
type: string
description: Airport name (e.g., "Istanbul Airport").
timezone:
type: string
description: IANA timezone (e.g., "Europe/Istanbul").
description: AirportRef is a lightweight reference to an airport.
GetCarrierOpsRequest:
type: object
properties:
airports:
type: array
items:
type: string
maxItems: 20
minItems: 1
description: IATA airport codes to aggregate carrier metrics from.
maxItems: 20
minItems: 1
minFlights:
type: integer
minimum: 0
format: int32
description: 'Minimum number of flights required to include a carrier (default: 1).'
description: GetCarrierOpsRequest specifies parameters for carrier operations metrics.
GetCarrierOpsResponse:
type: object
properties:
carriers:
type: array
items:
$ref: '#/components/schemas/CarrierOpsSummary'
source:
type: string
description: Data source identifier.
updatedAt:
type: integer
format: int64
description: 'Last update time as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
description: GetCarrierOpsResponse contains carrier operations metrics.
CarrierOpsSummary:
type: object
properties:
carrier:
$ref: '#/components/schemas/Carrier'
airport:
type: string
description: Airport IATA code this summary applies to.
totalFlights:
type: integer
format: int32
description: Total flights observed.
delayedCount:
type: integer
format: int32
description: Number of delayed flights.
cancelledCount:
type: integer
format: int32
description: Number of cancelled flights.
avgDelayMinutes:
type: integer
format: int32
description: Average delay in minutes across delayed flights.
delayPct:
type: number
format: double
description: Delay percentage (0-100).
cancellationRate:
type: number
format: double
description: Cancellation rate (0-100).
updatedAt:
type: integer
format: int64
description: 'Last update time as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
description: CarrierOpsSummary contains delay and cancellation metrics for a carrier at an airport.
GetFlightStatusRequest:
type: object
properties:
flightNumber:
type: string
maxLength: 10
minLength: 3
description: IATA flight number (e.g., "TK1952").
date:
type: string
description: Departure date in ISO 8601 format (e.g., "2026-03-05").
origin:
type: string
description: Optional origin airport IATA code to disambiguate.
required:
- flightNumber
- date
description: GetFlightStatusRequest specifies a flight to look up.
GetFlightStatusResponse:
type: object
properties:
flights:
type: array
items:
$ref: '#/components/schemas/FlightInstance'
source:
type: string
description: Data source identifier.
cacheHit:
type: boolean
description: Whether the response was served from cache.
description: GetFlightStatusResponse contains flight status results.
TrackAircraftRequest:
type: object
properties:
icao24:
type: string
description: ICAO 24-bit transponder address (hex, e.g., "4b1805").
callsign:
type: string
description: ATC callsign (e.g., "THY7CX").
swLat:
type: number
format: double
description: Optional bounding box south-west latitude.
swLon:
type: number
format: double
description: Optional bounding box south-west longitude.
neLat:
type: number
format: double
description: Optional bounding box north-east latitude.
neLon:
type: number
format: double
description: Optional bounding box north-east longitude.
description: TrackAircraftRequest specifies an aircraft to track.
TrackAircraftResponse:
type: object
properties:
positions:
type: array
items:
$ref: '#/components/schemas/PositionSample'
source:
type: string
description: Data source identifier.
updatedAt:
type: integer
format: int64
description: 'Last update time as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
description: TrackAircraftResponse contains aircraft position observations.
PositionSample:
type: object
properties:
icao24:
type: string
description: ICAO 24-bit transponder address (hex, e.g., "4b1805").
callsign:
type: string
description: ATC callsign (e.g., "THY7CX").
lat:
type: number
format: double
description: Latitude in decimal degrees.
lon:
type: number
format: double
description: Longitude in decimal degrees.
altitudeM:
type: number
format: double
description: Barometric altitude in metres.
groundSpeedKts:
type: number
format: double
description: Ground speed in knots.
trackDeg:
type: number
format: double
description: True track over ground in degrees (0 = North, clockwise).
verticalRate:
type: number
format: double
description: Vertical rate in metres per second (positive = climbing).
onGround:
type: boolean
description: Whether the aircraft is on the ground.
source:
type: string
enum:
- POSITION_SOURCE_UNSPECIFIED
- POSITION_SOURCE_OPENSKY
- POSITION_SOURCE_WINGBITS
- POSITION_SOURCE_SIMULATED
description: PositionSource identifies the provider of aircraft position data.
observedAt:
type: integer
format: int64
description: 'Observation time as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
description: PositionSample represents a single aircraft position observation.
GetYoutubeLiveStreamInfoRequest:
type: object
properties:
channel:
type: string
description: YouTube channel handle or ID.
videoId:
type: string
description: Specific video ID to check.
description: GetYoutubeLiveStreamInfoRequest parameters for detecting live status.
GetYoutubeLiveStreamInfoResponse:
type: object
properties:
videoId:
type: string
description: Video ID of the live stream (if found).
isLive:
type: boolean
description: Whether the stream is currently live.
channelExists:
type: boolean
description: Whether the channel exists.
channelName:
type: string
description: Human-readable channel name.
hlsUrl:
type: string
description: HLS manifest URL (if available).
title:
type: string
description: Stream title.
error:
type: string
description: Optional error message.
description: GetYoutubeLiveStreamInfoResponse containing detection results.
SearchFlightPricesRequest:
type: object
properties:
origin:
type: string
maxLength: 4
minLength: 3
description: Origin airport IATA code.
destination:
type: string
maxLength: 4
minLength: 3
description: Destination airport IATA code.
departureDate:
type: string
description: Outbound departure date (ISO 8601).
returnDate:
type: string
description: Return date (ISO 8601), empty for one-way.
adults:
type: integer
maximum: 9
minimum: 1
format: int32
description: Number of adult passengers (1-9).
cabin:
type: string
enum:
- CABIN_CLASS_UNSPECIFIED
- CABIN_CLASS_ECONOMY
- CABIN_CLASS_PREMIUM_ECONOMY
- CABIN_CLASS_BUSINESS
- CABIN_CLASS_FIRST
description: CabinClass represents the travel class for a flight ticket.
nonstopOnly:
type: boolean
description: Whether to restrict to nonstop flights only.
maxResults:
type: integer
maximum: 50
minimum: 1
format: int32
description: Maximum number of quotes to return (1-50).
currency:
type: string
description: ISO 4217 currency code for prices (e.g., "usd", "eur", "try").
market:
type: string
description: Market/locale code (e.g., "us", "tr").
required:
- origin
- destination
- departureDate
description: SearchFlightPricesRequest specifies parameters for a flight price search.
SearchFlightPricesResponse:
type: object
properties:
quotes:
type: array
items:
$ref: '#/components/schemas/PriceQuote'
provider:
type: string
description: Provider name (e.g., "amadeus", "demo").
isDemoMode:
type: boolean
description: Whether results are from demo/simulated mode.
updatedAt:
type: integer
format: int64
description: 'Last update time as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
isIndicative:
type: boolean
description: Whether returned prices are indicative (subject to change).
description: SearchFlightPricesResponse contains flight price offers.
PriceQuote:
type: object
properties:
id:
type: string
description: Unique quote identifier.
origin:
type: string
description: Origin airport IATA code.
destination:
type: string
description: Destination airport IATA code.
departureDate:
type: string
description: Outbound departure date (ISO 8601).
returnDate:
type: string
description: Return date (ISO 8601), empty for one-way.
carrier:
$ref: '#/components/schemas/Carrier'
priceAmount:
type: number
format: double
description: Total price amount.
currency:
type: string
description: ISO 4217 currency code (e.g., "EUR", "USD", "TRY").
cabin:
type: string
enum:
- CABIN_CLASS_UNSPECIFIED
- CABIN_CLASS_ECONOMY
- CABIN_CLASS_PREMIUM_ECONOMY
- CABIN_CLASS_BUSINESS
- CABIN_CLASS_FIRST
description: CabinClass represents the travel class for a flight ticket.
stops:
type: integer
format: int32
description: Number of stops (0 = nonstop).
durationMinutes:
type: integer
format: int32
description: Total travel duration in minutes.
bookingUrl:
type: string
description: Booking URL or deep-link (if available).
provider:
type: string
description: Provider name (e.g., "amadeus", "demo").
isIndicative:
type: boolean
description: Whether the price is indicative rather than bookable.
observedAt:
type: integer
format: int64
description: 'Time when this quote was observed, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
checkoutRef:
type: string
description: Reference used during the checkout process (for follow-up actions).
expiresAt:
type: integer
format: int64
description: 'Time when this quote expires, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
description: PriceQuote represents a single flight price offer from a provider.
ListAviationNewsRequest:
type: object
properties:
entities:
type: array
items:
type: string
maxItems: 10
minItems: 1
description: Entities to filter by (airline names, airport codes, route strings).
maxItems: 10
minItems: 1
windowHours:
type: integer
maximum: 168
minimum: 1
format: int32
description: Time window in hours to look back (1-168).
maxItems:
type: integer
maximum: 50
minimum: 1
format: int32
description: Maximum number of news items to return (1-50).
description: ListAviationNewsRequest specifies filters for aviation news retrieval.
ListAviationNewsResponse:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/AviationNewsItem'
source:
type: string
description: Data source identifier.
updatedAt:
type: integer
format: int64
description: 'Last update time as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
description: ListAviationNewsResponse contains filtered aviation news items.
AviationNewsItem:
type: object
properties:
id:
type: string
description: Unique item identifier (hash of URL).
title:
type: string
description: Article title.
url:
type: string
description: Article URL.
sourceName:
type: string
description: Name of the news source (e.g., "FlightGlobal").
publishedAt:
type: integer
format: int64
description: 'Publication time as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
snippet:
type: string
description: Short text snippet or description.
matchedEntities:
type: array
items:
type: string
description: Entities matched from the query (airport codes, airline names).
imageUrl:
type: string
description: Article image URL (if available).
description: AviationNewsItem represents a single aviation news article or press release.
SearchGoogleFlightsRequest:
type: object
properties:
origin:
type: string
description: Departure airport IATA code (e.g. "JFK").
destination:
type: string
description: Arrival airport IATA code (e.g. "LHR").
departureDate:
type: string
description: Departure date in YYYY-MM-DD format.
returnDate:
type: string
description: Return date in YYYY-MM-DD format; omit for one-way.
cabinClass:
type: string
description: 'Cabin class: ECONOMY, PREMIUM_ECONOMY, BUSINESS, or FIRST.'
maxStops:
type: string
description: 'Stop filter: ANY, NON_STOP, ONE_STOP, or TWO_PLUS_STOPS.'
departureWindow:
type: string
description: Departure time window in HH-HH format (e.g. "6-20").
airlines:
type: array
items:
type: string
description: Airline IATA codes to filter by (e.g. ["BA", "AA"]).
sortBy:
type: string
description: 'Sort order: CHEAPEST, DURATION, DEPARTURE_TIME, or ARRIVAL_TIME.'
passengers:
type: integer
format: int32
description: Number of adult passengers (1-9).
description: SearchGoogleFlightsRequest specifies parameters for a Google Flights search.
SearchGoogleFlightsResponse:
type: object
properties:
flights:
type: array
items:
$ref: '#/components/schemas/GoogleFlightResult'
degraded:
type: boolean
error:
type: string
description: SearchGoogleFlightsResponse contains flight results from Google Flights.
GoogleFlightResult:
type: object
properties:
legs:
type: array
items:
$ref: '#/components/schemas/GoogleFlightLeg'
price:
type: number
format: double
durationMinutes:
type: integer
format: int32
stops:
type: integer
format: int32
description: GoogleFlightResult represents a complete itinerary (one or more legs).
GoogleFlightLeg:
type: object
properties:
airlineCode:
type: string
flightNumber:
type: string
departureAirport:
type: string
arrivalAirport:
type: string
departureDatetime:
type: string
description: ISO 8601 local datetime, e.g. "2025-06-01T08:45".
arrivalDatetime:
type: string
durationMinutes:
type: integer
format: int32
description: GoogleFlightLeg represents a single flight segment (one plane, one takeoff and landing).
SearchGoogleDatesRequest:
type: object
properties:
origin:
type: string
description: Departure airport IATA code (e.g. "JFK").
destination:
type: string
description: Arrival airport IATA code (e.g. "LHR").
startDate:
type: string
description: Start of date range in YYYY-MM-DD format.
endDate:
type: string
description: End of date range in YYYY-MM-DD format.
tripDuration:
type: integer
format: int32
description: Trip duration in days (required for round-trip searches).
isRoundTrip:
type: boolean
description: Whether to search for round-trip flights.
cabinClass:
type: string
description: 'Cabin class: ECONOMY, PREMIUM_ECONOMY, BUSINESS, or FIRST.'
maxStops:
type: string
description: 'Stop filter: ANY, NON_STOP, ONE_STOP, or TWO_PLUS_STOPS.'
departureWindow:
type: string
description: Departure time window in HH-HH format (e.g. "6-20").
airlines:
type: array
items:
type: string
description: Airline IATA codes to filter by (e.g. ["BA", "AA"]).
sortByPrice:
type: boolean
description: Whether to sort results by price (lowest first).
passengers:
type: integer
format: int32
description: Number of adult passengers (1-9).
description: SearchGoogleDatesRequest specifies parameters for a Google Flights date-range price search.
SearchGoogleDatesResponse:
type: object
properties:
dates:
type: array
items:
$ref: '#/components/schemas/DatePriceEntry'
degraded:
type: boolean
error:
type: string
description: SearchGoogleDatesResponse contains cheapest-date results from Google Flights.
DatePriceEntry:
type: object
properties:
date:
type: string
description: Departure date in YYYY-MM-DD format.
returnDate:
type: string
description: Return date in YYYY-MM-DD format; empty for one-way results.
price:
type: number
format: double
description: DatePriceEntry pairs a departure date (and optional return date) with its cheapest price.
Reference in New Issue View Git Blame Copy Permalink