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
f4183f99c7cc41a9746341d7f78455bde2e5738c
worldmonitor/docs/api/AviationService.openapi.yaml
Elie Habib 45f5e5a457 feat(forecast): AI Forecasts prediction module (#1579) 
* feat(forecast): add AI Forecasts prediction module (Pro-tier)

MiroFish-inspired prediction engine that generates structured forecasts
across 6 domains (conflict, market, supply chain, political, military,
infrastructure) using existing WorldMonitor data streams.

- Proto definitions for ForecastService with GetForecasts RPC
- Dedicated seed script (seed-forecasts.mjs) with 6 domain detectors,
  cross-domain cascade resolver, prediction market calibration, and
  trend detection via prior snapshot comparison
- Premium-gated RPC handler (PREMIUM_RPC_PATHS enforcement)
- Lazy-loaded ForecastPanel with domain filters, probability bars,
  trend arrows, signal evidence, and cascade links
- Health monitoring integration (seed-meta freshness tracking)
- Refresh scheduler with API key guard

* test(forecast): add 47 unit tests for forecast detectors and utilities

Covers forecastId, normalize, resolveCascades, calibrateWithMarkets,
computeTrends, and smoke tests for all 6 domain detectors. Exports
testable functions from seed script with direct-run guard.

* fix(forecast): domain mismatch 'infra' vs 'infrastructure', add panel category

- Seed script used 'infra' but ForecastPanel filtered on 'infrastructure',
  causing Infra tab to show zero results
- Added 'forecast' to intelligence category in PANEL_CATEGORY_MAP

* fix(forecast): move CSS to one-time injection, improve type safety

- P2: Move style block from setContent to one-time document.head injection
  to prevent CSS accumulation on repeated renders
- P3: Replace +toFixed(3) with Math.round for readability in seed script
- P3: Use Forecast type instead of any[] in RPC handler filter

* fix(forecast): handle sebuf proto data shapes from Redis

Detectors now normalize CII scores from server-side proto format
(combinedScore, TREND_DIRECTION_RISING, region) to uniform shape.
Outage severity handles proto enum format (SEVERITY_LEVEL_HIGH).
Added confidence floor of 0.3 for single-source predictions.

Verified against live Redis: 2 predictions generated (Iran infra
shutdown, IL political instability).

* feat(forecast): unlock AI Forecasts on web, lock desktop only (trial)

- Remove forecast RPC from PREMIUM_RPC_PATHS (web access is free)
- Panel locked on desktop only (same as oref-sirens/telegram-intel)
- Remove API key guards from data-loader and refresh scheduler
- Web users get full access during trial period

* chore: regenerate proto types with make generate

Re-ran make generate after rebasing on main. Plugin v0.7.0 dropped
@ts-nocheck from output, added it back to all 50 generated files.
Fixed 4 type errors from proto codegen changes:
- MarketSource enum -> string union type
- TemporalAnomalyProto -> TemporalAnomaly rename
- webcam lastUpdated number -> string

* fix(forecast): use chokepoints v4 key, include ciiContribution in unrest

- P1: Switch chokepoints input from stale v2 to active v4 Redis key,
  matching bootstrap.js and cache-keys.ts
- P2: Add ciiContribution to unrest component fallback chain in
  normalizeCiiEntry so political detector reads the correct sebuf field

* feat(forecast): Phase 2 LLM scenario enrichment + confidence model

MiroFish-inspired enhancements:
- LLM scenario narratives via Groq/OpenRouter (narrative-only, no numeric
  adjustment). Evidence-grounded prompts with mandatory signal citation
  and few-shot examples from MiroFish's SECTION_SYSTEM_PROMPT_TEMPLATE.
- Top-4 predictions batched into single LLM call for cost efficiency.
- News context from newsInsights attached to all predictions for LLM
  prompt grounding (NOT in signals, cannot affect confidence).
- Deterministic confidence model: source diversity via SIGNAL_TO_SOURCE
  mapping (deduplicates cii+cii_delta, theater+indicators) + calibration
  agreement from prediction market drift. Floor 0.2, ceiling 1.0.
- Output validation: rejects scenarios without signal references.
- Truncated JSON repair for small model output.
- Structured JSON logging for LLM calls.
- Redis cache for LLM scenarios (1h TTL).
- 23 new tests (70 total), all passing.
- Live-tested: OpenRouter gemini-2.5-flash produces evidence-grounded
  scenario narratives from real WorldMonitor data.

* feat(forecast): Phase 3 multi-perspective scenarios, projections, data-driven cascades

MiroFish-inspired enhancements:
- Multi-perspective LLM analysis: top-2 predictions get strategic,
  regional, and contrarian viewpoints via combined LLM call
- Probability projections: domain-specific decay curves (h24/d7/d30)
  anchored to timeHorizon so probability equals projections[timeHorizon]
- Data-driven cascade rules: moved from hardcoded array to JSON config
  (scripts/data/cascade-rules.json) with schema validation, named
  predicate evaluators, unknown key rejection, and fallback to defaults
- 4 new cascade paths: infrastructure->supply_chain, infrastructure->market
  (both requiresSeverity:total), conflict->political, political->market
- Proto: added Perspectives and Projections messages to Forecast
- ForecastPanel: renders projections row and conditional perspectives toggle
- 89 tests (19 new), all passing
- Live-tested: OpenRouter produces perspectives from real data

* feat(forecast): Phase 4 data utilization + entity graph

Fixes data gaps that prevented 4 of 6 detectors from firing:
- Input normalizers: chokepoint v4 shape + GPS hexes-to-zones mapping
- Chokepoint warm-ping (production-only, requires WM_API_BASE_URL)
- Lowered CII conflict threshold from 70 to 60, gated on level=high|critical

4 new standalone detectors:
- UCDP conflict zones (10+ events per country)
- Cyber threat concentration (5+ threats per country)
- GPS jamming in maritime shipping zones (5 regions)
- Prediction markets as signals (60-90% probability markets)

Entity-relationship graph (file-based, 38 nodes):
- Countries, theaters, commodities, chokepoints, alliances
- Alias table resolves both ISO codes and display names
- Graph cascade discovery links predictions across entities

Result: 51 predictions (up from 1-2), spanning conflict, infrastructure,
and supply chain domains. 112 tests, all passing.

* fix(forecast): redis cache format, signal source mapping, type safety

Fresh-eyes audit fixes:
- BUG: redisSet used wrong Upstash API format (POST body with {value,ex}
  instead of command array ['SET',key,value,'EX',ttl]). LLM cache writes
  were silently failing, causing fresh LLM calls every run.
- BUG: prediction_market signal type missing from SIGNAL_TO_SOURCE,
  inflating confidence for market-derived predictions.
- CLEANUP: Remove unnecessary (f as any) casts in ForecastPanel since
  generated Forecast type already has projections/perspectives fields.
- CLEANUP: Bump health maxStaleMin from 60 to 90 to avoid false STALE
  alerts when LLM calls add latency to seed runs.

* feat(forecast): headline-entity matching with news corroboration signals

Uses entity graph aliases to match headlines to predictions by
country/theater (excludes commodity/infrastructure nodes to prevent
false positives). Predictions with matching headlines get a
news_corroboration signal visible in the panel.

Also fixes buildUserPrompt to merge unique headlines from ALL
predictions in the LLM batch (was only reading preds[0].newsContext).

Live-tested: 13 of 51 predictions now have corroborating headlines
(Iran, Israel, Syria, Ukraine, etc). 116 tests, all passing.

* feat(forecast): add country-codes.json for headline-entity matching

56 countries with ISO codes, full names, and scoring keywords (extracted
from src/config/countries.ts + UCDP-relevant additions). Used by
attachNewsContext for richer headline matching via getSearchTermsForRegion
which combines country-codes + entity graph + keyword aliases.

14/57 predictions now have news corroboration (limited by headline
coverage, not matching quality: only 8 headlines currently available).

* feat(forecast): read 300 headlines from news digest instead of 8

Read news:digest:v1:full:en (300 headlines across 16 categories) instead
of just news:insights:v1 topStories (8 headlines). Fallback to topStories
if digest is unavailable.

Result: news corroboration jumped from 25% to 64% (38/59 predictions).

* fix(forecast): handle parenthetical country names in headline matching

Strip suffixes like '(Zaire)', '(Burma)', '(Soviet Union)' from UCDP
region names before matching against country-codes.json. Also use
includes() for reverse name lookup to catch partial matches.

Corroboration: 64% -> 69% (41/59). Remaining 18 unmatched are countries
with no current English-language news coverage.

* fix(forecast): cache validated LLM output, add digest test, log cache errors

Fresh-eyes audit fixes:
- Combined LLM cache now stores only validated items (was caching raw
  unvalidated output, serving potentially invalid scenarios on cache hit)
- redisSet logs warnings on failure (was silently swallowing all errors)
- Added digest-based test for attachNewsContext (primary path was untested)
- Fixed test arity: attachNewsContext(preds, news, digest) with 3 params

* fix(forecast): remove dead confidenceFromSources, reduce warm-ping timeout

- P2: Remove confidenceFromSources (dead code, computeConfidence overwrites
  all initial confidence values). Inline the formula in original detectors.
- P3: Reduce warm-ping timeout from 30s to 15s (non-critical step)
- P3: Add trial status comment on forecast panel config

* fix(forecast): resolve ISO codes to country names, fix market detector, safe pre-push

P1 fixes from code review:
- CII ISO codes (IL, IR) now resolved to full country names (Israel, Iran)
  via country-codes.json. Prevents substring false positives (IL matching
  Chile) in event correlation. Uses word-boundary regex for matching.
- Market detector CII-to-theater mapping now uses entity graph traversal
  instead of broken theater-name substring matching. Iran correctly maps
  to Middle East theater via graph links.
- Pre-push hook no longer runs destructive git checkout on proto freshness
  failure. Reports mismatch and exits without modifying worktree.
2026-03-15 01:42:04 +04:00

1279 lines
54 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 recent position data for an aircraft.
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/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'
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
maxLength: 10
minLength: 10
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.
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
maxLength: 10
minLength: 10
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.
Reference in New Issue View Git Blame Copy Permalink