Public API — Commodity Intelligence

Public API

Free, key-less commodity intelligence

Every chart on this site is built on a versioned REST API. The API is free to use with attribution — no signup, no API key, no paywall. Built for NGOs, cooperatives, educators, journalists and small procurement teams that can't afford a Bloomberg terminal.

No key required

Call any /api/v1/* endpoint directly. No signup wall, no usage tier.

120 req / minute / IP

Generous for real use, strict enough to keep the service up for everyone.

CC BY 4.0

Free to redistribute + build on, as long as you credit "spatialsusty.com".

Attribution requirement

Anywhere the data is shown (site, paper, dashboard, report) include one of the following near the figure:

Source: Value Distribution — Commodity Intelligence (spatialsusty.com), CC BY 4.0

// …or the inline form:
powered by commodity.spatialsusty.com

The platform only aggregates data — every underlying dataset carries its own licence (e.g. FAOSTAT is CC BY-NC-SA 3.0 IGO; World Bank Pink Sheet is CC BY 4.0). When you redistribute raw numbers you inherit those licences.

Market & prices

Spot price series, country-level production/export metrics, global choropleth data.

GET/api/v1/prices

Monthly spot prices across cocoa, coffee, vanilla.

curl https://commodity.spatialsusty.com/api/v1/prices?commodity=cocoa&from_date=2024-01-01&to_date=2024-12-31

GET/api/v1/countries/{iso2}/summary
Top-line country metrics — production, export value, global share.
```
curl https://commodity.spatialsusty.com/api/v1/countries/GH/summary?commodity=cocoa&year=2024
```
GET/api/v1/countries/{iso2}/value-chain
Per-stage value split (farmer / processor / exporter / retailer %).
```
curl https://commodity.spatialsusty.com/api/v1/countries/CI/value-chain?commodity=cocoa&year=2024
```
GET/api/v1/global/map
Global choropleth data for any metric × commodity × year.

Risk & intelligence

Supply-chain risk scoring, EUDR readiness, sourcing scorecards, price alerts, and the executive brief.

GET/api/v1/risk-intel/executive-brief
One-screen morning brief — prices, balance, top origin, EUDR countdown.
GET/api/v1/risk-intel/executive-brief.html
Same brief, rendered as standalone HTML for email / print-to-PDF.
GET/api/v1/risk-intel/executive-brief.pdf
Same brief, rendered as a binary PDF (board packs, regulatory filings).
GET/api/v1/risk-intel/price-alert
Spot price vs 3-year rolling average, classified into a procurement alert.
GET/api/v1/risk-intel/sourcing-scorecard
Multi-dimensional origin scorecard (EUDR / forest / wage / traceability / stability / weather).
GET/api/v1/risk-intel/income-simulator
Simulate farm-gate price increases against the living-income benchmark.
GET/api/v1/risk-intel/counterfactual-income
If Fairtrade minimums had tracked inflation, where would farmers be today?
GET/api/v1/risk-intel/labor-risk
USDOL child / forced labor flags per commodity × origin (2024 edition).
```
curl https://commodity.spatialsusty.com/api/v1/risk-intel/labor-risk?commodity=cocoa&country=CI
```

GET/api/v1/risk-intel/fx-impact

Cumulative local-currency depreciation vs USD — the wedge USD coverage hides.

curl https://commodity.spatialsusty.com/api/v1/risk-intel/fx-impact?commodity=cocoa&country=GH&since_year=2020

GET/api/v1/risk-intel/conflicts-public
Public ledger of inter-source disagreements. Transparency moat.

GET/api/v1/risk-intel/alternative-origins

Diversification candidates ranked by composite sourcing scorecard.

curl https://commodity.spatialsusty.com/api/v1/risk-intel/alternative-origins?commodity=cocoa&current=CI&limit=5

GET/api/v1/risk-intel/supply-events
Live supply-risk news (GDELT) — drought, strike, port closure, embargo, disease, etc. 15-min refresh.
```
curl https://commodity.spatialsusty.com/api/v1/risk-intel/supply-events?commodity=cocoa&since_hours=168
```
GET/api/v1/risk-intel/country-macro
Origin macro backdrop from the World Bank Indicators API — GDP/capita, inflation, poverty, rural share.
```
curl https://commodity.spatialsusty.com/api/v1/risk-intel/country-macro?country=GH
```
GET/api/v1/risk-intel/deforestation-timeline
Annual tree-cover loss per origin, EUDR cutoff-referenced.
GET/api/v1/risk-intel/certification-premium
Fairtrade / Organic / Rainforest Alliance premia vs conventional baseline.
GET/api/v1/risk-intel/due-diligence-report
EUDR-style aggregated report for a commodity × origin.

Products & procurement

Product archetypes, retail-price lookup, regulatory radar, authoritative-source signals.

GET/api/v1/products/archetypes
Catalog of product archetypes with per-stage cost breakdowns.
GET/api/v1/products/filter-options
Filter dimensions available for product lookup (markets, segments, certifications, …).
GET/api/v1/procurement/weather-outlook
16-day ECMWF weather forecast aggregated across origin centroids.
GET/api/v1/procurement/regulatory-events
EUR-Lex + USTR regulatory radar, provenance-tagged.

Operational

Liveness + data freshness indicators.

GET/api/v1/health
Liveness probe (no DB).
GET/api/v1/health/ready
Readiness probe — DB + pool + anti-scrape stats.

Embeddable widgets

Drop a live widget onto any co-op, NGO or blog page.

<iframe
  src="https://commodity.spatialsusty.com/embed/price-alert?commodity=cocoa"
  width="480" height="140" frameborder="0"
  title="Cocoa price alert"></iframe>

<iframe
  src="https://commodity.spatialsusty.com/embed/income-gap?commodity=cocoa&country=CI"
  width="480" height="220" frameborder="0"
  title="Living income gap — Côte d'Ivoire cocoa"></iframe>

Widgets inherit this site's data freshness guarantees and update automatically whenever the underlying datasets update.

A one-page summary of commodity risk across cocoa, coffee and vanilla, delivered Monday morning. Unsubscribe in one click.

No spam, no trackers, no resold lists. Subscribers are stored in our own database (see Privacy).