Rankings

n is on every row and is the same on every row: the number of countries ranked that year. It is what makes ranks comparable across indicators — rank 40 of 213 and rank 40 of 61 are very different facts, and rank / n is the percentile that reconciles them.

year=latest does not mean the newest year present. It means the newest ranked, non-projection year, and the cutoff is per indicator.

This matters because several providers ship forecast years inside the same series as their estimates — UN population projections run to 2100, IMF forecasts a few years ahead. A plain maximum would open a population league table on the year 2100. So latest is capped at the indicator’s own newest observed year, which is why a series the catalogue lists as updated in 2023 resolves to 2023 rather than to this calendar year.

• The resolved year is always in meta.year. Read it rather than assuming.
• Projection years remain reachable — ask for one explicitly with ?year=2050. They are simply never the default.
• An indicator that is entirely projection still resolves, falling back to the newest year it has.

curl -sS "https://api.worldgovdata.com/v1/rankings/wgi.control_of_corruption?year=2015" \
  -H "Authorization: Bearer $WGD_API_KEY"

• 400 bad_year — year was neither latest nor four digits.
• 401 unauthorized — no key.
• 402 insufficient_credits — balance below 1.
• 404 indicator_not_found — no such id, or a series we may not redistribute.
• 404 no_rankings — the indicator exists but has no ranked years at all. Series flagged no_rank in the catalogue are never ranked; read their values from /v1/data instead.

• indicator — echoed back.
• year — the resolved year, which is the only place to learn what latest meant.
• higher_is_better — the direction. Nullable, for concepts with no better end.
• count — rows returned. Equal to n on the rows, except in the empty case.
• coverage — n_countries, yr_min, yr_max, latest_year. Omitted entirely when the indicator has no coverage row yet, so check for the key rather than for a null.
• licence and attribution — the terms for this series.

• Flat price. One credit whether the indicator ranks twelve countries or two hundred. For a whole-world cross-section this is dramatically cheaper than the same query through /v1/data.
• One year per request. There is no range. A rank-over-time view means one request per year — or pull the values from /v1/data and rank them yourself.
• Only enabled countries appear. The spine join means a country we do not serve is absent from the ranking even if the provider ranked it.
• Display-tier indicators are served here. Displaying them is exactly what that tier permits. If you intend to redistribute, check access_tier on the indicator record first — this response does not carry it. See Licensing.
• Ties. Ranks come from the ranking mart, not from a sort you can influence. Two identical values receive the order the mart computed; do not build logic that assumes strictly increasing values down the list.
• Cache it yourself. A league table changes when its provider publishes — once a year for most of these. The response comes back private, no-store because it is authenticated and carries your balance, so the cache has to be inside your application rather than in front of it.

• /v1/indicators — find the id, and read no_rank, higher_is_better and coverage before you spend anything.
• /v1/countries/{iso3} — the same comparison from the other direction: one country, every indicator, with its rank attached.
• /v1/data — the underlying series.