Aviation

Retrieve recent ACAS incidents and near misses, by time and/or location. Args: search_area: Optional radius around a geo point (latitude, longitude, range_km) from_date: Optional start date/datetime [YYYY-MM-DD or YYYY-MM-DD HH:MM:SS] to_date: Optional end date/datetime [YYYY-MM-DD or YYYY-MM-DD HH:MM:SS] result_limit: Optional cap on returned results Returns: Record fields: h (icao24), f (callsign), la (latitude), lo (longitude), threat_icao24 (icao24 of threat aircraft), acas_burst_start, acas_burst_end, map_url (ready-to-paste wingbits.com map link — use verbatim, do not modify) Notes: - If date range is not provided, returns all available data.

Search Aircraft in the aviation database. Args: search_area: Optional radius around a geo point (latitude, longitude, range_km). Ignored if h3_4_cells provided. from_date: Optional start date/datetime [YYYY-MM-DD or YYYY-MM-DD HH:MM:SS] to_date: Optional end date/datetime [YYYY-MM-DD or YYYY-MM-DD HH:MM:SS] aircraft_types: Optional filter by type (LIGHT_AIRCRAFT, SMALL_AIRCRAFT, LARGE_AIRCRAFT, HIGH_VORTEX_LARGE_AIRCRAFT, HEAVY_AIRCRAFT, HIGH_PERFORMANCE_AIRCRAFT, AIRCRAFT, HELICOPTER, ROTORCRAFT, GLIDER, OTHER_AIRBORNE_VEHICLE, GROUND_VEHICLE) operator_names: Optional filter by operator (fuzzy) manufacturer: Optional filter by manufacturer (fuzzy) models: Optional filter by aircraft model (fuzzy) altitude_range: Optional [min, max] in feet speed_range: Optional [min, max] in knots icao24_codes: Optional limit to specific ICAO24 hex codes call_signs: Optional limit to specific callsigns/flight numbers. Both ICAO format (e.g., "RYR9663", "DLH3FN") and IATA format (e.g., "FR9663", "LH400") are accepted — IATA codes are auto-expanded to their ICAO equivalents server-side via schedules.flight_schedules before the ADS-B query runs. ADS-B emits ICAO callsigns, so an IATA-only callsign with no known schedule mapping will return no rows. Trailing-wildcard entries (e.g., "DLH*", "RYR9*") are supported and translate to a ClickHouse LIKE prefix match; wildcard entries skip IATA→ICAO expansion and are matched verbatim against the broadcast callsign. h3_4_cells: Optional H3 res-4 cell indexes (from location_finder). Takes precedence over search_area. result_limit: Optional cap on returned results Returns: Record fields: h (icao24), f (callsign), first_seen, last_seen, first/last_seen_latitude, first/last_seen_longitude, first/last_seen_altitude, aircraft_variant, operator Notes: - If no from/to dates, defaults to last 24 hours. - Chain with location_finder to search by country/city/airport using h3_4_cells. - Returns ROWS, not aggregates. For "how many" / "trend" / "compare" / "group by" questions, do NOT call this and count rows — your count will be capped at result_limit and silently wrong for any busy region. Use `query_aviation_data` with `SELECT COUNT(*) ... GROUP BY ...` instead. - Returned data carries no route, origin, destination, or direction. ADS-B has none of those. - When response.metadata.truncated is true, the row set was capped — narrow the query (smaller area, shorter window) or switch to a SQL aggregation. Do NOT report counts or trends from truncated rows.

