API

A public, read-only JSON API — the same one that builds every page of this site.

Every country, indicator, ranking, comparison, map and change on CountryAtlas is served by this API. Responses are plain JSON, every value carries a provenance object, and identifiers are human-readable slugs. No key is needed.

Base URL: https://www.countryatlas.co/api/v1
Interactive docs (Swagger): /api/v1/docs
OpenAPI specification: /api/v1/openapi.json

Endpoints

All GET, all JSON. Countries accept ISO3 or slug; indicators, topics and groups accept their slug.

Endpoint	Returns
`GET /health`	Snapshot status, counts, version.
`GET /countries?region=&income=&q=&sort=`	Country directory with filters and sort.
`GET /countries/{id}`	Country overview: header, groups, coverage, headline metrics, topics.
`GET /countries/{id}/topics/{topic}`	All indicators of a topic for one country, grouped by subtopic.
`GET /countries/{id}/series/{indicator}?from=&to=`	Full history of one indicator for one country.
`GET /countries/{id}/changes`	Recent detected changes for a country.
`GET /countries/{id}/events`	Whole-history timeline of a country.
`GET /countries/{id}/similar?mode=`	Nearest peers per mode with contributions.
`GET /countries/{id}/insights`	Computed key facts.
`GET /countries/{id}/dna`	Nine-dimension fingerprint.
`GET /countries/{id}/download.csv\|json`	Per-country dataset (CSV or JSON).
`GET /indicators?topic=&q=&source=`	Indicator directory with topic, text and source filters.
`GET /indicators/{slug}`	Definition, sources, coverage, world value, top and bottom five.
`GET /indicators/{slug}/map?year=`	Choropleth values for one year with quantile legend.
`GET /indicators/{slug}/trend?group=`	Aggregate trend for a group (median, mean, weighted mean, sum).
`GET /indicators/{slug}/download.csv\|json`	Per-indicator dataset (CSV or JSON).
`GET /series?country=&indicator=`	Series bundle: several countries × several indicators.
`GET /rankings?topic=`	Rankable indicators.
`GET /rankings/{indicator}?year=&group=&sort=`	Ranking for one indicator, any year, any group.
`GET /rankings/{indicator}/history?countries=`	Rank by year for chosen countries.
`GET /compare?countries=&indicators=&mode=`	Comparison bundle with absolute, per-capita, indexed or % modes.
`GET /compare/snapshot?countries=&topic=`	Latest values table for a topic across countries.
`GET /regions?kind=`	Groups: regions, continents, income groups, organisations.
`GET /regions/{slug}?indicator=`	Group page: members, aggregates, member ranking.
`GET /search?q=&type=`	Typed search across countries, indicators, topics, regions, sources.
`GET /home`	Global snapshot, curated lists, recent changes.
`GET /changes?kind=&indicator=&country=`	Global feed of detected changes with filters.
`GET /sources`	Data sources with counts, licence and freshness.
`GET /sources/{id}`	Source detail: indicators mapped, datasets, import runs.
`GET /methodology`	Registry-derived methodology payload.

Examples

Real responses from the current snapshot, trimmed for length. Copy the command and run it.

A country overview

bash

curl -s "https://www.countryatlas.co/api/v1/countries/canada"

Live response (trimmed)

{
  "country": {
    "id": "CAN",
    "name": "Canada",
    "capital": "Ottawa",
    "region_name": "North America",
    "income_name": "High income"
  },
  "headline": [
    {
      "indicator": "population",
      "formatted": "41.7M",
      "year": 2025,
      "rank_world": 38,
      "n_world": 218,
      "provenance": {
        "source": "worldbank",
        "source_name": "World Bank",
        "dataset": "WDI",
        "series_code": "SP.POP.TOTL",
        "retrieved_at": "2026-09-11T06:47:57Z",
        "source_updated_at": "2026-07-13T00:00:00Z",
        "url": "https://data.worldbank.org/indicator/SP.POP.TOTL?locations=CA",
        "transform": null,
        "licence": "CC BY 4.0"
      }
    },
    {
      "indicator": "gdp",
      "formatted": "US$2.3T",
      "year": 2025,
      "rank_world": 10,
      "n_world": 187,
      "provenance": {
        "source": "worldbank",
        "source_name": "World Bank",
        "dataset": "WDI",
        "series_code": "NY.GDP.MKTP.CD",
        "retrieved_at": "2026-09-11T06:47:53Z",
        "source_updated_at": "2026-07-13T00:00:00Z",
        "url": "https://data.worldbank.org/indicator/NY.GDP.MKTP.CD?locations=CA",
        "transform": null,
        "licence": "CC BY 4.0"
      }
    }
  ],
  "…": "12 headline metrics"
}

