Indicators

licence, licence_url and attribution appear twice — once at the top level and once inside provider. They are the same values; the flat aliases exist so a consumer never has to reach into a nested object for a legal obligation.

q= is the fastest way from a phrase to an id. It splits on whitespace and requires every token to appear in the name, the id or the description, then ranks: a name starting with the whole phrase first, then names containing every token, then everything else.

curl -sS "https://api.worldgovdata.com/v1/indicators?q=life%20expectancy&limit=10"

Relevance order also wins over the default sort while q is set. Sending dir alone will not displace it — there is no column to reverse until you name a sort. Set sort explicitly if you want alphabetical results from a search.

Each sort has the direction that makes sense for it — widest coverage first, most recent year first, names A to Z — so omitting dir gives you the useful order. Setting dir reverses the sort column and nothing else: the name tie-break stays ascending and nulls stay last, so sort=coverage&dir=asc means “fewest countries first” rather than “unknown first, then Z to A”. An unknown value for either returns 400 bad_sort or 400 bad_dir, naming the accepted set.

meta carries count (rows here), total (rows matching), and an echo of every filter you sent. Three things to know:

• total equals count on an unpaged response — the real count is only computed when the response is actually paged.
• limit is not echoed. offset is. Track your own page size.
• Anything you did not send is omitted, so an absent topic means “no topic filter”, not null.

Full paging recipe on Pagination.

• Only servable indicators appear. Series we may not redistribute are absent from this list entirely, so its length is the real size of what you can use.
• An empty result is a 200, not a 404. A filter that matches nothing returns an empty array with count: 0.
• Unit is free text. Do not parse it, and do not assume two series with the same-looking unit are comparable. Read description.
• No limit means everything. Without a filter and without a limit, this endpoint returns the entire catalogue in one response. That is free but it is not small — page it.

Up to twelve indicators worth looking at next, merged from four sources in descending order of confidence, deduplicated by id, with the indicator itself excluded:

• Curated links — a human recorded the relationship. Highest confidence.
• Automatic same-concept links — different providers measuring the same thing.
• Computed correlations — strongest statistical association over shared country-years. relation: "correlated".
• Same-topic fallback — widest coverage in the same topic, so the array is never empty. relation: "related".

Each entry is { id, name, topic, unit, relation }. The relation string is what tells you which tier you are looking at, and the array is ordered strongest first — so a “see also” strip can simply take the first few.

The detail response’s meta is deliberately thin: generated_at, licence and attribution. There is no count — it is a single object.

• 404 indicator_not_found — no enabled, redistributable indicator has that id. The message repeats the id you sent, which is usually enough to spot the typo. Note that a series we may not redistribute produces this same 404 rather than a 403: from the API’s point of view it does not exist.

There is no 401 or 402 here — the endpoint is free and needs no key.