Skip to content
worldgovdata
Documentation / Endpoints

Getting started

Endpoints

Meta

Two free inventory endpoints: how current each provider is and what it is licensed under, and how much data exists for each country.

Neither takes a parameter and neither needs a key. Both are small enough to fetch once and cache for the life of a process.

GET /v1/meta/freshness

GET/v1/meta/freshness
Auth
Optional — anonymous callers are IP rate-limited
Cost
free
Returns
One row per enabled provider
Order
By provider_id, ascending
Parameters
None

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

The provenance endpoint. For every provider we serve: its licence, its attribution string, how often we re-ingest it, when that last succeeded, and how recent the data itself is.

Request

curl -sS "https://api.worldgovdata.com/v1/meta/freshness"

Response · 200

{
  "data": [
    {
      "provider_id": "aqueduct",
      "name": "WRI Aqueduct 4.0",
      "licence": "CC BY 4.0",
      "attribution": "WRI Aqueduct 4.0 (CC BY 4.0)",
      "cadence": "monthly",
      "upstream": [
        {
          "name": "Global hydrological models (PCR-GLOBWB)",
          "note": "Modelled runoff and water demand drive the water-risk scores."
        },
        {
          "name": "WRI compilation",
          "url": "https://www.wri.org/aqueduct",
          "note": "WRI blends the modelled layers into the composite indicators."
        }
      ],
      "last_ok_finished_at": "2026-07-27T02:00:11.482913+00:00",
      "last_ok_rows": 14760,
      "latest_data_year": 2023
    }
    // … 42 more providers, ordered by provider_id
  ],
  "meta": {
    "generated_at": "2026-07-28T09:14:02.481932+00:00",
    "count": 43
  }
}

Fields

Fields of a provider freshness record
FieldTypeNotes
provider_idstringThe prefix of every indicator id from this provider.
namestringDisplay name of the provider.
licencestringThe licence its data is served under.
attributionstringThe credit line to publish.
cadencestring | nullHow often we re-ingest it — e.g. “monthly”, “annual”.
upstreamarrayOrigins this provider is itself built on. Always an array; may be empty.
last_ok_finished_attimestamp | nullWhen our last successful load of it finished.
last_ok_rowsinteger | nullHow many rows that load wrote.
latest_data_yearinteger | nullThe newest year this provider has actually measured.

Two different kinds of recent

These are easy to conflate and they answer different questions.

  • last_ok_finished_at — when we last pulled successfully. A pipeline fact. If this is old, our copy may be behind the provider’s.
  • latest_data_year — the newest year the provider has actually measured. A data fact. A daily pipeline can still be three years behind the world, because that is how official statistics work.

The upstream array

Several of our providers are aggregators, composites or models: they are built on other institutions’ data. upstream records that lineage — the sources of the sources.

One upstream origin

{
  "name": "WRI compilation",                             // always present
  "url":  "https://www.wri.org/aqueduct",                // optional
  "note": "WRI blends the modelled layers into the …"    // optional
}
  • Always an array — never null. A provider whose lineage has not been recorded returns [].
  • Primary collectors — the institutions that are the origin — carry a single marker entry rather than a list.
  • Curated conservatively: only lineages the provider’s own documentation supports. An absent origin means unrecorded, not disproven.

What to use it for

  • Building an attribution table once, rather than per indicator.
  • Deciding when to re-pull. Compare last_ok_finished_at with your own last sync and skip providers that have not moved — every request you do not make is free.
  • Setting expectations in your own UI. “Latest available: 2023” is a far better answer than a chart that silently stops.
  • Enumerating provider ids for /v1/indicators?provider=….

GET /v1/meta/coverage

GET/v1/meta/coverage
Auth
Optional — anonymous callers are IP rate-limited
Cost
free
Returns
One row per country
Order
By iso3, ascending
Parameters
None

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

The per-country inventory: how many observations and how many distinct indicators exist for each country, and the span of years they cover. This is the honest answer to “how much do you actually have on X”.

Request

curl -sS "https://api.worldgovdata.com/v1/meta/coverage"

Response · 200

{
  "data": [
    {
      "iso3": "ABW",
      "name": "Aruba",
      "n_observations": 68602,
      "n_indicators": 2046,
      "yr_min": 1960,
      "yr_max": 2024
    },
    {
      "iso3": "AFG",
      "name": "Afghanistan",
      "n_observations": 133895,
      "n_indicators": 3153,
      "yr_min": 1960,
      "yr_max": 2024
    }
    // … 216 more, ordered by iso3
  ],
  "meta": {
    "generated_at": "2026-07-28T09:14:02.481932+00:00",
    "count": 218
  }
}

Fields

Fields of a country coverage record
FieldTypeNotes
iso3stringISO 3166-1 alpha-3 country code.
namestringCommon English name.
n_observationsintegerTotal observation rows held for the country.
n_indicatorsintegerDistinct indicators with at least one value for it.
yr_mininteger | nullEarliest year we hold anything for it.
yr_maxinteger | nullLatest year we hold anything for it.

Notes

  • Counts are wide, not deep. n_indicators counts indicators with at least one value — it says nothing about how many years each covers.
  • yr_min and yr_max span everything. They are the outer bounds across all indicators for that country, so they describe a hull rather than any one series. Use an indicator’s own coverage for a series-level answer.
  • Coverage varies enormously. A large economy may hold ten times what a small territory does. Design for the sparse end.
  • Not a rate-limit exemption. Free means no credits; requests still count against your rate limit. Fetch it once.

Related

  • Licensing — what the licence and attribution fields oblige you to do.
  • Sources — the same lineage, rendered.
  • /v1/indicators — per-series coverage, which is the finer-grained answer.