API Documentation

Free REST API for global statistics. JSON responses. No authentication required for basic access.

Base URL: https://statisticsoftheworld.com

Build software and AI workflows

Use the REST API or connect an AI client through MCP. Data responses include source attribution and reuse metadata. Start free with 1,000 requests/day without a key.

API Pro includes the reviewed World Bank bulk bundle, archived IMF forecast panel, email support, and 50,000 API and MCP requests/day.

API Pro · $49/mo→Get a free key MCP setup →

Catalog policy: API and MCP reads retain the same 335-indicator public catalog when a key is upgraded. Each response carries source-specific attribution and reuse metadata. Bulk files are a separate redistribution surface: the Data Pro bundle contains 277 reviewed World Bank indicators, and high-frequency bulk exports include only series cleared for redistribution.

Rate Limits & Pricing

Tier	Rate Limit	Price	Auth
Anonymous	1,000 req/day	Free	None (IP-based)
Developer	1,000 req/day	Free	`X-API-Key`
Data Pro	10,000 req/day	$29/mo	`X-API-Key`
API Pro	50,000 req/day	$49/mo	`X-API-Key`
Enterprise	Custom	Custom	`X-API-Key`

Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-RateLimit-Tier

Compare API plans →

Quick start

Python

import requests

r = requests.get(
    "https://statisticsoftheworld.com/api/v2/history",
    params={"indicator": "NY.GDP.MKTP.CD", "country": "USA"},
    headers={"X-API-Key": "sotw_YOUR_KEY"},  # optional under 1K/day
)
data = r.json()
print(data["data"][-1])  # latest year

JavaScript

const params = new URLSearchParams({ indicator: "NY.GDP.MKTP.CD", country: "USA" });
const res = await fetch(
  `https://statisticsoftheworld.com/api/v2/history?${params}`,
  { headers: { "X-API-Key": "sotw_YOUR_KEY" } } // optional under 1K/day
);
const data = await res.json();
console.log(data.data.at(-1)); // latest year

Endpoints

GET/api/v1/calendar

Institutional release schedules with source links. Supports from/to dates and JSON, CSV or Markdown. Date passed does not confirm publication. JSON may include related current series data with its own period; it is not a verified release outcome. Invalid date windows or formats return 400; required data-read failures return 503/no-store.

Example curl

curl "https://statisticsoftheworld.com/api/v1/calendar?institution=BOC&format=json"

Response

{"count":1,"events":[{"date":"YYYY-MM-DD","status":"scheduled","statusBasis":"schedule_date","publicationConfirmed":false,"sourceUrl":"..."}],"meta":{...}}

GET/api/v1/countries

List all 218 countries with metadata.

Example curl

curl https://statisticsoftheworld.com/api/v1/countries

Response

{"count":218,"data":[{"id":"USA","name":"United States","region":"North America",...}]}

GET/api/v1/countries/:id

Get a single country with its latest indicator values. Upgrading preserves the public catalog and raises the request limit.

Example curl

curl https://statisticsoftheworld.com/api/v1/countries/USA

Response

{"country":{"id":"CAN","name":"Canada",...},"indicators":[{"id":"NY.GDP.MKTP.CD","value":2240000000000,...}]}

GET/api/v1/indicators

List 335 public indicators. Paid keys retain the public catalog and add higher request limits.

Example curl

curl https://statisticsoftheworld.com/api/v1/indicators

Response

{"count":335,"categories":[...],"data":[{"id":"SP.POP.TOTL","label":"Population",...}]}

GET/api/v1/indicators/:id

Get a single indicator ranked across all countries.

Example curl

curl https://statisticsoftheworld.com/api/v1/indicators/USA

Response

{"indicator":{...},"count":192,"data":[{"rank":1,"countryId":"USA","value":31820000000000},...]}

GET/api/v1/history/:indicator/:country

Get available historical data for an indicator-country pair. ECB.EXRATE includes each reading’s historical quote currency per EUR, annual reference boundaries, publisher status/comment, compilation note and immutable capture link. A normal source status does not certify final observed data; RON and TRY already include the publisher’s redenomination adjustment.

Example curl

curl https://statisticsoftheworld.com/api/v1/history/SP.POP.TOTL/CAN

Response

{"indicator":{...},"country":"CAN","data":[{"year":2000,"value":744631000000},{"year":2001,...}]}

GET/api/v1/rankings/:indicator

Get ranked list of countries for an indicator. Supports ?limit=N parameter.

Example curl

curl https://statisticsoftheworld.com/api/v1/rankings/SP.POP.TOTL

Response

