UN Comtrade Trade Data

Query UN Comtrade for bilateral trade flows of critical minerals. Returns trade values (USD), net weight (kg), and flow direction (imports/exports) by HS commodity code, reporter country, partner country, and year.

Usage

Search by mineral name:

python3 {baseDir}/scripts/comtrade_query.py --mineral lithium

Search by HS code:

python3 {baseDir}/scripts/comtrade_query.py --hs-code 282520 --reporter 842

Filter by country and flow:

python3 {baseDir}/scripts/comtrade_query.py --mineral cobalt --reporter 842 --flow X --year 2022

JSON output:

python3 {baseDir}/scripts/comtrade_query.py --mineral rare_earth --format json --year 2023

Parameters

Parameter	Description	Default
--mineral	Critical mineral name (lithium, cobalt, rare_earth, graphite, nickel, manganese, gallium, germanium, copper, hree, lree)	-
--hs-code	HS commodity code (alternative to --mineral)	-
--reporter	Reporter country code (e.g., 842 for USA, 156 for China)	0 (all)
--partner	Partner country code	0 (world)
--flow	Trade flow: M (imports), X (exports), M,X (both)	M,X
--year	Year(s), comma-separated	2023
--limit	Maximum records to return	500
--format	Output format: summary, detailed, json	summary

Available Minerals

Name	HS Codes	Description
lithium	253090, 282520, 283691, 850650	Ores, oxide/hydroxide, carbonate, batteries
cobalt	2605, 282200, 810520, 810590	Ores, oxides, unwrought, articles
rare_earth	2846, 280530	REE compounds, REE metals
hree	284690	Heavy REE compounds
lree	284610	Light REE compounds
graphite	250410, 250490, 380110	Natural (amorphous, crystalline), artificial
nickel	2604, 7501, 750210, 750220, 281122	Ores, matte, unwrought, alloys, oxides
manganese	2602, 811100	Ores, unwrought
gallium	811292	Unwrought
germanium	811299	Other base metals
copper	7402, 7403	Refined, unrefined

Examples

# US lithium imports
python3 {baseDir}/scripts/comtrade_query.py --mineral lithium --reporter 842 --flow M --year 2023

# Global cobalt trade flows
python3 {baseDir}/scripts/comtrade_query.py --mineral cobalt --format detailed

# China rare earth exports
python3 {baseDir}/scripts/comtrade_query.py --mineral rare_earth --reporter 156 --flow X --year 2022

# Nickel trade by specific HS code
python3 {baseDir}/scripts/comtrade_query.py --hs-code 2604 --format json

Notes

• Requires UNCOMTRADE_API_KEY environment variable
• Country codes follow UN M49 standard (842=USA, 156=China, 276=Germany, etc.)
• Use 0 for "all countries" or "world"
• HS codes follow Harmonized System classification
• API has rate limits; be conservative with large queries