resolve_reference
Resolve an unknown freight identifier such as UN numbers, ports, container codes, or Incoterms into ranked, typed, and cited candidates when the token's entity type is unclear.
Instructions
Resolve an arbitrary freight identifier — one opaque string in, typed and cited candidates out. Use when you hold one identifier-ish token ("176", "UN1845", "NLRTM", "FOB", "22G1", "MSKU1100810", "D/E") and do not know what kind of identifier it is: each candidate names its entity type and carries the api_url and canonical_url of its full record.
Provide q: ONE identifier (single token, max 32 chars). Fourteen grammars all run — UN numbers, AWB prefixes, airline IATA/ICAO, airport IATA/ICAO, UN/LOCODE, ISO 6346 container numbers (check digit computed), HS codes (6-10 digits; national lines resolve at their 6-digit international parent), Incoterms, ADR tunnel codes, ADR Table A codes (special provisions, packing instructions and their PP/B/L provisions, MP, T/BK/TP, tank codes, TU/TC/TE/TA/TT/TM, V/VC/AP/CV/S, vehicle designations, labels, hazard identification numbers — e.g. "TU9" → its meaning, section and review status; a well-formed code no Table A row carries, e.g. "P999", is pattern_only), ULD serials, ISO container size/type codes. Ambiguity is the product: colliding grammars return MULTIPLE ranked candidates ("LHR" is Heathrow AND an Egyptian carrier's ICAO; "336" is an ADR special provision AND a hazard identification number), never a silent guess.
Behavior: deterministic — normalize (trim, uppercase, collapse spaces/dashes, strip a UN prefix), match ALL grammars, rank by record-hit > verification status > static dataset prior (airlines/adr/unlocode first) > stable tiebreak; every candidate carries rank_basis so the ordering is inspectable. Zero candidates is a VALID result (count 0 + note), never an error. A failed container check digit returns a candidate with valid:false rather than dropping it. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets.
Returns: query, normalized, count and candidates[] — each with entity_type, identifier_type, value_normalized, summary, record (the core fields the matching dataset holds), verification_status + verification_basis, rank_basis, canonical_url, api_url and a per-candidate dataset citation — under result, plus confidence, _source and citation (the FreightUtils v1 response envelope).
Limitations: v1 is SINGLE-TOKEN resolution, not free-text extraction — pass one identifier, not a manifest line; SCAC/BIC codes are not yet covered; a match asserts the identifier is known/well-formed, not that a shipment exists.
Related: every lookup tool this resolves into — adr_lookup, airline_lookup, airport_lookup, unlocode_lookup, hs_code_lookup, incoterms_lookup, container_lookup, uld_lookup, validate.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | One freight identifier — e.g. "176", "UN1845", "NLRTM", "FOB", "LHR", "22G1", "MSKU1100810", "090111", "AKE12345AB", "D/E", "TU9". |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ok | Yes | ||
| _meta | No | ||
| as_of | No | ||
| result | Yes | ||
| status | No | ||
| _source | Yes | ||
| edition | No | ||
| citation | Yes | ||
| validity | No | ||
| warnings | No | ||
| confidence | Yes | ||
| missing_inputs | No | ||
| blocking_errors | No | ||
| envelope_version | Yes | ||
| normalized_input | No |