Developers and the data API
Every page has a machine-readable twin. All endpoints are static files served with Access-Control-Allow-Origin: * and cached for 24 hours. No key, no rate limit beyond ordinary politeness.
Usage
These are plain static files on Cloudflare's CDN, not a metered API: there is no per-key quota and no throttling beyond what Cloudflare applies to any request pattern that looks abusive. Fetch a file once and cache it yourself rather than polling; every source updates at most monthly (see data status for each source's cadence), so polling more often than that returns the same bytes. A crawler pulling many files in a short burst should add a short delay between requests. If you build something that depends on this data at volume, a link back or a note in the contact form is appreciated but not required by the license.
Endpoints
| Path | What it holds |
|---|---|
/data/index.json | Every commodity with category, tier, top-3 producers, latest benchmark price and links. |
/data/commodities/{slug}.json | Full page data: production by country (latest year and series), reserves, top-15 exporters and importers per HS line, every price series with derived statistics and the last 24 months, balances, harvest calendar, and the sources with vintages. Example: /data/commodities/coffee.json. |
/data/prices/{slug}.json | The full monthly series for sources that allow redistribution (World Bank) and derived statistics for all. |
/data/prices.json | Every series' latest value and changes (the prices dashboard). |
/data/countries.json, /data/countries/{iso3}.json | The reverse index: where each country ranks in the top ten. |
/data/csv/{slug}-production.csv, -trade.csv, -prices.csv | Flat CSV downloads (only for sources whose license allows redistribution). |
/data/all-csv.zip | Every downloadable CSV above, bundled into one archive. To pick your own subset of series and date range instead, use the CSV builder. |
/data/openapi.json, /data/schemas/{name}.schema.json | An OpenAPI 3.1 description of every static endpoint below and a JSON Schema for each document type. Both are inferred from the published files and re-checked against every one of them on each build, so they cannot drift from the data: a property marked required appears in every file of that type. |
/data/consumption.json, /data/consumption/{iso3}.json | Consumption from FAO food balance sheets: world supply, top consumers and highest per-person supply per commodity, and one country's supply, per-person food supply, self-sufficiency and import dependency. |
/data/critical.json | Which commodities are on the US 2025 and EU 2024 critical-mineral lists (US status from USGS's own flag in the Mineral Commodity Summaries data), with the date each list was read and the listed minerals this site does not cover yet. |
/data/depletion.json | What each mineral and fuel on how much is left is mined each year, its reserves and their date, years of supply at the current pace and with growing output, the amount mined so far (with the first year counted and the reason where there is none) and how reserves changed between older and current editions. |
/data/long-prices.json | The century of real prices: USGS unit values in constant 1998 dollars since 1900 per mineral, with first-decade and latest-decade means, peak, low and the log-linear trend per decade. |
/data/supplier-exposure.json | Largest origin and top three origins, with shares of import value, for each critical mineral's primary customs line in five import markets; behind supplier exposure. |
/data/control-trade.json | Controlling country's export index in the years after each dated control, with other exporters' index and world share; behind trade after export controls. |
/data/export-history.json | Exporter shares of world export value in 2000 and 2024 per commodity (stable customs lines only) with gainers, losers and an annual top-five series; behind export share history. |
/data/event-prices.json | Price change 3, 6 and 12 months after each dated export control that names a priced mineral, with percentile and market-wide median; behind prices around export controls. |
/data/basket-prices.json | Monthly nominal and real price index (2015 = 100) of each large exporter's priced export basket since 2000, with weights, coverage and the benchmark series; behind export basket prices. |
/data/substitution.json | One row per importer and commodity where one supplier provides half or more of imports of at least $50 million: the supplier, its share, and others' sales to other buyers as a ratio; behind substitution coverage. |
/data/critical-matrix.json | One row per critical mineral: top producer share, export controls in force, US net import reliance, largest import-origin share, reserve years and by-product hosts, with the thresholds used; behind the critical risk matrix. |
/data/country-reserve-life.json | Each producing country's reserves, production and years of reserves by mineral; behind country reserve life. |
/data/price-vs-output.json | Real price against cumulative world output per mineral, with the fitted slope as percent per doubling and R²; behind prices and cumulative output. |
/data/us-dependence.json | US net import reliance, import sources, secondary supply and scrap flows by mineral (USGS); behind US import reliance. |
/data/confidence.json | The Firm, Fair or Rough level of each commodity's production data and the reasons; behind data confidence. |
/data/mineral-profile.json | Reserve years, peak, real price, US import reliance, critical lists, by-product links and export controls per commodity; used by compare. |
/data/export-controls.json | The register of export bans, quotas and licences, each with sources and status; behind export controls. |
/data/chokepoints.json | Chokepoint volumes by year and scope, bypass routes, dated disruptions and source conflicts; behind chokepoints. |
/data/by-products.json | By-product links with source quotes; behind by-products. |
/data/import-markets.json | Every import market of $250 million or more with its largest and second-largest supplier, as compact rows (column names in columns). |
/data/analysis.json, /data/analysis-prices.json, /data/enso.json | The computed tables behind the newer Patterns reports (land versus yield, net trade, supplier shifts, currencies, lead and lag, volatility, seasonality, El Niño) and the El Niño, La Niña and neutral label for each year. |
/data/fx.json | Latest USD exchange rates (EUR, GBP, JPY) behind the currency toggle on price pages. |
/commodities/{slug}/updates.xml | RSS: just one commodity's own monthly price update and any new record. |
/data/manifest.json | Per-source vintage, fetch time and check status. |
/commodities/{slug}.md | The page as plain Markdown, for assistants and offline reading. |
/llms.txt, /llms-full.txt | Site purpose, how to cite, and links to every page and JSON file. |
/data-updates.xml | RSS: new data vintages as they publish. |
/data/facts.json | Every fact in the daily fact pool, in rotation order. The fact for a UTC day is facts[(days since epoch) mod count]. |
/data/patterns.json | The tables behind the Patterns reports: concentration, producer versus exporter, real-terms prices, growth, correlations, reserves and country leaders. |
/hs-codes/ | Reverse index from Harmonized System code to the commodity page that tracks it, built from each commodity document's own trade.tables[].hs_code. |
/data/monthly.json | The monthly price-change reports behind /monthly/: gains, falls, records, runs and category averages for each of the last 12 months. |
/stats.xml | RSS: ten new statistics every week. |
/facts.xml | RSS: the fact of the day, yesterday and the next 30 days. |
/movers.xml | RSS: benchmark series that moved 8% or more on the month, regenerated with every publish. |
/badge/price/{slug}.svg, /badge/origin/{slug}.svg | Embeddable status badges: latest price and 12-month change, or top producer and share. See /embed/ for ready-made markup. |
Example
curl -s https://commodityorigins.com/data/commodities/coffee.json | jq '.production.items[0].top[:3]'Shape notes
- Production values are in the
unitfield of each item (tonnes for crops and minerals, thousand barrels daily for oil, billion cubic metres for gas). - Trade values are US dollars and net weight in kilograms;
shareis percent of the world total for that HS line. - Price series carry
unit,source_id,vintageandredistribution; IMF series include statistics but not row-level data. - Every object that came from a source has
source_id; thesourcesmap on each commodity gives the license and citation for that id.
License and citation
Commodity Origins's derived tables and prose are CC BY 4.0. Upstream rows keep their own license (see Sources). Suggested citation:
Commodity Origins, "{page title}", data {vintage}, https://commodityorigins.com/{path}/ (accessed {date}). Underlying data: {source citation from the page}.Last publish: 22 October 2026.