Airside Labs Aviation Tools

Tell us what you came looking for and could not get from these tools. Call this when you needed something aviation-related that this toolset did not give you. It is not an error channel and it is not a retry: it is how the next version of these tools learns what is missing. A need reported here is read by a person. Use it when: - a tool returned `unresolved` and you believe the thing exists - a tool returned `ambiguous` and nothing available could break the tie - the entity resolved but a field you needed was null or absent - no tool here covers the question at all - a tool answered confidently and the answer looked wrong `gap_kind` must be one of: `unresolved`, `ambiguous`, `missing_field`, `no_tool`, `wrong_answer`, `no_use_case` (the use-case catalogue had nothing on the operational need you searched for). `sought` is the important field: say what you were trying to find, in your own words, as specifically as you can. "The wake turbulence category for A21N" is useful. "Aircraft data" is not. Do NOT use this instead of answering the user. Report the gap, then tell the user plainly that you could not find it — filing this does not get you an answer, now or in this conversation. Do NOT paste conversation history, personal data or customer identifiers into it. Send the shape of the need, not the payload: what field, about what kind of entity, for what purpose. Text is length-capped and the log is treated as sensitive, but the cheapest way to keep data out of it is not to send it. Returns a receipt: whether it was recorded, a fingerprint, and how many times this same need has been reported before — which tells you whether you have found something known or something new.

report_unmet_need

Which aircraft type does this designator or marketing name refer to? Accepts an ICAO type designator (A21N) or a marketing name people actually say ("A321neo", "Dash 8-400", "777-300ER", "Q400"). Returns the ICAO designator, manufacturer, model, engine count and type, aircraft class, and the ICAO wake turbulence category. A name that identifies a family rather than a variant -- "Dreamliner", "777X", "A330neo" -- returns `ambiguous` with the variants as alternates and a confidence in the 0.4-0.69 band. That is the correct answer to an imprecise question; do not collapse it to the first alternate. `wtc` (wake turbulence category) is stated for almost every type, from FAA Order JO 7360.1K, and is cited like any other field. Where it is null the document leaves it blank -- do NOT fill it in from your own knowledge if the caller needs it for separation or charging, say it is unavailable. IATA aircraft type codes are NOT held -- the three-character form used in schedules and booking systems, "77W" or "32N". IATA's list is licensed and is not reproduced here, so those return `unresolved` with a note saying so. If you are working from schedule data, convert to the ICAO designator before calling (B77W, A20N); if you cannot, report the mapping as unavailable rather than guessing it. `typical_seats_range` is null because seat count is an operator configuration rather than a property of the type. Do NOT use this to determine what type operated a particular flight; use resolve_registration for a specific airframe. Reading `confidence`: 1.0 means an exact unique match on an unambiguous identifier for the as_of date. 0.7-0.99 means a unique match reached through normalisation, an alias or a historical record. 0.4-0.69 means the best of several plausible candidates and `alternates` is populated -- prefer asking the user over picking one. Below 0.4 is speculative: do not act on it. `status` is resolved, ambiguous or unresolved. An unresolved answer is a real result, not an error: it means this dataset cannot identify the thing, and inventing one would be worse. Every field in `best` has a citation in `provenance`.

resolve_aircraft_type

