Africa public data API

Overview

The API serves the same data you see on PollsAfrica, built from the same files, so a page and the API never disagree. Responses are JSON with a fixed envelope: your rows are in data and the source, update date, licence and a ready citation are in meta.

If you only need a file, the CSV and open JSON downloads need no key at all. The API is for code that wants filtered, paged rows or a stable address for each resource.

Base address: https://pollsafrica.com/api/v1

Authentication

Send your key in the Authorization header. The X-API-Key header works too. Keys never go in the address, so they stay out of logs and shared links.

curl -H "Authorization: Bearer YOUR_KEY" \
  "https://pollsafrica.com/api/v1/offices?country=ghana"

A request without a key gets 401 and a message that says where to find a key and where the open files are. Only the endpoint list at /api/v1 answers without a key. We chose this over an anonymous allowance because the open JSON files already cover anonymous use with no limit to manage.

Endpoints

All endpoints use GET. Browsers can call them too: cross-origin requests are allowed.

Dataset and indicator ids are listed at /api/v1/datasets. They match the file names on the data page.

Query parameters

• country: the country slug, such as ghana, or the country name. Works on any dataset that has a country column.
• limit: rows per page. The default is 100 and the most you can ask for is 1,000.
• offset: how many rows to skip. meta.next holds the address of the next page, or null on the last page.
• Any column name, for example status=upcoming on elections, keeps only rows with that exact value.

Example

curl -H "Authorization: Bearer YOUR_KEY" \
  "https://pollsafrica.com/api/v1/elections?limit=1"

{
  "data": [
    {
      "id": "comoros-0",
      "country": "Comoros",
      "label": "Presidential election",
      "date": "2024-01-14",
      "status": "held",
      "source_url": "https://www.electionguide.org/countries/"
    }
  ],
  "meta": {
    "source": "https://pollsafrica.com/elections",
    "updated": "2026-10-09",
    "licence": "CC BY 4.0",
    "licence_url": "https://creativecommons.org/licenses/by/4.0/",
    "cite": "PollsAfrica (year). Elections. Retrieved ... from https://pollsafrica.com/elections",
    "dataset": "elections",
    "total": 121,
    "limit": 100,
    "offset": 0
  }
}

Rate limits

The free tier allows 1,000 requests per key per day. The count resets at 00:00 UTC. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (a Unix time). Past the limit you get 429 with a Retry-After header in seconds. Cache what you fetch: the data changes on the schedule shown on the data page, not by the minute.

Errors

Errors share one shape, and the HTTP status tells you the class of problem.

{ "error": { "code": "missing_key", "message": "..." }, "meta": { "docs": "https://pollsafrica.com/developers" } }

Licence and attribution

The data is free to use, share and adapt, including commercially, under CC BY 4.0, as long as you credit PollsAfrica and say if you changed it. Each response includes the licence and a citation in meta. Please show that credit where your readers see the data.

Citing the data

Use meta.cite as written. It names the dataset, the year of its last update and the page that explains it. Where a dataset release has a DOI, the citation uses the DOI link instead of the page address. To cite one survey question, use the line under that question in the question bank.

Get a key

Tell us what you are building on the API access request. We read every request and send a key to the email you give. Keys are free. Each key is yours alone: if one leaks, tell us and we switch it off the same day.