Public API

The Civica API provides read-only access to government structure data for 250+ countries. All responses are JSON. No authentication is required.

Base URL

https://civicaatlas.org/api/v1

Rate Limits

60 requests per minute per IP address. Exceeding the limit returns a 429 status with a Retry-After header.

CORS

All endpoints support cross-origin requests. The API sets Access-Control-Allow-Origin: *.

API Status

Check current API status on our status page ↗

Endpoints

GET/api/v1/countries

Returns a paginated list of sovereign states with basic metadata. Filter by continent or government type.

Parameters

continentstringFilter by continent (e.g. "Africa", "Europe")

government_typestringFilter by government type (partial match, e.g. "republic")

limitintegerResults per page (default 50, max 250)

offsetintegerNumber of results to skip (default 0)

Example Response

{
  "data": [
    {
      "slug": "united-states",
      "name": "United States",
      "iso2": "US",
      "iso3": "USA",
      "continent": "North America",
      "capital": "Washington, DC",
      "population": 339996563,
      "governmentType": "presidential republic",
      "governmentTypeDetail": "constitutional federal republic",
      "gdpBillions": 25.46,
      "areaSqKm": 9833520,
      "flagUrl": "..."
    }
  ],
  "meta": {
    "total": 195,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}

GET/api/v1/countries/:code

Returns detailed government structure for a single country. Look up by slug, ISO 3166-1 alpha-2, or alpha-3 code.

Parameters

:codestringCountry slug, ISO-2, or ISO-3 code (e.g. "us", "USA", "united-states")

Example Response

{
  "data": {
    "slug": "france",
    "name": "France",
    "iso2": "FR",
    "iso3": "FRA",
    "continent": "Europe",
    "capital": "Paris",
    "population": 68170228,
    "governmentType": "semi-presidential republic",
    "governmentTypeDetail": "...",
    "gdpBillions": 2.78,
    "areaSqKm": 643801,
    "languages": "French",
    "currency": "Euro (EUR)",
    "democracyIndex": 7.99,
    "flagUrl": "...",
    "constitution": { "year": 1958, "yearUpdated": 2008 },
    "government": {
      "executive": [
        {
          "name": "Presidency of France",
          "type": "head_of_state",
          "offices": [
            {
              "name": "President",
              "type": "head_of_state",
              "currentHolder": {
                "name": "Emmanuel Macron",
                "party": "Renaissance",
                "since": "2017-05-14",
                "photoUrl": "..."
              }
            }
          ]
        }
      ],
      "legislative": [...]
    }
  }
}

GET/api/v1/government-types

Returns all government type classifications with the number of countries under each type, plus the five most populous examples.

Example Response

{
  "data": [
    {
      "governmentType": "presidential republic",
      "count": 42,
      "topExamples": ["United States", "Brazil", "Indonesia", "Nigeria", "Mexico"]
    },
    {
      "governmentType": "parliamentary republic",
      "count": 31,
      "topExamples": ["India", "Germany", "Italy", "South Africa", "Ethiopia"]
    }
  ],
  "meta": { "total": 12 }
}

Usage Examples

curl

curl "https://civicaatlas.org/api/v1/countries?continent=Europe&limit=10"
curl "https://civicaatlas.org/api/v1/countries/us"
curl "https://civicaatlas.org/api/v1/government-types"

JavaScript (fetch)

const res = await fetch("https://civicaatlas.org/api/v1/countries/fr");
const { data } = await res.json();
console.log(data.government.executive);

Python (requests)

import requests

resp = requests.get("https://civicaatlas.org/api/v1/countries", params={"government_type": "monarchy"})
for country in resp.json()["data"]:
    print(country["name"], country["population"])

Data Sources & Licensing

API data is sourced from the CIA World Factbook (public domain, archived January 2026), Wikidata (CC0), IPU Parline, and the Constitute Project. All public-domain and CC0 data is freely available for any use. Data from IPU Parline and Constitute Project is subject to their respective non-commercial licenses.

Widget Embed

Embed a live Civica Index widget on any website using a standard <iframe>. Widgets update every 5 minutes and respect the visitor’s system color scheme by default. Override with ?theme=light or ?theme=dark. Add ?dims=1 to the large widget to show dimension mini-bars.

Small — 300 × 80

<iframe src="https://civicaatlas.org/embed/brazil?size=sm"
        width="300" height="80" loading="lazy"
        title="Civica Index — Brazil"></iframe>

Medium — 320 × 180

<iframe src="https://civicaatlas.org/embed/denmark?size=md"
        width="320" height="180" loading="lazy"
        title="Civica Index — Denmark"></iframe>

Large — 400 × 260 (with dimensions)

<iframe src="https://civicaatlas.org/embed/brazil?size=lg&dims=1"
        width="400" height="260" loading="lazy"
        title="Civica Index — Brazil"></iframe>

Query Parameters

sizesm | md | lgWidget dimensions. Default: md

themelight | darkOverride color scheme. Default: system prefers-color-scheme

dims0 | 1Show 6 dimension mini-bars in large widget. Default: 0