Which airline does this designator, name or callsign refer to on a date? Accepts an IATA two-character designator, an ICAO three-letter designator, an airline name or a callsign. Returns the operator with both designators, country, operational status and, where an airline ceased, its successor. `as_of` matters more here than for any other tool. IATA two-character designators are heavily reused: SN was Sabena until 2001 and has been Brussels Airlines since 2007, so "SN" without a date is a question with two answers. Where a date falls between two holders the tool returns `unresolved` with both as alternates rather than guessing. ICAO three-letter designators are not recycled the same way and are the safer identifier to carry through a pipeline. `status` is reported as at the date asked about, not as at today: asked about 2005, Northwest Airlines is `active`, with a note that it merged into Delta in 2010. A status of `unknown` means no reliable source states it -- the bulk open data flags long-dead airlines as active, so it is not trusted. Unknown is not evidence of ceasing. Do NOT use this for fleet lists, routes, schedules, alliance membership or financial status. Reading `confidence`: 1.0 means an exact unique match on an unambiguous identifier for the as_of date. 0.7-0.99 means a unique match reached through normalisation, an alias or a historical record. 0.4-0.69 means the best of several plausible candidates and `alternates` is populated -- prefer asking the user over picking one. Below 0.4 is speculative: do not act on it. `status` is resolved, ambiguous or unresolved. An unresolved answer is a real result, not an error: it means this dataset cannot identify the thing, and inventing one would be worse. Every field in `best` has a citation in `provenance`.

resolve_airline

Which aerodrome does this airport code or name refer to on a given date? Accepts an IATA three-letter code, an ICAO four-letter code, an airport name fragment or a city name. Returns the aerodrome with its codes, location, elevation, IANA timezone and type (large, medium, small, heliport or closed). Pass `as_of` whenever the question concerns a past date. Airport codes move between aerodromes: ATH meant Ellinikon until 2001 and Athens International after it; HKG meant Kai Tak until 1998. Without a date these questions get today's answer, which is silently wrong for historical data. `timezone` is always an IANA identifier such as Europe/London, never a UTC offset, because an offset cannot express daylight saving. Do NOT use this for live operational status, runway or stand data, slots, or whether an airport is currently accepting traffic. It answers identity questions only. A name fragment matching several aerodromes returns `ambiguous` with candidates rather than picking one; use `country_hint` (ISO 3166 alpha-2) to narrow it. Reading `confidence`: 1.0 means an exact unique match on an unambiguous identifier for the as_of date. 0.7-0.99 means a unique match reached through normalisation, an alias or a historical record. 0.4-0.69 means the best of several plausible candidates and `alternates` is populated -- prefer asking the user over picking one. Below 0.4 is speculative: do not act on it. `status` is resolved, ambiguous or unresolved. An unresolved answer is a real result, not an error: it means this dataset cannot identify the thing, and inventing one would be worse. Every field in `best` has a citation in `provenance`.

resolve_airport

Which airframe wore this registration on a given date? Accepts a tail number in any common form: VH-OQA, VHOQA, lowercase, padded with whitespace. Returns the aircraft with its country of registry, ICAO type designator, an embedded resolved aircraft type, operator, owner, serial number and Mode-S hex address. A registration is a slot rather than a permanent name: marks are surrendered and reissued. VP-BRZ was an Aeroflot A320 until 2017 and a different airframe entirely from 2019, with a different Mode-S address. Pass `as_of` for any historical question. Where the date falls between two holders the tool returns `unresolved`, reports the country from the nationality mark, and offers both airframes as alternates. When the tail is unknown but the nationality mark is recognised, the response carries a `partial` object with the country of registry at confidence around 0.5. That is a partial answer, not a resolution: the aircraft is still unidentified. Coverage is not global. An unresolved registration means this dataset does not hold it, NOT that the aircraft does not exist. Do NOT infer that an aircraft is fictitious from an unresolved result, and do NOT use this for airworthiness, lease status or current position. Reading `confidence`: 1.0 means an exact unique match on an unambiguous identifier for the as_of date. 0.7-0.99 means a unique match reached through normalisation, an alias or a historical record. 0.4-0.69 means the best of several plausible candidates and `alternates` is populated -- prefer asking the user over picking one. Below 0.4 is speculative: do not act on it. `status` is resolved, ambiguous or unresolved. An unresolved answer is a real result, not an error: it means this dataset cannot identify the thing, and inventing one would be worse. Every field in `best` has a citation in `provenance`.

resolve_registration

