Reference Data

Resolve any freight identifier to typed, ranked, cited candidates

The agent front door: one identifier-ish string in, typed candidates out. 13 grammars all run (UN numbers, AWB prefixes, airline/airport IATA+ICAO, UN/LOCODE, ISO 6346 container numbers with check digit, HS codes, Incoterms, ADR tunnel codes, ULD serials, ISO container types). Envelope v1.1 native.

get/api/resolve

Request

  • Base URL: https://www.freightutils.com
  • URL: https://www.freightutils.com/api/resolve
  • Auth: none declared

Query parameters

qstring required

One freight identifier (single token, max 32 chars). Collisions return multiple ranked candidates; zero candidates is a valid count:0 result, never an error.

Response

Envelope v1.1 (native — always enveloped; ?envelope=1 downgrades to the byte-stable v1 envelope). result carries query, normalized, count and candidates[]; count 0 + note means no grammar matched. A 5-character query one character from a real UN/LOCODE adds did_you_mean[] ({value, label, api_url}).

okboolean required
envelope_version'1' | '1.1' required
confidenceobject required

high/deterministic when candidates exist; low/deterministic with a NO_MATCH warning when none do.

normalized_inputobject

Present when normalization changed the query (lowercase, spacing, dashes, UN prefix): q_input + normalized.

citationobject required

Top-level one-line citation for the resolution itself; per-candidate dataset citations live on each candidate.

Example response

{
  "result": {
    "candidates": [
      {
        "entity_type": "airport",
        "identifier_type": "airport_iata",
        "value_normalized": "LHR",
        "summary": "London Heathrow Airport — London, United Kingdom",
        "verification_status": "verified",
        "canonical_url": "/adr/un/1845",
        "api_url": "/api/airports?iata=LHR"
      }
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.