By name: comtrade-trade description: Query UN Comtrade bilateral trade flows (USD, kg) for critical minerals by HS code, country, and year metadata: openclaw: emoji: "🚢" requires: bins: - python3 env: - UNCOMTRADE_API_KEY
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_KEYenvironment 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