Skip to content

Metadata

The metadata layer exposes the UN Comtrade reference catalogues: countries (the reporters and partners), HS codes (the commodity classification), units (the measurement units), and trade classifications (the standard HS revisions). Every catalogue is cached on first use and refreshable on demand.

Purpose

This page covers:

  1. The MetadataService interface.
  2. The country, partner, HS-code, and unit catalogues.
  3. The cache lifecycle (load → cache → refresh).
  4. The offline-mode fallback.

Prerequisites

  • un-comtrade-sdk installed (see Installation).
  • The ComtradeClient instantiated (see Quick Start).
  • No API key required for the metadata endpoints.

Walkthrough

List countries

from un_comtrade import ComtradeClient

with ComtradeClient() as client:
    countries = client.metadata.get_countries()
    print(f"{len(countries)} countries")

get_countries() returns list[Country] — a typed list of frozen dataclasses. Each Country exposes country_code, iso_alpha2, iso_alpha3, and display_name.

Look up a single country

with ComtradeClient() as client:
    india = client.metadata.get_country(699)
    print(f"{india.display_name} ({india.iso_alpha3})")

Returns Country | None — None when the code is not in the catalogue.

Search countries by name

with ComtradeClient() as client:
    matches = client.metadata.search_countries("india")
    for c in matches:
        print(f"  {c.country_code} {c.display_name}")

Returns list[Country] ordered by ISO code. Search is case-insensitive and matches against the display name and ISO alpha-2/3 codes.

List HS codes at a given level

with ComtradeClient() as client:
    hs2 = client.metadata.get_hs_codes(level=2)
    print(f"{len(hs2)} HS-2 codes")

The level argument is 2, 4, or 6 for HS chapters, headings, and subheadings respectively. Returns list[HSCode] — each entry exposes code, description, and level.

Refresh the catalogue

with ComtradeClient() as client:
    client.metadata.refresh()

The refresh() method clears the cache, re-downloads every catalogue, and writes the new snapshot to disk. Rate-limited to one HTTP call per second per ADR-0035.

Configure the cache directory

from un_comtrade import ComtradeClient
from un_comtrade.config import Configuration

config = Configuration(cache_dir="/srv/un_comtrade/cache")
with ComtradeClient(config) as client:
    countries = client.metadata.get_countries()

See Authentication → Configure the cache directory for the full configuration surface.

Examples

Drill into the country catalogue after a refresh:

from un_comtrade import ComtradeClient

with ComtradeClient() as client:
    client.metadata.refresh()
    countries = client.metadata.get_countries()

# Snapshot the catalogue for offline use.
import json
with open("countries.json", "w") as f:
    json.dump(
        [
            {"code": c.country_code, "iso3": c.iso_alpha3, "name": c.display_name}
            for c in countries
        ],
        f, indent=2,
    )

Search by ISO code (faster than text search):

with ComtradeClient() as client:
    matches = client.metadata.search_countries("IN")
    print(matches[0].country_code, matches[0].display_name)
# → 699 India

Next steps