---
title: "Resolve any freight identifier to typed, ranked, cited candidates"
method: GET
path: "/api/resolve"
tags: ["Reference Data"]
---

# Resolve any freight identifier to typed, ranked, cited candidates

`GET /api/resolve`

## Request

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

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.

## Query parameters

- `q` string, required

## Response `200`

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}).

- ResolveResponse: Envelope v1.1 (native). result holds the resolution; each candidate carries its own dataset citation. Zero candidates is ok:true with count 0 and a note, never an error.
  - `ok` boolean, required
  - `envelope_version` '1' | '1.1', required
  - `result` object, required
    - `query` string, required
    - `normalized` string, required: After trim, uppercase, space/dash collapse and UN-prefix strip.
    - `candidates` ResolveCandidate[], required
      - `entity_type` string, required: What the candidate is: dangerous_good, airline, airport, location, hs_classification, incoterm, container_type, container_equipment, uld_type, tunnel_restriction.
      - `identifier_type` string, required: Which grammar matched: un_number, awb_prefix, airline_iata, airline_icao, airport_iata, airport_icao, unlocode, container_number, hs_code, incoterm, tunnel_code, uld_type, iso_container_type.
      - `value_normalized` string, required
      - `summary` string, required: One-line human summary of the candidate.
      - `record` object, nullable, required: Core fields from the matching dataset. Null for a pattern-only match (the value fits a grammar but is not in the served dataset).
      - `verification_status` string, required: Normalized across datasets: active_verified, verified, computed, partial, pending_verification, unchecked, unverified, historical, pattern_only.
      - `verification_basis` 'record' | 'dataset', required: record = from this record's own provenance fields; dataset = the dataset-level claim (no record-level signal exists).
      - `rank_basis` string, required: Why the candidate sits where it does: record hit > verification status > static dataset prior > stable tiebreak.
      - `canonical_url` string: The record's page on freightutils.com, where one exists. Omitted otherwise.
      - `api_url` string: The dataset's REST query for this record, where one exists.
      - `citation` object, required: The matching dataset's own citation for this record (text + optional qualifier).
        - `text` string, required
        - `qualifier` string
    - `count` integer, required
    - `note` string: Present only when count is 0: 'no known freight identifier grammar matched'.
  - `confidence` object, required: high/deterministic when candidates exist; low/deterministic with a NO_MATCH warning when none do.
  - `warnings` object[]: Advisory only. NO_MATCH is emitted on every count:0 response.
    - `code` string
    - `message` string
  - `normalized_input` object: Present when normalization changed the query (lowercase, spacing, dashes, UN prefix): q_input + normalized.
  - `blocking_errors` object[]: Present on the 400 branches only: MISSING_INPUT (no q) or INVALID_INPUT (over the 32-char single-token limit).
    - `code` string
    - `message` string
    - `recovery` object
  - `citation` object, required: Top-level one-line citation for the resolution itself; per-candidate dataset citations live on each candidate.
  - `_source` SourceEnvelope: Additive provenance citation for the dataset or method behind this response, from FreightUtils' single provenance source of truth. Shapes: reference, methodology (calculators), or reference with provenance_status:'pending-verification'. Fields appear only when a real value exists.
    - `type` 'reference' | 'methodology', required
    - `authority` string
    - `dataset` string
    - `source_url` string
    - `data_vintage` string
    - `licence` string
    - `retrieved_via` string
    - `standard` string
    - `reference` string
    - `computed_by` string
    - `provenance_status` 'pending-verification'
    - `dataset_edition` string: Edition this response is served from (editioned reference datasets only), e.g. 'UN/LOCODE 2025-1'.
    - `authority_current_edition` string: The authority's current in-force edition at the last check. Differs from dataset_edition only when the served data lags the authority.
    - `checked_at` string: YYYY-MM-DD of the last served-vs-authority edition comparison (on-demand checker, staleness-guarded).

## Other responses

- `400`: Missing or over-length q — enveloped blocking_errors (MISSING_INPUT / INVALID_INPUT). v1 takes ONE identifier; free-text extraction is out of scope.

---

[API](https://skmtc.dev/freightutils/apis/freightutils-api.md) · [All operations](https://skmtc.dev/freightutils/apis/freightutils-api/llms.txt) · [OpenAPI document](https://skmtc.dev/freightutils/apis/freightutils-api/revisions/6607bb3cea90?raw)