Search Aircraft in the aviation database — ownership-free variant. Same behaviour as aircraft_finder but does NOT join the ownership view: no operator / manufacturer / model filters, and result rows do NOT include aircraft_variant or operator. Use this when you only need flight tracks / positions / callsigns and don't care about ownership enrichment. Pair with aircraft_finder if you need ownership-derived fields or filters. Args: search_area: Optional radius around a geo point (latitude, longitude, range_km). Ignored if h3_4_cells provided. from_date: Optional start date/datetime [YYYY-MM-DD or YYYY-MM-DD HH:MM:SS] to_date: Optional end date/datetime [YYYY-MM-DD or YYYY-MM-DD HH:MM:SS] aircraft_types: Optional filter by type (LIGHT_AIRCRAFT, SMALL_AIRCRAFT, LARGE_AIRCRAFT, HIGH_VORTEX_LARGE_AIRCRAFT, HEAVY_AIRCRAFT, HIGH_PERFORMANCE_AIRCRAFT, AIRCRAFT, HELICOPTER, ROTORCRAFT, GLIDER, OTHER_AIRBORNE_VEHICLE, GROUND_VEHICLE) altitude_range: Optional [min, max] in feet speed_range: Optional [min, max] in knots icao24_codes: Optional limit to specific ICAO24 hex codes call_signs: Optional limit to specific callsigns/flight numbers. Both ICAO format (e.g., "RYR9663", "DLH3FN") and IATA format (e.g., "FR9663", "LH400") are accepted — IATA codes are auto-expanded to their ICAO equivalents server-side via schedules.flight_schedules before the ADS-B query runs. ADS-B emits ICAO callsigns, so an IATA-only callsign with no known schedule mapping will return no rows. Trailing-wildcard entries (e.g., "DLH*", "RYR9*") are supported and translate to a ClickHouse LIKE prefix match; wildcard entries skip IATA→ICAO expansion and are matched verbatim against the broadcast callsign. h3_4_cells: Optional H3 res-4 cell indexes (from location_finder). Takes precedence over search_area. result_limit: Optional cap on returned results Returns: Record fields: h (icao24), f (callsign), first_seen, last_seen, first/last_seen_latitude, first/last_seen_longitude, first/last_seen_altitude Notes: - If no from/to dates, defaults to last 24 hours. - Chain with location_finder to search by country/city/airport using h3_4_cells. - Returns ROWS, not aggregates. For "how many" / "trend" / "compare" / "group by" questions, do NOT call this and count rows — your count will be capped at result_limit and silently wrong for any busy region. Use `query_aviation_data` with `SELECT COUNT(*) ... GROUP BY ...` instead. - Returned data carries no route, origin, destination, or direction. ADS-B has none of those. - When response.metadata.truncated is true, the row set was capped — narrow the query (smaller area, shorter window) or switch to a SQL aggregation. Do NOT report counts or trends from truncated rows.

Resolve operator, registration, aircraft model, operator country, manufacturer, and owner for a batch of ICAO hex codes. Single round-trip — pass every hex you need identified in one call. Use this when answering any question that requires per-aircraft identity (operator/airline, tail number, registration, aircraft type, owner) after a position query (e.g. `wingbits_api_realtime_flights`, `wingbits_api_realtime_flight_search`). Never infer operator from callsign prefix or hex range — call this tool instead. Returns: - `identities`: rows with `{ hex, operator, aircraftModel, registration, operatorCountry, manufacturer, owner }` — any field may be null if unknown - `notFoundHexes`: hexes not present in any identity source (typically very new registrations). For these, report the callsign/hex verbatim without guessing.

Get detailed schema information for a specific table in the aviation database. Returns field names, data types, and comments. Args: table_name: Name of the table (e.g. 'adsb_sampled', 'flight_trace')

Find latitude/longitude coordinates and H3 cell indexes for a location or area of interest. Args: query: Search text (e.g. city name, airport ICAO/IATA code, country name) hint: Search type — "airport", "country", or "city" result_limit: Optional cap on returned results (max 50) Returns: Record fields: name, h3_4 (array of H3 res-4 cell indexes as strings), lat (null for countries), lon (null for countries), location_type, additional_info (JSON with extra fields per hint type) Notes: - The h3_4 array is the primary output for spatial chaining with aircraft_finder. - Small countries (e.g. Malta) may return h3_4=[] because H3 res-4 cells (~1,700 km²) are too coarse. - Chain: location_finder → aircraft_finder(h3_4_cells=result.h3_4)

Search military aircraft in the aviation database. Args: country: Optional, filter by country of registration operator: Optional, filter by operating force or group (e.g., US Air Force, Royal Navy) model: Optional, filter by aircraft model (e.g., C-130, F-16, Typhoon) resultLimit: Optional cap on returned results Returns: Record fields: h (icao24), aircraft_model, operator, operator_type, country

