The atlas is a thin presentation layer over committed, versioned data. Those files are the API: stable URLs, plain JSON, CC-friendly public sources. They update when the pipeline reruns (the same files power the interactive views and the per-material profiles).
Endpoints
| URL | What |
|---|---|
| /out/data.json | The 32 materials with their mine / refine / reserve layers + the EU import-origin lens |
| /out/flows_2018.json … flows_2024.json | Reconciled bilateral trade (CEPII BACI), one file per measured year |
| /out/flows_2025.json | Provisional nowcast (own reconciliation of partial Comtrade) |
| /out/flows_2026.json | Directional scenario (2025 structure, levels tilted by Q1 momentum × prices) |
Base: https://varcolacus.github.io/critical-materials-atlas. The CSV the atlas exports (the Download data button, top right of the table) is the per-material metric sheet for the selected year.
Schema — flows_<year>.json
{
"year": 2024,
"names": { "CD": "Congo [DRC]", "CN": "China", … }, // ISO-2 → display name
"materials": {
"cobalt": [
{ "from": "ZM", "to": "ZA", "value": 78998908 }, // exporter, importer, USD
…
],
"lithium": [ … ], …
},
"provisional": true // only on 2025/2026
}
Schema — data.json
{
"headlineYear": 2024, "dataUpdated": "15 Jun 2026",
"materials": [
{
"label": "cobalt", "title": "Cobalt oxides & hydroxides (CN 2822 00 00)",
"note": "…", "hhi": 0.474,
"mined": [ {"c":"CD","v":76}, {"c":"ID","v":10}, … ], // USGS, % world output
"refined": [ {"c":"CN","v":76} ], // IEA, % processing
"reserves": [ {"c":"CD","v":55}, {"c":"AU","v":15}, … ], // USGS, % reserves
"origins": [ {"c":"CN","v":62.25,"eur":12038563}, … ] // EU import-origin lens (Comext)
}, …
]
}
Use it
const f = await (await fetch( 'https://varcolacus.github.io/critical-materials-atlas/out/flows_2024.json')).json(); // top exporter of lithium, by value const o = {}; for (const {from,value} of f.materials.lithium) o[from]=(o[from]||0)+value; console.log(Object.entries(o).sort((a,b)=>b[1]-a[1])[0]); // → ["CL", …]
Attribution & licence. The data derives from public sources — UN Comtrade (reconciled via CEPII BACI), USGS Mineral Commodity Summaries, IEA Critical Minerals Outlook, Eurostat Comext, World Bank. Use freely; please cite the original source for serious work, and link this atlas as the derived/reconciled layer. The reconciliation method is documented in the technical note and reproducible from the engine repo.