Skip to content

Metadata via the CLI

The metadata command browses the UN Comtrade reference catalogues. Five sub-subcommands cover countries, partners, HS codes, search, and refresh.

Purpose

This page covers each metadata sub-subcommand in detail, with flags, output formats, and shell-composition patterns.

Prerequisites

  • un-comtrade-sdk installed.
  • The un-comtrade script on your PATH.

Walkthrough

List countries

un-comtrade metadata countries

Output (default json):

[
  {"country_code": 4, "iso_alpha3": "AFG", "display_name": "Afghanistan"},
  ...
]

List partner countries

un-comtrade metadata partners

List HS codes at a level

un-comtrade metadata hs-codes --level 2      # HS chapters
un-comtrade metadata hs-codes --level 4      # HS headings
un-comtrade metadata hs-codes --level 6      # HS subheadings

Search HS codes by description

un-comtrade metadata search "electrical"

Refresh the catalogue

un-comtrade metadata refresh

Forces a re-download of every catalogue. Rate-limited to one HTTP call per second.

Examples

A Markdown table of the top-20 countries by population-equivalent rank (the catalogue is sorted by reporter code):

un-comtrade metadata countries --output-format markdown | head -25

Pipe the country catalogue to jq for filtering:

un-comtrade metadata countries --output-format json \
    | jq '[.[] | select(.iso_alpha3 == "IND")]'
# → [{"country_code": 699, "iso_alpha3": "IND", "display_name": "India"}]

Search HS codes for "machinery":

un-comtrade metadata search "machinery" --output-format markdown
  • RECIPE-091 — Drive metadata commands from the CLI.

Next steps