Look up aircraft registered to specific operators, independently from actual flight data. Args: operator_names: List of operator names to filter by (exact match) Returns: Record fields: icao24 (aircraft ICAO24 code), operator, model (aircraft variant)

Execute a raw SQL SELECT query on the aviation ClickHouse database. USE ONLY AS LAST RESORT if no other tool can provide the required information. IMPORTANT: Always call get_schema first to verify exact column names before writing any SQL. Column names are not obvious — e.g. adsb_sampled uses: h (icao24), f (callsign), sq (squawk code), c (emitter category), la (latitude), lo (longitude), al (altitude ft), gs (ground speed). Guessing column names will cause ClickHouse errors. Args: query: SQL SELECT query to execute max_rows: Maximum rows to return (default: 1000) Returns: JSON object with data array and metadata (count, truncated flag) Notes: - Only SELECT queries are allowed (INSERT/UPDATE/DELETE/DROP blocked). - Call get_schema before writing SQL — never guess column names.

Find scheduled flights in schedules.flight_schedules. Given user-friendly inputs, returns one row per scheduled flight (master + each codeshare) deduped to the most recent snapshot per (flight_icao, flight_iata, dep_time_ts), with denormalised airport / airline codes, the best-known dep / arr timestamps, and a best-effort broadcast (ADS-B) callsign that can be fed straight into aircraft_finder_lite.call_signs to retrieve actual ADS-B tracks. Args: dep_airport: Optional departure airport — name, municipality (e.g., "Paris"), IATA ("LHR") or ICAO ("EGLL"). Fuzzy + permissive. arr_airport: Optional arrival airport, same shape. dep_from: Optional earliest departure time [YYYY-MM-DD or YYYY-MM-DD HH:MM:SS] Compared against coalesce(dep_actual_ts, dep_estimated_ts, dep_time_ts). dep_to: Optional latest departure time, same semantics. arr_from: Optional earliest arrival time, compared against the analogous arrival coalesce. arr_to: Optional latest arrival time. airline: Optional airline filter — name, IATA ("BA") or ICAO ("BAW"). result_limit: Optional cap on returned results. At least one of dep_airport / arr_airport MUST be supplied — otherwise the tool errors rather than issuing an unbounded scan. Returns: Record fields: query_type, flight_icao, flight_iata, airline_icao, airline_iata, dep_icao, dep_iata, arr_icao, arr_iata, dep_ts, arr_ts, status, aircraft_icao, updated_at, estimated_callsign. Notes: - estimated_callsign is the broadcast/ADS-B callsign most recently matched to the master IATA via schedules.latest_univoque_matches; it's a best-effort estimate (NULL when no match). All codeshare siblings of a master share its estimated_callsign. - Sorted by dep_ts ascending (NULLS LAST).

Retrieve aircraft that issued a specific squawk code in a given area and time range. Supports generic search for emergency codes like 7500, 7600, 7700. Args: squawk_situation: Optional predefined situation — "hijacking" (7500), "radio_failure" (7600), "emergency" (7700), "all_emergencies" (7500/7600/7700), "all_squawks" (any non-empty code) squawk_codes: Optional specific list of squawk codes (e.g., ["7500", "7700"]) search_area: Optional radius around a geo point (latitude, longitude, range_km) from_date: Optional start date/datetime [YYYY-MM-DD or YYYY-MM-DD HH:MM:SS] to_date: Optional end date/datetime [YYYY-MM-DD or YYYY-MM-DD HH:MM:SS] result_limit: Optional cap on returned results Returns: Record fields: h (icao24), f (callsign), c (aircraft emitter category), squawk_code, start_ts (event start), end_ts (event end) Notes: - Either squawk_situation or squawk_codes must be supplied. - If no from/to dates are specified, defaults to last 7 days.

Look up aircraft (returning icao24) linked to specific keywords. Args: keyword: string of keywords to search for in VIP aircraft data (e.g., owner, registration, label) Examples: - keyword = "Government of " - keyword = "" - keyword = "" resultLimit: Optional cap on returned results Returns: Record fields: score (higher = better match), h (icao24), registration, owner, operator, remarks Notes: - Results with a score below 0.9 are fuzzy matches and should be scrutinized.