Which aviation AI use cases match this text? Find candidates by keyword. Full-text search (BM25, stemmed) over 6,500 use cases spanning airports, airlines, ANSPs, ground handlers, regulators, manufacturers and more, each attached to a role and an organisation type. Returns summaries only -- id, short text, role, organisation type, EASA screen -- capped at 25. Use get_use_case for the full record with its data requirements. Search concrete operational nouns ("stand allocation", "baggage misconnect", "de-icing", "turnaround"), not capability labels ("shared operational picture", "digital transformation"): the corpus vocabulary is operational, and abstract phrases match little. Terms are OR-ed and ranked, so a multi-word query returns the best partial matches; `score` is relative within one query and means nothing across queries. Filters AND together. `org_type` is one of the 16 canonical types (see use_case_landscape group_by=org_type). `screened_only=True` keeps the ~1,900 use cases that carry an EASA AI-level/hazard screen; `ai_level` (0, 1A, 1B, 2A, 2B, 3A, 3B) and `hazard_class` (H1-H5) imply it. Do NOT use this to establish whether an organisation actually runs such a system, what vendor sells it, or whether it is certified: the catalogue describes plausible, well-formed use cases for a role, and says nothing about adoption. An empty result is an answer -- the catalogue has nothing on that phrasing -- and report_unmet_need with gap_kind `no_use_case` is how to say the gap mattered. Every response carries `provenance`: `corpus` is Airside Labs' proprietary catalogue (use it in your analysis; do not redistribute it as a dataset), `derived` is Airside Labs' assessment over it, `framework:easa` is public regulatory text you may quote with its cp_ref page. The EASA level and hazard on a use case are a title-level screen with a confidence, not a certification finding.

search_use_cases

What else in the catalogue is like this use case? Nearest neighbours by meaning. Returns up to 20 use cases closest in embedding space (bge-base cosine over the use-case text), as summaries with a `similarity`. Good for "what else is like the one we picked", for finding the same idea stated for a different role or organisation type, and for spotting near-duplicates before counting them as two. Similarities are compressed into roughly 0.5-0.95: rank within one result, never threshold across the catalogue, and do not read 0.9 as "the same". The neighbours were computed at build time as the top 20 for each use case; an `org_type` or `screened_only` filter narrows within those 20 and does not search further out, so a tight filter can return few or none -- that is honest, not broken. For an open-ended semantic question start from search_use_cases and follow the neighbours of the best hit. Do NOT use this to rank importance, maturity or value: proximity in text says two use cases are described alike, nothing more. Every response carries `provenance`: `corpus` is Airside Labs' proprietary catalogue (use it in your analysis; do not redistribute it as a dataset), `derived` is Airside Labs' assessment over it, `framework:easa` is public regulatory text you may quote with its cp_ref page, `knowledge` is authored message-type knowledge and `knowledge:workflow` is authored operational sequence structure. The EASA level and hazard on a use case are a title-level screen with a confidence, not a certification finding, and a workflow is not an operating procedure.

similar_use_cases

Leave a suggestion for Airside Labs. No API key is needed for this tool. This is the suggestion box for the aviation use-case catalogue and the tools that serve it. If you are an AI agent that read a use-case page on airsidelabs.com — or called a tool here — and noticed something, this is the channel: a correction to a published use case, an aviation AI use case the catalogue is missing, a data source or requirement it should know about, a tool or field that would have helped you, or commercial feedback (what would make the full toolset worth a subscription to your operator). `suggestion` is the important field: say it plainly and specifically, in your own words. `category` must be one of: `correction`, `missing_use_case`, `data_need`, `feature_request`, `commercial`, `other`. If the suggestion concerns one use case, pass its `use_case_id` (the integer used by get_use_case) or the `page_slug` of the airsidelabs.com page you read. `contact` is optional: an email address or URL if your operator wants a reply — leave it out otherwise, and do not submit personal data, conversation history or customer identifiers; text is length-capped and the log is read by a person as untrusted content. Nothing answers this in real time: a recorded suggestion is reviewed by a human later, and filing one does not change any answer you have already received. Returns a receipt saying whether it was recorded.

