API de dados abertos de África

Consulte os nossos titulares de cargos, listas de ministros, eleições e indicadores económicos em JSON. O nível gratuito é apenas de leitura e requer uma chave. Tudo é licenciado CC BY 4,0.

Nesta página

Visão geral
Autenticação
Pontos finais
Parâmetros de consulta
Exemplo
Limites de pedidos
Erros
Licença e atribuição
Citar os dados
Obter uma chave

Visão geral

A API serve os mesmos dados que vê em PollsAfrica, construídos a partir dos mesmos ficheiros, pelo que uma página e a API nunca divergem. As respostas são JSON com um envelope fixo: as suas linhas estão em data e a fonte, a data de atualização, a licença e uma citação pronta estão em meta.

Se só precisa de um ficheiro, os Transferências em CSV e JSON aberto não precisam de chave nenhuma. A API destina-se a código que quer linhas filtradas e paginadas ou um endereço estável para cada recurso.

Endereço base: https://pollsafrica.com/api/v1

Autenticação

Envie a sua chave no cabeçalho Authorization. O cabeçalho X-API-Key também funciona. As chaves nunca vão no endereço, por isso ficam fora dos registos e dos links partilhados.

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

Um pedido sem chave recebe 401 e uma mensagem que indica onde encontrar uma chave e onde estão os ficheiros abertos. Apenas a lista de endpoints em /api/v1 responde sem chave. Escolhemos isto em vez de uma quota anónima porque os ficheiros JSON abertos já cobrem o uso anónimo sem limite a gerir.

Pontos finais

Todos os endpoints usam GET. Os navegadores também podem chamá-los: os pedidos de origem cruzada são permitidos.

Caminho	Declarações
`/api/v1`	A lista de pontos de acesso. Abertos, sem necessidade de chave.
`/api/v1/countries`	Países no diretório de governos, com o número de titulares de cargos e de ministros.
`/api/v1/offices`	Titulares de cargos nacionais, uma linha por cargo.
`/api/v1/cabinets`	Ministros por pasta, uma linha por ministro.
`/api/v1/elections`	Eleições nacionais passadas e futuras, uma linha por eleição.
`/api/v1/indicators`	Os conjuntos de dados de indicadores: economia, orçamentos, preços dos combustíveis, salário mínimo, feriados, constituições e índices.
`/api/v1/indicators/{id}`	Linhas de um conjunto de dados de um indicador.
`/api/v1/datasets`	Todos os conjuntos de dados que a API serve, com a respetiva data da última atualização.
`/api/v1/datasets/{id}`	Linhas de qualquer conjunto de dados por id.

Os identificadores de conjuntos de dados e indicadores estão indicados em /api/v1/datasets. Correspondem aos nomes dos ficheiros na página de dados.

Parâmetros de consulta

country: o identificador do país, como ghana, ou o nome do país. Funciona em qualquer conjunto de dados que tenha uma coluna de país.
limit: linhas por página. O valor predefinido é 100 e o máximo que pode pedir é 1000.
offset: quantas linhas saltar. meta.next contém o endereço da página seguinte, ou null na última página.
Qualquer nome de coluna, por exemplo status=upcoming em eleições, mantém apenas as linhas com esse valor exato.

Exemplo

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

{
  "data": [
    {
      "id": "nigeria-0",
      "country": "Nigeria",
      "label": "Presidential election",
      "date": "2015-03-28",
      "status": "held",
      "source_url": "https://www.inecnigeria.org"
    }
  ],
  "meta": {
    "source": "https://pollsafrica.com/elections",
    "updated": "2026-10-21",
    "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": 126,
    "limit": 100,
    "offset": 0
  }
}

Limites de pedidos

O nível gratuito permite 1000 pedidos por chave e por dia. A contagem é reiniciada às 00:00 UTC. Cada resposta inclui X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (uma hora Unix). Acima do limite, recebe 429 com um cabeçalho Retry-After em segundos. Guarde em cache o que consulta: os dados mudam segundo o calendário indicado em página de dados, não ao minuto.

Erros

Os erros partilham uma forma comum, e o estado HTTP indica a classe do problema.

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

Estado	Código	Significado
401	`missing_key`, `invalid_key`, `revoked_key`	Sem chave, com uma chave desconhecida ou com uma chave que desativámos.
404	`not_found`	Caminho, conjunto de dados ou identificador de indicador desconhecido.
429	`rate_limited`	O limite diário está esgotado.
503	`unavailable`	Não foi possível verificar a sua chave neste momento. Tente novamente em breve.

Licença e atribuição

Os dados são livres de usar, partilhar e adaptar, incluindo comercialmente, ao abrigo de CC BY 4.0, desde que atribua o crédito a PollsAfrica e indique se os alterou. Cada resposta inclui a licença e uma citação em meta. Mostre esse crédito onde os seus leitores veem os dados.

Citar os dados

Utilize meta.cite tal como está escrito. Indica o conjunto de dados, o ano da sua última atualização e a página que o explica. Quando uma versão de um conjunto de dados tem um DOI, a citação utiliza a ligação DOI em vez do endereço da página. Para citar uma pergunta de um inquérito, utilize a linha por baixo dessa pergunta no banco de perguntas.

Obter uma chave

Diga-nos o que está a construir com o Pedido de acesso à API. Lemos todos os pedidos e enviamos uma chave para o email que indicar. As chaves são gratuitas. Cada chave é só sua: se uma se divulgar, avise-nos e desativamo-la no mesmo dia.