Documentation / Endpoints

Getting started

Core concepts

Endpoints

Reference

Endpoints

Countries

The country spine: the 12-field record every observation in the platform hangs off, and a per-country digest of the latest value for every indicator we hold.

GET /v1/countries

GET/v1/countries

Auth: Optional — anonymous callers are IP rate-limited
Cost: free
Returns: Array of country records
Order: By name, ascending

Base https://api.worldgovdata.com/v1

The full spine, or a filtered slice of it. This is where you get the ISO3 codes every other endpoint expects. Small enough to fetch once at startup and cache.

Query parameters

Query parameters
Parameter	Description
`region`string	Exact match against the region as stored in the spine. Not fuzzy and not case-insensitive — take the values from an unfiltered call.example: South Asia
`income_group`string	Exact match against the World Bank income group.example: High income

Request

curl -sS "https://api.worldgovdata.com/v1/countries?region=South%20Asia"

Response · 200

{
  "data": [
    {
      "iso3": "AFG",
      "iso2": "AF",
      "m49": 4,
      "name": "Afghanistan",
      "official_name": "Islamic Republic of Afghanistan",
      "region": "South Asia",
      "subregion": "Southern Asia",
      "income_group": "Low income",
      "wb_code": "AFG",
      "capital": "Kabul",
      "wikidata_id": "Q889",
      "flag_emoji": "🇦🇫"
    },
    {
      "iso3": "BGD",
      "iso2": "BD",
      "m49": 50,
      "name": "Bangladesh",
      "official_name": "People's Republic of Bangladesh",
      "region": "South Asia",
      "subregion": "Southern Asia",
      "income_group": "Lower middle income",
      "wb_code": "BGD",
      "capital": "Dhaka",
      "wikidata_id": "Q902",
      "flag_emoji": "🇧🇩"
    }
    // … 6 more, ordered by name
  ],
  "meta": {
    "generated_at": "2026-07-28T09:14:02.481932+00:00",
    "count": 8,
    "region": "South Asia"
  }
}

Fields

Fields of a country record
Field	Type	Notes
iso3	string	ISO 3166-1 alpha-3. The primary key everywhere in the API.
iso2	string \| null	ISO 3166-1 alpha-2.
m49	integer \| null	UN M49 numeric code.
name	string	Common English name. The default sort order.
official_name	string \| null	Long form, e.g. “Republic of India”.
region	string \| null	World Bank region, e.g. “South Asia”.
subregion	string \| null	UN subregion, e.g. “Southern Asia”.
income_group	string \| null	World Bank income group.
wb_code	string \| null	World Bank country code, where it differs from ISO3.
capital	string \| null	Capital city.
wikidata_id	string \| null	Wikidata Q-id, for joining to other datasets.
flag_emoji	string \| null	The regional-indicator pair for the flag.

Only enabled countries are returned, and there is no enabled field in the response — if a country is in the list, it is servable. meta.count is the number of rows; meta.region and meta.income_group echo your filters and are omitted when you did not send them.

Notes

Filters are exact strings. region=south asia matches nothing and returns an empty array with a 200 — not a 404. Fetch the list once and read the distinct values off it.
The two filters combine with AND.
Several fields are nullable. Small territories in particular may have no income_group, no capital or no m49. Do not key a join on a nullable field.

GET /v1/countries/{iso3}

GET/v1/countries/{iso3}

Auth: Bearer key required
Cost: 1
Returns: One country object, plus topics
Order: Topic, then curated sort, then name

Base https://api.worldgovdata.com/v1

One country’s record with a topics map appended: for every indicator we hold for that country, its latest value, the year it is from, and the country’s rank on it. This is the endpoint behind a country profile page.

Parameters

Parameters
Parameter	Description
`iso3`path, ISO3 code · required	Case-insensitive; upper-cased for you before the lookup.example: IND
`featured`boolean	Restrict the topic lists to featured indicators — the curated headline set the portal’s country pages use. `featured=false` gives you the complement, which is rarely what you want.default: unset (everything) · example: true
`topic`string	Restrict to one topic. Combines with `featured`.example: health

Request

curl -sS "https://api.worldgovdata.com/v1/countries/IND?featured=true" \
  -H "Authorization: Bearer $WGD_API_KEY"

Response · 200

{
  "data": {
    "iso3": "IND",
    "iso2": "IN",
    "m49": 356,
    "name": "India",
    "official_name": "Republic of India",
    "region": "South Asia",
    "subregion": "Southern Asia",
    "income_group": "Lower middle income",
    "wb_code": "IND",
    "capital": "New Delhi",
    "wikidata_id": "Q668",
    "flag_emoji": "🇮🇳",
    "topics": {
      "economy": [
        {
          "indicator": "wdi.gdp_per_capita_ppp",
          "name": "GDP per capita, PPP",
          "unit": "2021 intl $",
          "year": 2024,
          "value": 9182.7,
          "rank": 128,
          "rank_delta_1y": 2,
          "featured": true
        }
        // … 9 more economy items
      ],
      "governance": [
        {
          "indicator": "wgi.control_of_corruption",
          "name": "Control of corruption",
          "unit": "0–100 percentile",
          "year": 2024,
          "value": 44.8,
          "rank": 108,
          "rank_delta_1y": -1,
          "featured": true
        }
        // … 9 more governance items
      ]
      // … 11 more topics
    }
  },
  "meta": {
    "generated_at": "2026-07-28T09:14:02.481932+00:00",
    "count": 120,
    "featured": true,
    "topic_counts": {
      "agriculture": 1284,
      "economy": 1180,
      "governance": 214
      // … every topic held for India, unfiltered
    }
  }
}

The topics map

data.topics is keyed by topic slug; each value is an array of items, ordered by the curated within-topic sort and then by name. Each item is:

One topic item

{
  "indicator":     "wgi.control_of_corruption",   // the id to use elsewhere
  "name":          "Control of corruption",
  "unit":          "0–100 percentile",
  "year":          2024,                          // the year this value is from
  "value":         44.8,                          // nullable
  "rank":          108,                           // nullable — absent for unranked series
  "rank_delta_1y": -1,                            // nullable — change since last year
  "featured":      true
}

meta.count is the number of items across all topics, not the number of topics. meta.topic_counts is a map of topic slug to the count we hold unfiltered, so a slim response can still label and lazily expand the long tail — including topics whose items were filtered out entirely.

Notes and gotchas

Flat price. 1 credit whether the response holds ten items or ten thousand.
Year varies by row. Each item carries its own year, because indicators update on different cadences. There is no single “as of” date for the response.
rank may be null. Some series are flagged as not rankable; those items carry a value and no rank.
topic_counts ignores your filters. That is deliberate — it answers “what else is there”, which a filtered count could not.
Latest values, not a series. One row per indicator. For a time series, use /v1/data.
Display-tier data appears here. The export gate is on /v1/data only. Check access_tier before you republish a value you read from this endpoint — Licensing.

Errors

401 unauthorized — no key. This route costs a credit, so it needs one.
402 insufficient_credits — balance below 1.
404 country_not_found — no enabled country has that ISO3 code. The message names the code you sent.

An unknown topic is not an error: it returns a country with an empty topics map, a count of 0, and a full topic_counts that shows you what you could have asked for.

/v1/meta/coverage — per-country observation and indicator totals, free, and a better answer to “how much do you have on X” than the detail endpoint.
/v1/data — the time series behind any of these latest values.
/v1/rankings — the same comparison from the other direction: one indicator, every country.