Flight History Search

"""Typed models for Historical ADS-B - matches historical-adsb.mdx field tables."""from __future__ import annotationsfrom dataclasses import dataclassfrom typing import Literal@dataclassclass HistoricalFlightSummary:    flight_id: str    icao24: str | None    callsign: str | None    flight_number: str | None    tail_number: str | None    departure_airport_icao: str | None    arrival_airport_icao: str | None    flight_start: str    flight_end: str    takeoff_time: str | None    landing_time: str | None    flight_duration_min: float | None    distance_nm: float | None@dataclassclass HistoricalPosition:    timestamp: str    icao24: str    latitude: float    longitude: float    altitude_baro: float | None    ground_speed: float | None    track: float | None    vertical_rate: float | None    is_on_ground: bool@dataclassclass HistoricalFlightWindow:    flight_id: str    callsign: str | None    departure_airport_icao: str | None    arrival_airport_icao: str | None    takeoff_time: str | None    landing_time: str | None    flight_start: str    flight_end: str    flight_state: str | None@dataclassclass AirportTrafficFlight:    flight_id: str    icao24: str | None    callsign: str | None    departure_airport_icao: str | None    arrival_airport_icao: str | None    takeoff_time: str | None    landing_time: str | None    flight_duration_min: float | None    distance_nm: float | None@dataclassclass AirportTrafficResponse:    icao: str    direction: Literal["dep", "arr", "both"]    count: int    flights: list[AirportTrafficFlight]

import osimport requestsBASE = "https://data.skylinkapi.com/v3.1"HEADERS = {    "x-api-key": os.getenv("SKYLINK_API_KEY", "YOUR_API_KEY")}PLAN_GATED = {401, 403}def search_historical_flights(    *,    registration: str | None = None,    callsign: str | None = None,    icao24: str | None = None,    departure_icao: str | None = None,    arrival_icao: str | None = None,    start: str | None = None,    end: str | None = None,    limit: int = 10,    tier: str = "ultra",) -> dict:    """Search archived flights - at least one aircraft/route filter is required."""    params = {k: v for k, v in {        "registration": registration,        "callsign": callsign,        "icao24": icao24,        "departure_icao": departure_icao,        "arrival_icao": arrival_icao,        "start": start,        "end": end,        "limit": limit,    }.items() if v is not None}    r = requests.get(        f"{BASE}/{tier}/history/flights",        headers=HEADERS,        params=params,        timeout=(10, 25),    )    r.raise_for_status()    return r.json()def fetch_historical_flight_detail(flight_id: str, *, tier: str = "ultra") -> dict:    """Fetch full metadata for one archived flight by UUID."""    r = requests.get(        f"{BASE}/{tier}/history/flight/{flight_id}",        headers=HEADERS,        timeout=(10, 25),    )    r.raise_for_status()    return r.json()def search_then_detail(    *,    departure_icao: str,    limit: int = 1,    tier: str = "ultra",) -> dict | None:    """Search → pick first match → return full flight detail."""    search = search_historical_flights(        departure_icao=departure_icao,        limit=limit,        tier=tier,    )    flights = search.get("flights") or []    if not flights:        return None    return fetch_historical_flight_detail(flights[0]["flight_id"], tier=tier)if __name__ == "__main__":    import json    detail = search_then_detail(departure_icao="EGLL")    print(json.dumps(detail, indent=2, default=str) if detail else "No matching flight found")