API

Base URL

https://statorigin.org/api/v1

All endpoints are GET, return JSON, and send Access-Control-Allow-Origin: *, so you can call them straight from a browser without a proxy.

Quick start

curl "https://statorigin.org/api/v1/statistics?industry=electric-vehicles&region=CN&year=2020..2026&limit=5"

import requests

r = requests.get("https://statorigin.org/api/v1/statistics",
                 params={"industry": "electric-vehicles", "region": "CN", "limit": 100})
for row in r.json()["data"]:
    print(row["period"]["start"][:4], row["value"], row["scale"],
          "-", row["source"]["org"], row["source"]["locator"])

const res = await fetch(
  "https://statorigin.org/api/v1/statistics?industry=electric-vehicles&limit=100"
);
const { data, meta } = await res.json();

// Every row carries its own citation, ready to use.
console.log(data[0].citation.apa);
console.log(meta.attribution);

Endpoints

12 endpoints. Every one returns the same envelope and the same licence and attribution metadata.

Response shape

Every list endpoint returns data plus meta. Each element of data is a full record; provenance is never abbreviated.

Live example: /api/v1/statistics/stat_C3GXCWCGPPPPWY1K0743MWVCXJ

Reproduce a chart

Every hub chart is drawn from one series call. This is the electric vehicles hub's first chart, electric cars as a share of new car sales: one request, the response, and a plot.

curl "https://statorigin.org/api/v1/indicators/global-ev-sales-share-of-new-cars/series?region=GLOBAL"

{
  "data": {
    "indicator": { "slug": "global-ev-sales-share-of-new-cars", "name": "…", "unit": "percent", "scale": "1" },
    "unit": "percent",
    "scale": "1",
    "region": { "code": "GLOBAL", "name": "Global", "type": "world" },
    "points": [
      {
        "period_start": "2024-01-01",
        "period_label": "2024",
        "value": 20,
        "value_type": "actual",
        "statistic_id": "stat_…",
        "url": "https://statorigin.org/stat/stat_…",
        "source_org": "IEA",
        "source": { "org": "…", "document_title": "…", "document_url": "…", "locator": "…", "published_date": "…" }
      }
    ],
    "available_regions": ["GLOBAL", "…"]
  },
  "meta": { "total": 6, "attribution": "…", "license": "…", "docs": "…" }
}

import requests, matplotlib.pyplot as plt

d = requests.get("https://statorigin.org/api/v1/indicators/global-ev-sales-share-of-new-cars/series?region=GLOBAL").json()["data"]
pts = d["points"]
years = [int(p["period_start"][:4]) for p in pts]
vals = [p["value"] for p in pts]
actual = [p["value_type"] == "actual" for p in pts]
plt.plot(years, vals, marker="o")                      # every point, one line
plt.scatter([y for y, a in zip(years, actual) if not a],
            [v for v, a in zip(vals, actual) if not a], facecolors="white")  # hollow = forecast
plt.title(d["indicator"]["name"]); plt.ylabel(d["unit"])
plt.figtext(0.01, 0.01, "Source: " + ", ".join(sorted({p["source_org"] for p in pts})) + " · statorigin.org")
plt.show()

region takes a code or a slug (GLOBAL, CN, china) and defaults to GLOBAL; from and to bound the years. Every value is expressed in the series-level unit and scale, whatever scale the publisher used for that year. Each point is its own sourced record: url is the permanent page for that observation, and source is what it was taken from. If an indicator is renamed, the old slug is kept in slug_history and keeps resolving, so a saved script does not break.

Live: /api/v1/indicators/global-ev-sales-share-of-new-cars/series?region=GLOBAL · the chart as drawn on the hub: electric vehicles charts

Authentication and quotas

Responses include X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Exceeding the quota returns 429 with Retry-After.

Quotas exist to stop abuse, not to sell access. If you need more than the free tier for something useful, ask: the answer is usually yes.

Errors

Errors return { "error": { "code", "message", "docs" } } with an HTTP status that matches the code.

A malformed filter is rejected rather than ignored. If you pass year=20204 you get a 400, not a result set containing every year. A silently dropped filter is how wrong numbers get into other people's work.

Licence and attribution

Data is published under CC BY 4.0. Attribution is required and commercial use is permitted.

Attribute the original publisher (they did the work) and link to the permanent record so the trail stays checkable. Every response includes an attribution string in meta and a formatted citation on each record, so you never have to assemble one by hand.

Machine-readable resources

• OpenAPI 3.1 specification · generate a client, or import into Postman or Insomnia
• llms.txt · a plain-language brief for language models
• Sitemap index · hubs, indicators, topics, regions, rankings, reports, sources and static pages, with truthful lastmod values
• Methodology · how figures are sourced and verified

Currently serving 232938 published data points across 3138 indicators and 171 source organisations.