{"indicator":{...},"count":192,"data":[{"rank":1,"countryId":"CHN","country":"China","value":1425893000},...]}

GET/api/v1/series

High-frequency catalog: daily yield curves and reference rates, central bank policy rates, monthly CPI for ~190 countries, unemployment, industrial production, electricity, and shipping activity. Every series carries machine-readable licence metadata.

Example curl

curl https://statisticsoftheworld.com/api/v1/series

Response

{"count":171,"data":[{"id":"UST.YC.10Y","frequency":"D","licence":"public-domain","resale_permitted":true,...}]}

GET/api/v1/series/:id

Observations for one series. ?geo=USA selects a country, ?latest=1 returns the newest stored reading for every geography, and ?from=YYYY-MM-DD bounds history. Check each reading’s period; latest dates can differ across countries.

Example curl

curl "https://statisticsoftheworld.com/api/v1/series/BIS.CBPOL.D?latest=1"

Response

{"series":{"id":"IMF.CPI.YOY.M","unit":"% y/y",...},"data":[{"geo":"USA","period":"2026-05","value":4.25},...]}

GET/api/v1/series/bulk

Stream the redistributable high-frequency corpus as CSV (?since=YYYY-MM-DD for increments). Rights are enforced per series for every tier.

Example curl

curl https://statisticsoftheworld.com/api/v1/series/bulk

Response

series_id,geo,freq,period,period_start,value,obs_status,licence\nUST.YC.10Y,USA,D,2026-07-17,2026-07-17,4.55,,public-domain

GET/api/v1/forecast-revisions/:country

Stored IMF World Economic Outlook readings for six subjects, by publication round. Accepts a source geography code or recognized country slug. Free access returns JSON for one target_year (1980–2100, default current UTC year), showing subjects with at least two populated rounds. A paid key with full=1 returns up to the latest 60 stored target years as JSON or format=csv. Coverage metadata identifies missing values and any year-window limit. Percentage-series revisions are percentage points. Read failures return 503/no-store, not partial data or false absence. Publication-round labels and year offsets do not certify observation status or immutable publisher archives.

Example curl

curl https://statisticsoftheworld.com/api/v1/forecast-revisions/CAN

Response

Illustrative structure (not actual CAN readings): {"country":"CAN","targetYear":2026,"series":[{"indicator":"NGDP_RPCH","label":"Real GDP growth","firstEstimate":{"vintage":"2021-10","value":3.25},"latest":{"vintage":"2025-04","value":2.5},"totalRevision":-0.75,"revisionUnit":"percentage points",...}]}

GET/api/pro/dataset

Paid bulk files, authenticated with X-API-Key. file=latest, dictionary, countries and license accompany the reviewed World Bank bundle; calendar contains independently sourced institutional schedules. file=forecast-revisions streams the stored IMF panel for six subjects (1.25M+ numeric rows, about 66 MB), with forecast-dictionary and forecast-license alongside it. Forecast headers identify the database read, export generation and omitted null-value rows. Each CSV chunk is checked against the complete generation; preflight failure returns 503 and later failure aborts the download. Keep source_unit_code unchanged and use the dictionary for scale and geography caveats; country_iso3 includes non-ISO3 source codes. Call with no file parameter to check entitlement.

Example curl

curl -H "X-API-Key: sotw_…" "https://statisticsoftheworld.com/api/pro/dataset?file=forecast-revisions" -o sotw-forecast-revisions.csv

Response

source,vintage,country_iso3,indicator_id,target_year,horizon,value,source_unit_code\nIMF,2019-10,CAN,NGDP_RPCH,2020,1,1.821,pcent_change

Series history and failed reads

For /api/v1/series/:id, ?as_of=YYYY-MM-DD applies recorded value revisions from an archive collected since July 18, 2026. It is a partial rollback of current rows, not a complete historical snapshot: insertions, deletions and status-only changes are not reconstructed. Read the response’s provenance details before relying on a historical selection.

The complete cross-geography mode, latest=1, cannot be combined with geo, from, to, limit or as_of; incompatible parameters return 400. Invalid cutoffs and dates before the archive began also return 400. A successfully checked unknown series returns 404. Failed catalog, observation or revision reads return 503 with Cache-Control: no-store; successful empty results remain distinct from failures.

For series bulk CSV, a catalog failure is rejected before streaming. A later chunk failure interrupts the stream. Discard an interrupted file and retry; its initial HTTP status alone does not establish a complete download.

Data Sources

IMF World Economic Outlook

World Bank WDI

FRED (Federal Reserve)

Yahoo Finance

European Central Bank

Alpha Vantage

ExchangeRate-API