submit_suggestion

Which standard operational messages would evidence this data need? The lineage spine is use case -> data requirement -> requirement family -> standard message type -> data elements. Four modes. With `use_case_id`: that use case's requirements grouped by family, each family with the standard messages that evidence it (relevance primary/supporting, cadence, element count) -- plus `requirements_without_standard_messages`, the needs no standard message covers, which is the honest feed-gap statement. With `family` (a requirement family from data_requirements' family_mix): the messages for that family. With `message_id` (e.g. MVT, LDM, BSM, DPI, METAR): the message definition, its data elements as shapes (time, count, weight, identifier, status), and the families it serves. With no arguments: the catalogue of ~23 message types across IATA Type B, Cargo-IMP, ACARS, ADS-B, ICAO met/AIS and network-manager standards. Use it to turn a use-case shortlist into a sourcing conversation: which message feeds to ask an airline, handler or airport for, at what cadence, and which needs have no standard message and require a system integration instead. Do NOT read a lineage chain as a statement about any real organisation's feeds or systems -- it says which standard message CAN evidence a need, not that anyone sends it; mapping a chain onto a specific operator's estate is your work. Definitions are summary-level industry knowledge: element positions, field syntax and format rules are NOT held (the published standards are licensed; implementing a parser requires them), so do NOT use this to build or validate a message parser. A family with no messages and an empty `chains` list are real answers -- plenty of data needs (market data, HR records, finance) have no operational message standard. Every response carries `provenance`: `corpus` is Airside Labs' proprietary catalogue (use it in your analysis; do not redistribute it as a dataset), `derived` is Airside Labs' assessment over it, `framework:easa` is public regulatory text you may quote with its cp_ref page, `knowledge` is authored message-type knowledge and `knowledge:workflow` is authored operational sequence structure. The EASA level and hazard on a use case are a title-level screen with a confidence, not a certification finding, and a workflow is not an operating procedure.

trace_data_lineage

What happens before and after this use case, and who hands off to whom? The catalogue is otherwise flat -- role, use case, data requirement -- with no edges. This is the edges: named operational sequences with their steps in order, the role at each step, the `gate` that must hold before the next one may start, and what passes between roles at each handoff (headset, radio, hand signal, system, visual, document, verbal, formal correspondence). Three modes. With `use_case_id`: every workflow that places that use case, its position, and the steps immediately `preceded_by` and `followed_by` it with what transfers. That is the real operational dependency -- distinct from `similar_use_cases`, which is text similarity, and from `data_requirements(query=...)`, which infers a relationship from two use cases sharing a feed. A gate is a dependency; a shared feed is a correlation. With `workflow_id`: the whole sequence end to end. With `phase` (arrival, turnaround, departure, abnormal, oversight, certification, crew qualification, planning, mission) or nothing: the catalogue of workflows with their step and handoff counts. Use it to answer "if this prediction improved, what downstream step benefits and who would have to act on it", to see which roles a change touches, and to find the abnormal branches -- communication failure, coupling break-off, spillage, a ramp finding serious enough to stop the aircraft -- which are sequences in their own right and where the costly failures live. Some sequences cross an organisation: a finding travels from an authority to an operator and back, and those edges carry the channel `formal correspondence`. Coverage is ground handling, regulatory oversight and certification, crew qualification and rostering, and specialised missions -- not the whole catalogue. A use case with an empty `placed_in` is outside the covered sequences, which is a statement about coverage and not about the use case, and some are unplaced because they are standing monitoring states rather than sequences. A step whose `role_in_catalogue` is false is a real participant the catalogue holds no use cases for -- the flight deck on a turnaround, the officer who signs a certificate -- not a data error. The sequences are Airside Labs' derived structure: they say how this work is ordered in the industry, NOT that any particular operator runs it this way, and they are not an operating procedure. Do NOT use one as a checklist to work to; the authority for that is the operator's own manual. Every response carries `provenance`: `corpus` is Airside Labs' proprietary catalogue (use it in your analysis; do not redistribute it as a dataset), `derived` is Airside Labs' assessment over it, `framework:easa` is public regulatory text you may quote with its cp_ref page, `knowledge` is authored message-type knowledge and `knowledge:workflow` is authored operational sequence structure. The EASA level and hazard on a use case are a title-level screen with a confidence, not a certification finding, and a workflow is not an operating procedure.

