Documentação não oficial da API DivulgaCandContas

O Tribunal Superior Eleitoral disponibiliza os dados sobre candidaturas em eleições de três formas:

1. Para consulta pela web, no sistema DivulgaCandContas;
2. Para download, em arquivos CSV, pelo repositório de dados eleitorais;
3. Por uma API do tipo REST.

A API é usada pelo sistema que faz a consulta pela web. Entretanto, ela não está documentada. Tentativas de obter a documentação oficial junto ao TSE não lograram êxito. Por isso, decidimos começar a criar uma documentação não oficial para ajudar a quem mais esteja tentando utilizá-la.

Como usar

Para usar a API, consulte a documentação no formato Open API 2.0. Para mais informações sobre o padrão Open API, consulte o site swagger.io.

A documentação está no arquivo divulgacandcontas-swagger.yaml. Além disso, o arquivo divulgacandcontas.http possui alguns exemplos de consultas prontas para uso.

Mas atenção: antes de usar a API, tome alguns cuidados:

• confira se a sua necessidade de dados pode ser satisfeita pelos downloads de dados disponíveis no repositório de dados eleitorais do TSE. Use a API apenas se os dados não estiverem disponíveis lá (por exemplo, os planos de governo dos candidatos, como nos exemplos) ou você está querendo informações atualizadas apenas por um recorte dos dados (ex.: candidatos de um município específico).
• Se decidir usar a API, coloque um intervalo de tempo entre as consultas, para não sobrecarregar os servidores do TSE. Dessa maneira evitamos que ela seja retirada do ar e reduz o risco do seu IP ser bloqueado na API.

Experimentando com chamadas à API

Para consultar a definição da API acesse o página publicada aqui

Todavia, a API do TSE impedirá as consultas de funcionar pelo navegador, atualmente a API não suporta Cross Origin Resource Sharing (CORS), o que faz com que o navegador bloqueie chamadas à API a partir de outros domíníos.

Uma possível solução, para quem usa Firefox, é instalar a extensão CORS Everywhere e configurar o "activation whitelist" para /^https:\/\/editor.swagger.io/. Ative a extensão na aba do editor de Swagger para que as chamadas à API passem a funcionar no Firefox.

Também é possível utilizar o site Swagger Inspector, no canto superior esquerdo em "Definition" fornecer a URL que aponta para a documentação deste repositorio. Essa URL

Você pode encontrar exemplos de scripts para acessar essa API no diretório examples.

Como contribuir

Essa documentação está em construção e contém apenas uma pequena fração do que está disponível na API. Caso você encontre alguma outra chamada à API que seja útil para você, não hesite em enviar o pull request com a sua complementação.