Run a TypeScript (or JavaScript) script against the aviation data API in an isolated V8 sandbox. The script can `import { ... } from '@wingbits/aviation'` to call any aviation tool. Each tool returns `{ data, metadata }`. Use `await fetchAll(result)` to materialize all rows — it handles both small inline results and large results offloaded to S3 (>100 rows) transparently. Use console.log for any output you want the orchestrator to see. stderr is reserved for structured errors. Args: script: TypeScript or JavaScript source. ESM. Top-level await allowed. timeout: Optional timeout in seconds (default 30, max 120). Call get_code_mode_functions first to see the full typed surface.

Return the TypeScript declarations and example scripts for the sandboxed @wingbits/aviation module. Call this once before writing a code-mode script so you know the available functions, their descriptions, argument shapes, and return types (ResultSet vs. plain object).

Detect GPS jamming / spoofing by aggregating aircraft-reported NACp (Navigation Accuracy Category for Position) over an area and time window. What this returns: - **overall** stats for the whole area+window (samples, aircraft count, % bad) - **hot_cells** — top H3 res-4 cells ranked by % bad samples, each with a center lat/lon - **hourly** time series of `{ bucket_start, samples, pct_bad, pct_degraded }` so the agent can spot onset/offset. Bucket size is reported in `hourly_granularity` — hourly for windows ≤ 14d, daily for longer windows (keeps the payload tractable). How to read the numbers: - `degraded` = aircraft reported NACp 1-6 (low-accuracy GPS — classic jamming signature) - `no_position` = aircraft reported NACp 0 (GPS unavailable / integrity unknown — denial signature) - `pct_bad` = (degraded + no_position) / samples × 100. Sustained values >5% in a populated cell almost always indicate jamming. The global background is ~0.5%. - An H3 res-4 cell is ~1,700 km² — roughly a 50km radius circle. Cell centers are returned for mapping. Args: - `search_area` OR `h3_4_cells`: where to look. Use `location_finder` to resolve country/city to h3_4 cells. - `from_date` / `to_date`: window, defaults to last 24h. `adsb_nac_stats` retains ~60 days, so multi-week comparisons are fine here. - `min_samples_per_cell`: filter sparse cells out of hot_cells (default 500). A cell with 20 samples and 10 bad ones is noise, not a hotspot. - `top_cells`: how many hot cells to return (default 20). `search_area` vs `h3_4_cells` — read this before historical investigations: - `search_area` resolves to a candidate set of H3 cells from the **last 24h** of traffic, then filters the historical window to that set. Fast, but a cell that was active during a jamming event months ago can be missed if its traffic has since dropped (e.g. coverage reduced, region went quiet). - For historical investigations in regions whose traffic profile may have changed, resolve cells with `location_finder` and pass them as `h3_4_cells` — that path skips the 24h candidate-set filter and searches the full retention window. Caveats — always surface these to the user: - **Absence ≠ no jamming.** A cell with zero samples means no aircraft were tracked there in the window (coverage gap), NOT that GPS works fine. Only cells that appear in the result set are evidence. - **One aircraft ≠ jamming.** A high pct_bad from a single aircraft might be a transponder fault, not an environmental jammer. `aircraft_observations` is an inflated upper bound (sums 10-min-bucket counts, same plane across buckets counted multiple times) — treat low values (single digits) as suspicious, but don't read large values as "N distinct planes". - This tool reports the **observable**, not the **cause**. We see degraded GPS reports; we don't see jamming-source identification. State observations as observations.