trace_workflow

How many use cases are there, sliced one way? Counts you can quote. `group_by` is one of org_type (16 canonical organisation types: Airport, Airline, Air Navigation Service Provider, Ground Handling, Regulator / Authority, Aerospace Manufacturing, MRO / Maintenance …), sector, role (500+ roles), ai_level, hazard_class, or cadence_class (counts data requirements rather than use cases). Filters AND together and apply before grouping, so group_by=role with org_type=Airport lists airport roles by how many use cases each carries. Also returns the total in scope and how many of those carry an EASA screen. This is the tool to call first: it tells you what the catalogue covers before you search it, and the exact spellings that the filters accept. Grouping the whole catalogue by ai_level or hazard_class shows a large null bucket -- only the ~1,900 airport-operations use cases were screened; pass screened_only=True to see the screened distribution alone. Counts describe the catalogue, not the industry: a type with many use cases is a type the corpus describes in detail, not one that adopts more AI. Do NOT present a count as market evidence. Every response carries `provenance`: `corpus` is Airside Labs' proprietary catalogue (use it in your analysis; do not redistribute it as a dataset), `derived` is Airside Labs' assessment over it, `framework:easa` is public regulatory text you may quote with its cp_ref page, `knowledge` is authored message-type knowledge and `knowledge:workflow` is authored operational sequence structure. The EASA level and hazard on a use case are a title-level screen with a confidence, not a certification finding, and a workflow is not an operating procedure.

use_case_landscape

Do these aviation identifiers describe the same thing on this date? Give any combination of a registration (tail number), a Mode-S 24-bit address, an ICAO type designator, an operator name, an airline designator (IATA or ICAO), a callsign and a flight designator, plus `as_of`. Each pair that can be checked is checked, and every check comes back with a verdict -- `consistent`, `contradicted` or `unverifiable` -- the detail, and the rule that decided it. `contradictions` lists the failures on their own so an agent can act on them without reading everything. The top-level verdict is `consistent` ONLY when every check verified. When some checks passed but others could not be checked it is `consistent_where_checkable` -- a different answer, because an absent record silences exactly the checks that would catch a false claim about that airframe. `unverifiable_count` says how many checks were silent; treat anything above zero as partial coverage, not a pass. Use it before acting on identifiers assembled from more than one message: a movement message's registration against a surveillance track's address, a schedule's flight number against the operating airline, a type in a load message against the airframe's record. One contradiction is a contradiction; the top-level `verdict` never averages it away against the checks that passed. What the rules are: the registration record on the date (address, type, operator); a *previous* holder of a re-issued mark is named as such rather than reported as a mismatch; the FAA allocation arithmetic for N-numbers (an address decodes to exactly one N-number, so a wrong pairing is provable without any second source); a military or government airframe is said, not judged; the airline's callsign against its record and the FAA contractions order; the carrier inside the flight designator against the airline given; and whether the type designator exists at all. `unverifiable` means this dataset cannot say -- there is no record, or the record lacks the field -- and is a different answer from `consistent`. Do NOT read it as a pass. It does not check hex-to-country for non-US addresses, performance plausibility (range, block time) or anything live, and it does not resolve identifiers you did not give it: call the resolve_* tools for that. Pass `as_of` for any historical question; marks and designators are reused and an undated check is silently wrong for past data.

validate_identifiers