One series with history and provenance

bash

curl -s "https://www.countryatlas.co/api/v1/countries/CAN/series/gdp-per-capita?from=2022"

Live response (trimmed)

{
  "indicator": {
    "slug": "gdp-per-capita",
    "name": "GDP per capita (current US$)"
  },
  "unit": "current US$",
  "values": [
    {
      "period": "2022-01-01",
      "year": 2022,
      "value": 56496.9275340663,
      "is_forecast": false,
      "status": "imported"
    },
    {
      "period": "2023-01-01",
      "year": 2023,
      "value": 54847.5370112652,
      "is_forecast": false,
      "status": "imported"
    },
    {
      "period": "2024-01-01",
      "year": 2024,
      "value": 55015.7066917734,
      "is_forecast": false,
      "status": "imported"
    }
  ],
  "…": "4 values",
  "stats": {
    "min": {
      "year": 2023,
      "value": 54847.5370112652
    },
    "max": {
      "year": 2022,
      "value": 56496.9275340663
    },
    "first": {
      "year": 2022,
      "value": 56496.9275340663
    },
    "last": {
      "year": 2025,
      "value": 55697.6639660837
    },
    "cagr": -0.4738089756876951,
    "n": 4
  },
  "provenance": {
    "source": "worldbank",
    "source_name": "World Bank",
    "dataset": "WDI",
    "series_code": "NY.GDP.PCAP.CD",
    "retrieved_at": "2026-09-11T06:47:53Z",
    "source_updated_at": "2026-07-13T00:00:00Z",
    "url": "https://data.worldbank.org/indicator/NY.GDP.PCAP.CD?locations=CA",
    "transform": null,
    "licence": "CC BY 4.0"
  }
}

A ranking, three rows

bash

curl -s "https://www.countryatlas.co/api/v1/rankings/gdp-per-capita?limit=3"

Live response (trimmed)

{
  "indicator": "gdp-per-capita",
  "year_used": 2025,
  "n": 187,
  "rows": [
    {
      "rank": 1,
      "country": "Luxembourg",
      "formatted": "US$147.3k",
      "change_1y": "+6.9 %"
    },
    {
      "rank": 2,
      "country": "Ireland",
      "formatted": "US$131.6k",
      "change_1y": "+16.6 %"
    },
    {
      "rank": 3,
      "country": "Switzerland",
      "formatted": "US$114.8k",
      "change_1y": "+6.6 %"
    }
  ]
}

Map values for one year

bash

curl -s "https://www.countryatlas.co/api/v1/indicators/life-expectancy/map?year=2023"

Live response (trimmed)

{
  "year_used": 2023,
  "n": 217,
  "legend": {
    "min": 54.462,
    "max": 86.372,
    "breaks": [
      66.331,
      71.146,
      74.552,
      77.725,
      81.69
    ],
    "n_classes": 6
  },
  "values": {
    "CAN": 81.6263414634146,
    "JPN": 84.0412195121951,
    "NGA": 54.462,
    "…": "217 countries"
  },
  "provenance": {
    "source": "worldbank",
    "source_name": "World Bank",
    "dataset": "WDI",
    "series_code": "SP.DYN.LE00.IN",
    "retrieved_at": "2026-09-11T06:48:03Z",
    "source_updated_at": "2026-07-13T00:00:00Z",
    "url": "https://data.worldbank.org/indicator/SP.DYN.LE00.IN",
    "transform": null,
    "licence": "CC BY 4.0"
  }
}

