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
1---2name: comtrade-trade3description: Query UN Comtrade bilateral trade flows (USD, kg) for critical minerals by HS code, country, and year4---56# UN Comtrade Trade Data78Query 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.910## Usage1112### Search by mineral name:13```bash14python3 {baseDir}/scripts/comtrade_query.py --mineral lithium15```1617### Search by HS code:18```bash19python3 {baseDir}/scripts/comtrade_query.py --hs-code 282520 --reporter 84220```2122### Filter by country and flow:23```bash24python3 {baseDir}/scripts/comtrade_query.py --mineral cobalt --reporter 842 --flow X --year 202225```2627### JSON output:28```bash29python3 {baseDir}/scripts/comtrade_query.py --mineral rare_earth --format json --year 202330```3132## Parameters3334| Parameter | Description | Default |35|-----------|-------------|---------|36| `--mineral` | Critical mineral name (lithium, cobalt, rare_earth, graphite, nickel, manganese, gallium, germanium, copper, hree, lree) | - |37| `--hs-code` | HS commodity code (alternative to --mineral) | - |38| `--reporter` | Reporter country code (e.g., 842 for USA, 156 for China) | 0 (all) |39| `--partner` | Partner country code | 0 (world) |40| `--flow` | Trade flow: M (imports), X (exports), M,X (both) | M,X |41| `--year` | Year(s), comma-separated | 2023 |42| `--limit` | Maximum records to return | 500 |43| `--format` | Output format: summary, detailed, json | summary |4445## Available Minerals4647| Name | HS Codes | Description |48|------|----------|-------------|49| `lithium` | 253090, 282520, 283691, 850650 | Ores, oxide/hydroxide, carbonate, batteries |50| `cobalt` | 2605, 282200, 810520, 810590 | Ores, oxides, unwrought, articles |51| `rare_earth` | 2846, 280530 | REE compounds, REE metals |52| `hree` | 284690 | Heavy REE compounds |53| `lree` | 284610 | Light REE compounds |54| `graphite` | 250410, 250490, 380110 | Natural (amorphous, crystalline), artificial |55| `nickel` | 2604, 7501, 750210, 750220, 281122 | Ores, matte, unwrought, alloys, oxides |56| `manganese` | 2602, 811100 | Ores, unwrought |57| `gallium` | 811292 | Unwrought |58| `germanium` | 811299 | Other base metals |59| `copper` | 7402, 7403 | Refined, unrefined |6061## Examples6263```bash64# US lithium imports65python3 {baseDir}/scripts/comtrade_query.py --mineral lithium --reporter 842 --flow M --year 20236667# Global cobalt trade flows68python3 {baseDir}/scripts/comtrade_query.py --mineral cobalt --format detailed6970# China rare earth exports71python3 {baseDir}/scripts/comtrade_query.py --mineral rare_earth --reporter 156 --flow X --year 20227273# Nickel trade by specific HS code74python3 {baseDir}/scripts/comtrade_query.py --hs-code 2604 --format json75```7677## Notes7879- Requires `UNCOMTRADE_API_KEY` environment variable80- Country codes follow UN M49 standard (842=USA, 156=China, 276=Germany, etc.)81- Use 0 for "all countries" or "world"82- HS codes follow Harmonized System classification83- API has rate limits; be conservative with large queries
lamm-mit