# FreightUtils — neutral freight reference + validation layer for AI agents

> FreightUtils — neutral freight reference + validation layer for AI agents. Every response cites its source: authority, edition, licence where held, and a verification status an agent can read. Deterministic tools, not generated answers. Reference only — never filing, booking, or legal advice; results state when human review is required.

Source-backed dangerous-goods, customs, location and freight-calculation data an agent can call and cite, from primary sources (ADR 2025 / UNECE, HS 2022 / WCO, IATA-regulated airline prefixes, UN/LOCODE, OurAirports). Neutral by design: no freight to sell, no carrier to push. 25 tools · 25 REST endpoints · 26 MCP tools. Built by a UK ADR-certified freight transport planner.

## Connect

- **MCP (Streamable HTTP):** `https://www.freightutils.com/api/mcp` — the 26 MCP tools for AI agents (legacy alias: `/api/mcp/mcp`).
- **Claude (claude.ai, Desktop, mobile, Cowork):** add FreightUtils from Claude's connector directory — https://claude.ai/directory/connectors/freightutils — or as a custom connector with the MCP URL above (https://www.freightutils.com/mcp#use-in-claude).
- **MCP (stdio):** npm package `freightutils-mcp` — for Claude Desktop / Cursor / Cline / local agents (`npx freightutils-mcp`). Version-agnostic — always resolves the latest published release.
- **REST:** base `https://www.freightutils.com/api` — 25 endpoints, JSON, CORS-enabled, no auth for anonymous use. OpenAPI 3.1 spec: https://www.freightutils.com/openapi.json
- **Custom GPT:** https://chatgpt.com/g/g-69fb8fdb0a5c819182c73f8d224cc3d0 — the FreightUtils GPT on the OpenAI GPT Store (backed by the same OpenAPI spec).
- **API key (optional):** `POST https://www.freightutils.com/api/keys/register`, then send the `x-api-key: <key>` header. Anonymous 25 requests/day per IP · free key 100 requests/day · Pro 50,000 requests/month (£19/mo).
- **Envelope 1.2 (REST, `?envelope=1.2`):** every answer states `status` (ok · partial · not_found · unsupported · ambiguous), `missing_inputs`, `edition` (name, applies_from, may_apply_until — ADR 2025 may still be applied until 2027-06-30) and `as_of` (the dataset's audited date). `ok` and every value are unchanged; `?envelope=1` / `1.1` are unchanged. The MCP tools answer with 1.2 too — the hosted endpoint and freightutils-mcp from 2.24.0 — refusals included. Schema: https://www.freightutils.com/schemas/response-envelope.v1.2.json
- **The consignment object:** one typed load description — `lines[]` (un_number, packing_group, variant_index, quantity {value, unit, basis}, packages {count, type, gross_kg}, hs_code, value {amount, currency}, dims, stackable), `journey` (origin, destination as UN/LOCODE or ISO country, date, tunnels_on_route, mode), `vehicle`, `options`. Send `{"consignment": {...}}` alone to POST /api/consignment, /api/shipment/summary or /api/adr-calculator (MCP: the `consignment` argument): same answer as the tool's own shape; a missing input is a 400 MISSING_INPUT naming its path in `missing_inputs`. POST /api/validate `{"type":"consignment","consignment":{...}}` checks it. Schema: https://www.freightutils.com/schema/consignment-object.v1.json
- **MCP scopes:** `https://www.freightutils.com/api/mcp/dg` (adr_lookup, adr_exemption_calculator, adr_lq_eq_check, validate, resolve_reference), `/api/mcp/customs` (hs_code_lookup, uk_duty_calculator, ics2_check, incoterms_lookup, validate), `/api/mcp/ops` (the calculators, equipment, locations, carriers, validate, resolve_reference). `/api/mcp` serves every tool, unchanged. A scope is a filter: same tools, schemas, answers, key and limits; scopes leave out get_subscribe_link. The npm package serves the same lists over stdio from 2.25.0: `npx freightutils-mcp --scope dg` (or customs, ops; also `FREIGHTUTILS_SCOPE`). Under envelope 1.2 a MISSING_INPUT refusal's `missing_inputs` names only the parameters the call lacked; a calculator's `null` means not computed for want of an input, never zero.
- **Batch inputs:** `/api/adr?un_numbers=`, `/api/unlocode?codes=`, `/api/airports?codes=`, `/api/airlines?codes=`, `/api/hs?codes=` (≤ 50, comma-separated) and POST /api/duty `{"lines":[...]}` (≤ 10); on MCP (hosted, and freightutils-mcp from 2.25.0) the array arguments `un_numbers`, `codes`, `lines`. Send alone. `results[]` in input order, each with its own `status`; the batch status is `ok` only when every item is, else `partial` with `not_found` / `unresolved` by index. One call against the daily limit, N against the Pro monthly allowance.
- **ADR editions:** the five tools that read ADR data — `/api/adr` (adr_lookup), `/api/adr-calculator` (adr_exemption_calculator), `/api/adr/lq-check` (adr_lq_eq_check), `/api/consignment`, `/api/shipment/summary` — take `edition` ("2025" | "2027") and `as_of` (YYYY-MM-DD); MCP the same arguments (hosted, and freightutils-mcp from 2.26.0). `edition` wins; otherwise `as_of` (default today, UTC) picks by the timeline: before 2027-01-01 ADR 2025 (unchanged answers); 2027-01-01 to 2027-06-30 ADR 2027 with an `EDITION_TRANSITIONAL` notice (ADR 2025 may still be applied, 1.6.1.1); from 2027-07-01 ADR 2027 only (`edition=2025` → `EDITION_UNSUPPORTED`). ADR 2027 is accepted and applies from 2027-01-01; before that an ADR 2027 answer carries `EDITION_NOT_YET_APPLICABLE`. Answers on a named edition carry `adr_edition`; under ADR 2027 the 1.1.3.6 answer carries `transitional_1_6_1_61` (the ADR 2025 note-a basis, ×20 / 50 kg, for UN 0081, 0082, 0084, 0241, 0331, 0332, 0482, 1005, 1017, until 2030-12-31) beside the verdict, UN 2372 carries `transitional_notes[]` (1.6.3.64 / 1.6.4.70), UN 2941 answers not_found (deleted). UN 2348 / 2862 PG III is variant_index 1 under ADR 2027 — send packing_group. https://www.freightutils.com/api-docs#adr-editions
- **Check receipts:** stored only for calls made with an API key — a free key is enough (POST /api/keys/register); a call without a key gets the receipt hash in the answer (`X-FreightUtils-Receipt-Hash`; `_meta.receipt` with `stored: false`, the hash and the hashed fields, recomputable from the answer; typed in freightutils-mcp from 2.26.0) and nothing is stored, so there is no check_id to retrieve; a free key stores 25 receipts a day (from the 26th check that day `_meta.receipt` with reason `quota`, nothing stored; Pro: no daily receipt limit); GET /api/receipts/{check_id}/verify gives anyone holding the id `{ exists, schema_version, receipt_hash, created_at, tool, edition }` and nothing else, no key needed. An answer of the seven check tools (adr_exemption_calculator, adr_lq_eq_check, uk_duty_calculator, consignment_calculator, shipment_summary, ics2_check, adr_consignment_check) to a keyed call carries a `check_id` and `receipt_url` — headers `X-FreightUtils-Check-Id` / `X-FreightUtils-Receipt` on REST, `_meta.check_id` / `_meta.receipt_url` under `?envelope=1.2` and in MCP structuredContent (hosted, and typed in freightutils-mcp from 2.25.0). GET /api/receipts/{check_id} (`?format=text` for a summary) returns the inputs as consumed, edition, data hashes, rules and citations, result, unresolved items, `not_proven` and `receipt_hash`, for 90 days. Each check's 1.2 answer and receipt name the edition it rested on (`edition` + `as_of`; ADR checks: ADR 2025 with its dates; duty: the UK Trade Tariff, live; ICS2: the stop-word list version), or `edition: null` with `_meta.edition_basis` "no regulatory dataset read". Receipts from 30 Oct 2026 are `receipt.v2` (as_of and edition_basis inside the hash). Never names, addresses, keys, IPs or free text over 200 characters. Lookups carry none.
- **Anonymous answers say so:** a call without a key carries an `X-FreightUtils-Identify` response header (one sentence: the anonymous limit, what a free key changes, how to label your calls) — in the body as `_meta.identify` only under `?envelope=1.2`; keyed calls never do. Optional label: `?client=<your-app>` or the `X-FreightUtils-Client` header (up to 40 characters of `A-Za-z0-9._-`) — it changes no answer, and every route accepts it. Free-text searches (`/api/adr?search=`, `/api/airlines?q=`, `/api/airports?q=` and their MCP tools) take at most 200 characters; a longer one is refused with a 400.

## Tools

Each tool is a deterministic REST endpoint (and an MCP tool of the same capability) returning JSON with a `_source` citation. Listed as the capability an agent searches for.

### Freight calculators

- [LDM Calculator](https://www.freightutils.com/ldm) — `GET /api/ldm` — loading metres for road trailers: pallet presets (euro / uk / half / quarter) or custom dimensions, EU + US vehicles, stacking, utilisation + fit check.
- [CBM Calculator](https://www.freightutils.com/cbm) — `GET /api/cbm` — cubic metres for sea + air freight, with cubic-feet / litres / container-fill equivalents.
- [Chargeable Weight](https://www.freightutils.com/chargeable-weight) — `GET /api/chargeable-weight` — air / sea chargeable weight: volumetric vs actual, settable IATA divisor (default 6000).
- [Pallet Fitting](https://www.freightutils.com/pallet) — `GET /api/pallet` — how many boxes fit a pallet: layers, 90° rotation, height + weight limits.
- [Container Capacity](https://www.freightutils.com/containers) — `GET /api/containers` — ISO 668 / 1496 specs for 10 container types + box-loading calculation.
- [Unit Converter](https://www.freightutils.com/convert) — `GET /api/convert` — freight weight / volume / length conversions, including CBM → chargeable kg and CBM → freight tonnes.
- [Consignment Calculator](https://www.freightutils.com/consignment-calculator) — `POST /api/consignment` — multi-item mixed consignment: per-line + grand-total CBM, LDM, volumetric and mode-specific chargeable weight (sea / air / road) + advisory flags.
- [Emissions Calculator](https://www.freightutils.com/emissions) — `GET /api/emissions` — ISO 14083 / GLEC distance-based CO2e estimate; returns the exact factor + authority + edition (DEFRA 2026 / EPA / ADEME), WTW + TTW, and flags low representativeness (sea / air). Estimate, not an audited report.

### Dangerous goods (ADR 2025, UNECE)

- [ADR Lookup](https://www.freightutils.com/adr) — `GET /api/adr` — UN number → the full ADR 2025 Table A entry, all 20 columns as codes: name, class, packing group, labels, special provisions, LQ/EQ, packing and tank instructions, carriage provisions, transport category, tunnel code, hazard identification number (UNECE).
- [ADR Table A codes](https://www.freightutils.com/adr/codes) — `GET /api/adr/codes`, `GET /api/adr/codes/{family}/{code}` — what each code in Table A columns (5)–(20) means (special provisions, packing instructions, tank codes decoded, TU/TC/TE, V/VC/AP/CV/S, labels, hazard numbers), in FreightUtils' own words from ECE/TRANS/352, cited to section and page, each with its `verification_status` (unreviewed paraphrases say so): `paraphrase_unreviewed`, `machine_reviewed`, `contested`, `owner_reviewed`, `dg_reviewed`, `needs_fix`, or `verified` on the transport category and tunnel code entries (typed in freightutils-mcp from 2.28.0). On `/api/adr` as `resolved_codes` beside `results` — each code once per answer, with the `rows` and `columns` that carry it (`include_codes=none|compact|full`; compact has no `url`: a code's page is https://www.freightutils.com/adr/codes/{family}/{code}; MCP `adr_lookup` the same argument); `resolve_reference` resolves a code such as TU9.
- [ADR Exemption Calculator](https://www.freightutils.com/adr-calculator) — `GET /api/adr-calculator` — ADR 1.1.3.6 transport-category points vs the 1,000-point threshold (single or mixed load). An ID-prefixed line (ID 8000) counts out only with `icao_limited_quantity: true` (POST items; else `BLOCKED`); an item quantity of 0 is not carried (`EXCLUDED_NIL`); a gross mass on an entry counted by mass is an upper bound (`figure_basis: "upper_bound_gross"`); ADR 2027 answers carry `basis`, and on a stated `as_of` a transitional basis that clears the load comes with `basis_until` and `strict_adr_2027`; a line whose entry is deleted in ADR 2027 (UN 2941) is answered on 1.6.1.1 inside its window, `strict_adr_2027.entry_deleted` and `items[].edition_basis` saying so. MCP `adr_exemption_calculator` the same (hosted, and freightutils-mcp from 2.28.0; the two deletion fields typed from 2.29.0).
- [ADR LQ/EQ Check](https://www.freightutils.com/adr/lq-eq-checker) — `POST /api/adr/lq-check` — Limited Quantity (3.4) / Excepted Quantity (3.5) eligibility for one or more UN numbers.
- [ADR Consignment Check](https://www.freightutils.com/api-docs#consignment-check) — `POST /api/adr/consignment-check` — one call on the consignment object: the 1.1.3.6 verdict, LQ/EQ per line, the whole-load tunnel code against the route (8.6.3 / 8.6.4), the 5.4.1.1.1 document entries, mixed loading (7.5.2 by label and by Class 1 compatibility group; 7.5.4 foodstuffs for CV28 goods, optional `vehicle.foodstuffs_carried`) and the vehicle side — plates and placards (5.3), documents, fire extinguishers and equipment (8.1), driver training (8.2) — each listing the requirements the load puts on the vehicle and checking them against optional `vehicle.*` / `crew.*` inputs (without them a dangerous-goods load is conditional); `result.status` pass | fail | conditional | insufficient_data (fail = a check the load does not meet; a relief that does not apply — a load outside 1.1.3.6, or a line with no stated regime that fits neither LQ nor EQ — is `not_applicable` and does not change the status) and `result.regime` ("1.1.3.6" | "full_adr" | "undetermined": the rules the checks answered under), with `missing_inputs` and page-cited `checks_performed`; and the UN packaging mark (6.1.3.1: optional `packages.un_mark` read field by field, its X / Y / Z letter held against the line's packing group; no mark is conditional; the packaging kind is not checked). An LQ / EQ line whose stated regime is met is left out of the 1.1.3.6 total (1.1.3.6.5, `exemption_1_1_3_6.engine.excluded_lines`). MCP `adr_consignment_check` the same (hosted, default list and `dg` scope, and freightutils-mcp since 2.29.0; in 2.34.0, the current version, it takes the `vehicle.*` and `crew` inputs and `packages.un_mark`, and names the vehicle side, the packaging check and `result.regime`).

### Customs & trade

- [HS Code Lookup](https://www.freightutils.com/hs) — `GET /api/hs` — Harmonized System tariff codes (HS 2022, WCO): search by product description or code.
- [Incoterms 2020](https://www.freightutils.com/incoterms) — `GET /api/incoterms` — all 11 rules with risk / cost transfer points; any-mode vs sea-only.
- [Incoterms 2020 quick reference chart](https://www.freightutils.com/incoterms/chart) — one-screen matrix: risk, cost, insurance, export/import clearance for all 11 rules.
- [UK Duty & VAT](https://www.freightutils.com/duty) — `POST /api/duty` — UK import duty + VAT estimate on live GOV.UK Trade Tariff data (CIF basis, preference rates).
- [ICS2 Stop-Words Checker](https://www.freightutils.com/ics2-check) — `GET /api/ics2-check` — flags EU ICS2 stop-words in an ENS goods description (EU CIRCABC list, in-force version). Reference only — a clean result ≠ acceptance.

### Reference data

- [Airline Codes & AWB Prefixes](https://www.freightutils.com/airlines) — `GET /api/airlines` — airline by IATA / ICAO code, AWB prefix, callsign or country (IATA-regulated prefixes). Every prefixed record says whether its prefix is shared (`prefix_shared`, `prefix_holders`); cargo records say whether the carrier operates and on what basis (`operational_status` + `operational_status_basis`: the carrier's own page, or its ICAO designator in the current FAA Order JO 7340.2), whether the EU or UK Air Safety List names it (`restrictions[]`, a flag with the regulation and date), and carry carrier-published cargo, AWB-tracking and dangerous-goods links where the carrier publishes them. MCP `airline_lookup` the same (hosted, and typed in freightutils-mcp from 2.27.0).
- [UN/LOCODE Lookup](https://www.freightutils.com/unlocode) — `GET /api/unlocode` — UN/LOCODE transport locations (ports, airports, rail, road, ICDs) by name, code, country or function.
- [Airport Code Lookup](https://www.freightutils.com/airports) — `GET /api/airports` — airport by IATA / ICAO code, name or city (OurAirports, public domain) → full record incl. coordinates and elevation.
- [ULD Types](https://www.freightutils.com/uld) — `GET /api/uld` — air-cargo ULD specs (AKE / LD3, PMC, …): dimensions, weights, aircraft compatibility, deck position.
- [Vehicle & Trailer Types](https://www.freightutils.com/vehicles) — `GET /api/vehicles` — road freight vehicles / trailers (EU + US): internal dimensions, payload, pallet capacity.
- [Identifier Validator](https://www.freightutils.com/validate) — `GET /api/validate` — paste ANY text (a booking line, an email) and it finds + check-digit-validates every ISO 6346 container, IATA AWB, and IMO number in it; or validate a single identifier by type. Structural (check-digit) validation — not a registry lookup. A failed identifier says why in `failure.reason` (INVALID_CHECK_DIGIT, WRONG_LENGTH, BAD_CHARSET; UNKNOWN_PREFIX / AMBIGUOUS for an AWB's airline; UNSUPPORTED_TYPE); `/api/resolve` carries the same check as `validation` on an AWB, container or IMO number, and `failure` (NO_MATCH / AMBIGUOUS). MCP `validate` / `resolve_reference` the same (hosted, and typed in freightutils-mcp from 2.27.0).

### API / MCP-only (no dedicated page)

- Shipment Summary — `POST /api/shipment/summary` — composite: chains CBM + chargeable weight + LDM + ADR compliance + UK duty in one call, per transport mode.
- Nearest Airport — `GET /api/nearest-airport` — nearest airports to a caller-provided latitude / longitude by great-circle distance (coordinates are input only, never stored or logged). By default only airports with scheduled airline service and an IATA code (no heliports); `include_all=true` lists every type; the answer states `distance_basis` and the `filter` applied. MCP `nearest_airport` takes `include_all` (hosted, and freightutils-mcp from 2.27.0).
- Resolve Reference — `GET /api/resolve?q=` — resolve any freight identifier ("176", "UN1845", "NLRTM", "FOB") to typed, ranked, cited candidates across all datasets; 13 grammars all run, ambiguity returned rather than guessed. The agent front door.
- `get_subscribe_link` (MCP only) — returns the FreightUtils Pro upgrade URL + tier metadata; agents hand the URL to the user and never attempt checkout.

## Agent-safety contract

- **Every response cites its source.** A `_source` block on every REST + MCP response carries the authority, edition/version, source URL, licence and — for computed tools — the method; emission factors also carry a `last_verified` date. Datasets still finishing a provenance audit carry `provenance_status: "pending-verification"` and assert no licence.
- **Edition-aware.** Reference data names its edition (ADR 2025, HS 2022, Incoterms 2020, ICS2 in-force list date) so an agent can tell the user exactly which version it answered from.
- **Data licensing, as each publisher states it.** ADR 2025/UNECE (factual compilation, no named open licence), HS 2022 descriptions from UN Comtrade H6 (UN Statistics Division; no named open licence), UN/LOCODE (© UNECE, CC BY 4.0, as UNECE states for UN/CEFACT standards), GOV.UK Trade Tariff (OGL v3.0), OurAirports (public domain), airline codes compiled by FreightUtils from public sources (not published or endorsed by IATA or ICAO); emission factors DEFRA (OGL v3.0) / EPA (US-Gov public domain) / ADEME (Base Empreinte terms of use). Licensed source texts (IATA / IMDG) are never reproduced.
- **Explicit boundaries — what a clean/valid result does NOT mean:**
  - `validate` is **structural**: a valid check digit means the identifier is well-formed, NOT that the container / shipment / vessel exists or is active. It is not a registry or tracking lookup.
  - `ics2_check` clean means **no listed stop-word found**, NOT that an ENS will be accepted (the list is non-exhaustive and dynamic). It is not an ENS filing or a compliance determination.
  - `emissions_calculator` returns a **best-effort estimate** from published factors, NOT an audited carbon report; sea / air are low-representativeness screening defaults.
  - Reference and calculation only — never filing, booking, or legal advice. Results state when human review is required.

## Reference guides

- [ADR Tunnel Codes](https://www.freightutils.com/adr/tunnel-codes) · [ADR Limited Quantities](https://www.freightutils.com/adr/limited-quantities) · [ADR 2025 Changes](https://www.freightutils.com/adr/changes-2025) · [ADR Training Guide](https://www.freightutils.com/adr/training-guide)
- [What a freight reference tool changes for an agent](https://www.freightutils.com/guides/agent-builders-eval): the public eval written up for agent builders — models alone, with the FreightUtils tools and with web search; every figure from the pinned results. [All guides](https://www.freightutils.com/guides) · [Eval results](https://www.freightutils.com/eval)

## Platform

- [API Documentation](https://www.freightutils.com/api-docs): the 25 REST endpoints, MCP setup, and worked examples. JSON, CORS, no auth for anonymous use.
- [OpenAPI 3.1 Specification](https://www.freightutils.com/openapi.json): machine-readable spec — OpenAI Custom GPT Actions, Postman, Swagger.
- [Playground](https://www.freightutils.com/playground): try every endpoint live in the browser.
- [Pricing](https://www.freightutils.com/pricing): anonymous 25/day, free key 100/day, Pro £19/month for 50,000/month.
- [Long-form index (llms-full.txt)](https://www.freightutils.com/llms-full.txt) · [Changelog](https://www.freightutils.com/changelog) · [Status](https://www.freightutils.com/status)
- [npm: freightutils-mcp](https://www.npmjs.com/package/freightutils-mcp) · [npm: n8n-nodes-freightutils](https://www.npmjs.com/package/n8n-nodes-freightutils)

## About

- [About FreightUtils](https://www.freightutils.com/about): built by an ADR-certified UK freight transport planner.
- [For IT Departments](https://www.freightutils.com/for-it): hostnames, security posture, no-PII summary for whitelisting reviews.
- [Privacy Policy](https://www.freightutils.com/privacy) · [Terms of Service](https://www.freightutils.com/terms) · [Data Processing Agreement](https://www.freightutils.com/dpa)

## Optional

- [Roadmap](https://www.freightutils.com/roadmap) · [API Versioning Policy](https://www.freightutils.com/docs/versioning) · [Deprecation Policy](https://www.freightutils.com/docs/deprecation)