API reference

One REST API for the whole platform. JSON only, versioned under /api/v1.

Authentication

Create a key on your account page, then send it as a bearer token. Keys are free.

curl -H "Authorization: Bearer ec_ab12cd34.YOUR_SECRET" \
  "https://mondo.international/api/v1/datasets"

X-API-Key and ?api_key= are accepted too, for tools that cannot set headers.

Authorisation is the licence, not the key

A valid key gets you the catalogue. Observations are served only for datasets whose licence you have accepted for the use you declare. If you have not, the API returns 403 with the exact licence you need and a link to accept it.

{
  "error": {
    "code": "licence_acceptance_required",
    "message": "You have not accepted the licence terms for the requested data...",
    "declined": [{"dataset": "wb-trade-openness", "licence": {"code": "CC-BY-4.0"}, ...}],
    "accept_at": "https://mondo.international/account/"
  }
}

Endpoints

Endpoint	Scope	What it returns
GET /api/v1/	—	Service description and endpoint index
GET /api/v1/meta	—	Languages, limits, row counts
GET /api/v1/licences	—	The licence register, machine readable
GET /api/v1/sources	—	Providers and their terms
GET /api/v1/questions	—	The question-first navigation as data
GET /api/v1/datasets	catalog:read	Catalogue, with your access decision per dataset
GET /api/v1/datasets/<slug>	catalog:read	One dataset with indicators and freshness
GET /api/v1/areas	catalog:read	Geographies with ISO codes
GET /api/v1/observations	data:read	The data. Licence-gated.
GET /api/v1/search	catalog:read	Questions, datasets, indicators and areas matching a query
GET /api/v1/freshness	catalog:read	When each dataset was last refreshed and whether it is stale

Querying observations

Parameter	Example	Notes
dataset	wb-trade-openness	Slug. Either this or indicator is required.
indicator	NE.TRD.GNFS.ZS,NE.EXP.GNFS.ZS	Comma separated source codes
area	CAN,FRA,JPN,CHN	ISO-3, ISO-2, NUTS or aggregate codes
partner	USA	For bilateral series only
start / end	2000 / 2024	Years, inclusive
use	commercial	Declared use for this request; must be permitted by the licence
limit / offset	5000 / 0	Max 50000
lang	fr	en, fr, ja, zh

Try it

curl -H "Authorization: Bearer $EC_KEY" \
  "https://mondo.international/api/v1/observations?dataset=abs-national-accounts&area=CAN,FRA,JPN&start=2010"
curl -H "Authorization: Bearer $EC_KEY" \
  "https://mondo.international/api/v1/observations?dataset=bis-policy-rates&area=CAN,FRA,JPN&start=2010"
curl -H "Authorization: Bearer $EC_KEY" \
  "https://mondo.international/api/v1/observations?dataset=ecb-hicp-inflation&area=CAN,FRA,JPN&start=2010"

Response shape

{
  "count": 45,
  "declared_use": "academic",
  "licences": { "CC-BY-4.0": { "name": "...", "attribution": "..." } },
  "citation": ["Mondo (2026). Trade openness... Licence: CC BY 4.0."],
  "observations": [
    { "dataset": "wb-trade-openness", "indicator": "NE.TRD.GNFS.ZS",
      "area": "CAN", "partner": null, "period": "2024-12-31",
      "value": 67.4, "unit": null, "status": null }
  ]
}

Who may call it

There is no anonymous tier. Every endpoint except this service description requires a key, and a key only works once the address on its account has been confirmed by clicking a link sent to it. That costs a person one click; it costs a script a working mailbox for every key it wants, which is the point.

This is not about charging for the data. The data is free and the keys are free. It is about the API being used by people we can reach if something goes wrong, and about not becoming an anonymous proxy for providers whose terms we accepted on your behalf.

Limits

Default 60/minute. Each key also carries a monthly quota, visible on your account page. Ask if you need more; the point of this platform is that you use the data.