Methodology & provenance
How every number here is calculated
This platform turns fragmented public commodity data into dashboards, country profiles and APIs. Nothing is synthesised in the dark: every figure is traceable to a named authority and tagged with a provenance tier so you always know whether you are reading a measurement, a computation, or a good-faith estimate. Where two authorities disagree by more than 5% we keep both values — see the reconciliation ledger.
The two things a tier can tell you
Numeric metrics carry one of four tiers, emitted by the backend in every API response's sources block:
Raw observation read straight from the authority (FAO tonnage, ECB FX rate, Pink Sheet price).
Computed from measured inputs (global share, living-income gap, scorecard). Declares its measured sources.
Involves an assumption or interpolation (carry-forward, template scaling, scenario shock). Carries a note explaining it.
Source is declared but not yet ingested — the UI shows a placeholder instead of a fabricated number.
Product value-chain cards use a second, complementary vocabulary that describes where an archetype came from rather than how a number was computed:
Each headline metric, and how it is built
| Metric | Tier | How it is calculated | Primary sources |
|---|---|---|---|
| Production volume | Measured | FAOSTAT QCL annual crop production tonnage. When the latest official vintage lags the current year, the most recent value is carried forward and the row is flagged as an assumption rather than re-stated as new fact. | FAOSTAT |
| Export value & global share | Derived | UN Comtrade trade flows. Global share = one origin's export value ÷ the summed world export value for that commodity and year. | UN Comtrade |
| Spot / benchmark price | Measured | The World Bank Pink Sheet monthly average is the canonical 'spot' series. ICE futures (daily), the ICCO daily average (cocoa), the ICO composite indicator (coffee) and SVI / Fairtrade references (vanilla) sit behind it as a resolution fallback chain. | World Bank Pink Sheet · ICE · ICCO · ICO · SVI |
| Value distribution (farm-gate → retail) | Modelled | Each actor's share of the FINAL RETAIL CONSUMER PRICE — not FOB, not farm-gate. German cocoa archetypes are read verbatim from the BASIC 2022 study; every other market and commodity is a good-faith scaling of that cost template (see deep-dive below). | BASIC 2022 · ICO · SVI |
| Living-income gap | Derived | Per origin: gap = living_income − avg_farmer_income. Required farm-gate uplift = gap ÷ (farm size × yield). Origin risk score = min(2 × mean gap %, 100). Benchmarks from Anker / GLWC reference values. | Anker Research / GLWC |
| Sourcing scorecard | Derived | A 100-point composite of six weighted dimensions: EUDR readiness 20 · living-wage progress 20 · forest preservation 15 · traceability 15 · political stability 15 · weather resilience 15. | EUR-Lex · Global Forest Watch · Anker · WGI · ND-GAIN |
| FX-adjusted farm-gate | Derived | The USD benchmark is translated into each origin's local currency via ECB reference rates, then compared to its trailing 3-year mean — exposing currency-driven sourcing stress that a USD-only chart hides. | ECB · World Bank Pink Sheet |
| Weather & NDVI outlook | Measured | Open-Meteo (ECMWF) historical and forecast archive, plus Copernicus Sentinel-2 NDVI where credentials are provisioned. Until a feed is ingested the card renders 'data pending' rather than a synthesised value. | Open-Meteo · Copernicus |
Value distribution, in detail
The headline split (e.g. Ghana cocoa — farmers, processors, exporters, retailers) is each actor's share of the final retail consumer price of the finished product — the chocolate bar on the shelf, not the FOB export price or the farm-gate price. The figures are anchored to the BASIC 2022 "German Cocoa and Chocolate Value Chains" study. German retail-chocolate archetypes are Direct quote verbatim readings; every other market and commodity is a Modelled estimate good-faith scaling of that cost template, cross-referenced with the ICO Annual Review (coffee) and the SVI 2023 Transparency Report (vanilla).
Read percentages, not euros. The BASIC absolute €/kg figures reflect 2020 retail data; cocoa spot rose roughly 3× into 2024. Treat the shares (who captures what) as the durable signal — they move far less across price regimes than the absolute prices do.
Farmers
Smallholders who grow and harvest the raw commodity.
Processors
Mills and roasters that turn the raw crop into bulk industrial goods.
Exporters
Local traders and shipping companies that move the crop across borders.
Brands & retailers
Brands that put the product on a wrapper and supermarkets that put it on a shelf.
Sourcing scorecard — the 100-point composite
| Dimension | Weight | Basis |
|---|---|---|
| EUDR readiness | 20 | EUR-Lex regulatory status × declared origin readiness |
| Living-wage progress | 20 | avg farmer income ÷ living-income benchmark |
| Forest preservation | 15 | inverse of annual forest-loss % |
| Traceability | 15 | digital > certification/cooperative > none |
| Political stability | 15 | World Bank LPI / governance indicators |
| Weather resilience | 15 | climate exposure of the growing region |
| Total | 100 | ≥ 75 excellent · 55–74 good · 35–54 moderate · < 35 high-risk |
Authoritative sources
The sources behind the metrics above, with their licence and update cadence. The complete, machine-readable registry is emitted in every API response's sources block and can be fetched whole from GET /api/v1/sources — see the public API docs. That registry, not this table, is canonical.
| Source | Organisation | Licence | Cadence |
|---|---|---|---|
| World Bank Commodity Markets (Pink Sheet) | The World Bank | CC BY 4.0 | Monthly (16th) |
| FAOSTAT — Production, Crops & Livestock | FAO of the UN | CC BY-NC-SA 3.0 IGO | Annual |
| ICCO Quarterly Bulletin of Cocoa Statistics | Int'l Cocoa Organization | ICCO Terms | Quarterly |
| ICO Coffee Market Report | Int'l Coffee Organization | ICO Terms | Monthly |
| UN Comtrade — International Trade Statistics | UN Statistics Division | UN SD Terms | Monthly |
| ECB Euro FX reference rates | European Central Bank | ECB Open Data | Daily (business days) |
| Anker Living Income Reference Values | Anker Research Inst. / GLWC | CC BY-NC 4.0 | Annual |
| Global Forest Watch (Hansen GFC) | WRI / Univ. of Maryland | CC BY 4.0 | Annual |
| EUR-Lex Official Journal of the EU | Publications Office of the EU | Re-use Decision 2011/833/EU | Daily |
| Worldwide Governance Indicators (WGI) | The World Bank | CC BY 4.0 | Annual |
| ND-GAIN Country Index | Univ. of Notre Dame | CC BY 4.0 | Annual |
| Open-Meteo Archive (ECMWF IFS) | Open-Meteo.com | CC BY 4.0 | Hourly |
| Sustainable Vanilla Initiative Transparency Report | SVI e.V. | SVI Terms | Annual |
| Fairtrade International Minimum Price Table | Fairtrade International | Fairtrade Terms | Annual |
Using this data responsibly
- These are aggregated public statistics and modelled estimates — not audited financial statements, and not a legal or compliance conclusion about any company, origin or shipment.
- Figures are reference and analysis material, not trading-grade or real-time market data; do not use them to time trades.
- Anything tagged Modelled or Modelled estimate is directional — treat the shares and rankings as the signal, not the last decimal.
- When sources disagree we surface both rather than pick a winner; the judgement call between them is yours.