List specific aircraft (hex codes) that reported degraded GPS — NACp < 7 — inside a search area and time window. Sources `adsb_nac_raw` (per-sample, not aggregated). Use for: "which aircraft had their GPS jammed over Lithuania last week?", "give me hexes of planes affected by the Bahrain jamming event yesterday". Args: - `search_area`: required. Center lat/lon + range_km. - `hours_back`: look-back window from now, in hours (default 2, max 4). **`adsb_nac_raw` has a hard 4-hour TTL — there is no way to query older data through this tool.** For older windows, use `gps_jamming_finder` to confirm the area-wide pattern, then chain into `aircraft_finder` with hexes from the affected region. - `min_samples`: drop aircraft with fewer than N NAC reports in the window (default 5) — filters transient drive-by traffic. - `min_pct_bad`: only return aircraft with this % of samples below NACp=7 (default 20). Lower it to widen the net. - `result_limit`: max rows (default 200). Returns rows: `{ h, samples, no_position, degraded, pct_bad, min_np, last_seen, last_lat, last_lon }`. Caveats: - A single hex appearing here is NOT proof of jamming — it could be a transponder fault. Cross-reference with `gps_jamming_finder` to confirm there's an area-wide pattern around the same time. If only one hex shows up in an otherwise-clean area, suspect equipment. - Routes/origins are NOT in this output. Pair with `aircraft_finder` (icao24_codes=[hexes]) to enrich with operator/callsign.

Query LIVE flight data from the Wingbits network — a **single position snapshot** of currently-tracked aircraft in an area. Use for: "what helicopters are over X right now", "current flights over Y", "any planes near me". Returns observable state only: hex, callsign, position, altitude, speed, heading, squawk, onGround, timestamp. **For operator / registration / aircraft model / owner, call `aircraft_identity` with the hexes you care about — it accepts an array of hexes and returns them all in one round-trip.** Never infer operator or registration from callsign prefixes or hex ranges. If you need identity for any of the returned flights, batch the hexes into a single `aircraft_identity` call rather than making N per-hex calls. What this tool DOES NOT tell you (do not infer these from a snapshot): - **Direction of travel** — onGround=true means "currently on ground", NOT "arriving" or "departing". A snapshot has no temporal direction; do NOT classify aircraft as arrivals vs departures from one call. - **Origin or destination** — ADS-B carries no route data. A position near LHR ≠ "departing LHR". - **Schedules, delays, cancellations, gates, terminals** — none of this is in ADS-B. For arrival/departure analysis, try `location_finder('')` + `aircraft_finder` over the returned coords first. Only if that approach can't answer the question, fall back to `query_aviation_data` with a dual-source `completed_flights` × `flight_trace` cross-check — never query `completed_flights` alone for counts. Do NOT use this tool for historical queries ("flights yesterday", "last week") — use `aircraft_finder` (after `location_finder` for area coords). SQL is the last resort.

Get current position and status of a specific flight by its ICAO hex address. Use this when you already have the hex code and want to check current status. Returns observable state (position, altitude, speed, squawk). For operator, registration, and aircraft model, call `aircraft_identity` with the same hex. Never infer operator from callsign prefix or hex range.

Search for a specific flight by callsign or ICAO hex code. Use this when the user asks about a specific flight like "Where is UAL123?" or "Find flight ABC123". Returns observable state (position, altitude, speed, squawk). For operator, registration, and aircraft model, call `aircraft_identity` with the returned hex. Never infer operator from the callsign prefix.

Search the web for current information about a specific flight (route, schedule, status, arrival time), a specific airport (terminals, facilities, info), or real-time flight status (delays, cancellations). Use this when ADS-B tools do not have the answer — for example, when a flight is not in live data but the user asks where it is going, or when the user asks if a flight is on time.

Dry-run a code-mode aviation routine against a synthetic time window. Use this to validate that a script you've written compiles, calls the aviation helpers correctly, and emits the expected `{ flights, meta }` JSON envelope on stdout. The runtime takes care of the time-bound injection — your script just references `__window.from` and `__window.to` wherever a helper needs a date range. Do NOT declare `__window` yourself; the tool prepends it for you. This is the same V8 sandbox the production cron executor uses; if the dry-run succeeds here, the saved routine will work in production with a fresh window each tick. Args: script: TypeScript source. ESM. Top-level await allowed. Must reference `__window.from` / `__window.to` for time bounds and end with `console.log(JSON.stringify({ flights, meta }))`. Returns the same shape as av_data_code_mode_serverless: { stdout, stderr, exit_code, downloadUrl? }.