FreightUtils Reference API

openapi: 3.2.0
info:
  title: FreightUtils Reference API
  description: 'The neutral freight reference layer for AI agents: reference and calculation APIs for dangerous goods, customs, locations and freight math that agents can call and cite. No freight to sell, no carrier to push. Anon 25/day per IP, free key 100/day, Pro 50k/month — freightutils.com/pricing.'
  version: 1.0.0
  contact:
    name: FreightUtils
    url: https://www.freightutils.com
    email: contact@freightutils.com
  license:
    name: Free to use
    url: https://www.freightutils.com/api-docs
servers:
- url: https://www.freightutils.com
  description: Production
security:
- {}
- ApiKeyHeader: []
- BearerAuth: []
tags:
- name: Reference
paths:
  /api/unlocode:
    get:
      summary: UN/LOCODE transport location lookup
      description: Search 116,000+ UN/LOCODE entries by name, code, country, or function type.
      operationId: searchUnlocode
      tags:
      - Reference
      parameters:
      - name: q
        in: query
        description: Name or code search; the spaced notation "GB LHR" reads as GBLHR.
        schema:
          type: string
        example: rotterdam
      - name: code
        in: query
        description: Exact 5-character UN/LOCODE, e.g. GBLHR; "GB LHR" is accepted.
        schema:
          type: string
        example: NLRTM
      - name: country
        in: query
        description: ISO 2-letter country
        schema:
          type: string
        example: GB
      - name: function
        in: query
        description: Function type
        schema:
          type: string
          enum:
          - port
          - airport
          - rail
          - road
          - icd
          - border
      - name: limit
        in: query
        description: Max results — a whole number (default 20); values outside 1–100 are clamped. Text that is not a whole number is refused with 400.
        schema:
          type: integer
          default: 20
      - name: codes
        in: query
        required: false
        description: 'Batch: up to 50 UN/LOCODEs, comma-separated. Answered as results[] in input order, each with its own status; send alone. One call against the daily budget, N against the Pro monthly allowance.'
        schema:
          type: string
        example: NLRTM,GBFXT
      - $ref: '#/components/parameters/Envelope'
      - $ref: '#/components/parameters/ClientLabel'
      - $ref: '#/components/parameters/IfStale'
      responses:
        '200':
          description: 'Search results. A name search with no match carries did_you_mean: up to 3 real places whose name is one or two letters from the query ({code, name, country}) — suggestions, never applied.'
          headers:
            X-FreightUtils-Upstream:
              $ref: '#/components/headers/X-FreightUtils-Upstream'
        '404':
          description: Code not found When the code is one character from real UN/LOCODEs in the same country, did_you_mean lists up to 3 of them ({code, name, country}).
        '424':
          description: 'Only with ?if_stale=refuse: a dataset of the answer missed its upstream window.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/StaleUpstreamProblem'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    StaleUpstreamProblem:
      type: object
      description: HTTP 424 problem details, only for a caller who sent ?if_stale=refuse while a dataset of the answer missed its upstream window. Not retryable in seconds. Without the parameter the same request is answered, marked stale.
      required:
      - type
      - title
      - status
      - code
      - detail
      - datasets
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
          enum:
          - 424
        code:
          type: string
          enum:
          - stale_upstream
        detail:
          type: string
        datasets:
          type: array
          items:
            type: object
            properties:
              dataset:
                type: string
              state:
                type: string
              last_success:
                type:
                - string
                - 'null'
              window_days:
                type:
                - number
                - 'null'
              editions_held:
                type: array
                items:
                  type: string
        state_read_at:
          type:
          - string
          - 'null'
        instance:
          type: string
    RateLimitError:
      type: object
      required:
      - error
      - message
      properties:
        error:
          type: string
          example: rate_limited
        message:
          type: string
        tier:
          type: string
          example: anon
        limit:
          type: integer
        window:
          type: string
          example: 1d
        reset_at:
          type: string
          description: UTC time the allowance resets.
        upgrade_url:
          type: string
        signup_url:
          type: string
        docs_url:
          type: string
        retry_after_seconds:
          type: integer
  parameters:
    Envelope:
      name: envelope
      in: query
      required: false
      description: 'Response envelope: 1 (byte-stable), 1.1, or 1.2 (adds status, missing_inputs, edition, as_of). Omit for the plain body.'
      schema:
        type: string
        enum:
        - '1'
        - '1.1'
        - '1.2'
    ClientLabel:
      name: client
      in: query
      required: false
      description: Optional caller label (up to 40 characters of A-Za-z0-9._-) so your calls are recognisable in our usage figures. Changes no answer. The X-FreightUtils-Client header does the same.
      schema:
        type: string
        maxLength: 40
        pattern: ^[A-Za-z0-9._-]{1,40}$
    IfStale:
      name: if_stale
      in: query
      required: false
      description: 'refuse: answer HTTP 424 (stale_upstream) instead of serving stale while a dataset of this answer missed its upstream check window. Omit it (the default) to be served from the last verified edition with stale: true.'
      schema:
        type: string
        enum:
        - refuse
  headers:
    X-FreightUtils-Upstream:
      description: 'The upstream state of the datasets this answer was drawn from: the UpstreamMeta object as compact JSON, on every REST answer of a record lookup and of a calculator that read a served dataset (absent when it read none, e.g. a container check digit).'
      schema:
        type: string
  responses:
    RateLimited:
      description: 'Rate limited: the daily (or monthly) allowance or a burst window is spent. Retry after Retry-After seconds, or send a key.'
      headers:
        Retry-After:
          schema:
            type: integer
        X-RateLimit-Limit:
          schema:
            type: integer
        X-RateLimit-Remaining:
          schema:
            type: integer
        X-RateLimit-Reset:
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitError'
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'Free or Pro API key (fu_…). Optional: without one a call is anonymous (25/day per address).'
    BearerAuth:
      type: http
      scheme: bearer
      description: 'The same key as Authorization: Bearer fu_…'