Search

bash

curl -s "https://www.countryatlas.co/api/v1/search?q=canada%20gdp&limit=3"

Live response (trimmed)

{
  "q": "canada gdp",
  "n": 3,
  "hits": [
    {
      "type": "country_indicator",
      "name": "Canada · GDP (current US$)",
      "hint": "Country indicator · Indicator · Economy · current US$",
      "url": "/countries/canada?indicator=gdp"
    },
    {
      "type": "country_indicator",
      "name": "Canada · GDP per capita (current US$)",
      "hint": "Country indicator · Indicator · Economy · current US$",
      "url": "/countries/canada?indicator=gdp-per-capita"
    },
    {
      "type": "country_indicator",
      "name": "Canada · GDP per capita, PPP (current international $)",
      "hint": "Country indicator · Indicator · Economy · current international $",
      "url": "/countries/canada?indicator=gdp-per-capita-ppp"
    }
  ]
}

Recent changes

bash

curl -s "https://www.countryatlas.co/api/v1/changes?limit=2"

Live response (trimmed)

{
  "n": 2,
  "items": [
    {
      "country": "Ethiopia",
      "indicator": "gdp",
      "kind": "yoy_drop",
      "year": 2025,
      "severity": 1,
      "headline": "GDP fell 15.6 % to US$ 126.4B in 2025 (largest drop since 1994)."
    },
    {
      "country": "Ethiopia",
      "indicator": "gdp-per-capita",
      "kind": "yoy_drop",
      "year": 2025,
      "severity": 1,
      "headline": "GDP per capita fell 17.7 % to US$ 933 in 2025 (largest drop since 1994)."
    }
  ]
}

The provenance object

Attached to every value the API returns.

Headline metrics, series points, ranking rows, map values and change items all carry a provenance object: the source connector and display name, dataset and series code, when the pipeline retrieved it, when the source last updated it, a deep link to the source page, the transformation applied (if any) and the source licence. Series responses also list every source used with the number of values from each.

json

{
  "value": 55697.66,
  "period": "2025-01-01",
  "year": 2025,
  "formatted": "55.7k",
  "status": "imported",
  "provenance": {
    "source": "worldbank",
    "source_name": "World Bank",
    "dataset": "WDI",
    "series_code": "NY.GDP.PCAP.CD",
    "retrieved_at": "2026-09-11T06:49:30Z",
    "source_updated_at": "2026-07-13T00:00:00Z",
    "url": "https://data.worldbank.org/indicator/NY.GDP.PCAP.CD?locations=CA",
    "transform": null,
    "licence": "CC BY 4.0"
  }
}

Field	Meaning
source / source_name	Connector id (worldbank, imf, oecd, eurostat, who, fred, owid, bis, ilo) and its display name.
dataset, series_code	Dataset and series inside the source (WDI NY.GDP.PCAP.CD, WEO NGDPDPC, OWID co2_per_capita…).
retrieved_at	When the pipeline fetched the payload (UTC).
source_updated_at	Last update advertised by the source; null when it publishes none.
url	Deep link to the series at the source, with the country when the portal supports it.
transform	Expression applied at normalisation (e.g. x*1e9), null if none.
licence	Licence of the source for this series.

Rate limits & caching

120 requests per minute per IP (429 with a Retry-After header beyond that). Responses are cached per snapshot; the X-CountryAtlas-Run header names the snapshot and X-Cache says whether the cache served you. Please cache on your side too — data changes at most once a day.

Errors

RFC 7807 problem+json: 404 for an unknown country, indicator, topic or group (with a hint in detail), 400 for a bad combination, 422 for an invalid parameter, 429 when rate-limited, 503 while the first snapshot is being built.

Licence

The compilation is CC BY 4.0; each value keeps its source licence in provenance.licence. Attribute the original sources and CountryAtlas.

Sources →·Methodology →

Questions or higher limits?

Made by Simon-Pierre Boucher · contact@spboucher.ai·Hosted on MacLustr