Docs / Election data
Election data API
Read-only election data: upload progress, polling units, live stream, races, candidates and parties.
These endpoints use the same key as every other call: Authorization: Bearer pij_live_.... They only read. Each key can make 5,000 election requests a day, counted separately from checks, and the count resets at midnight Nigerian time.
What the numbers mean. The data shows how many polling units have had their result sheet uploaded to INEC's results portal. It is upload progress, not results. It can lag INEC by a few minutes. Say so when you publish it.
Endpoints
| Request | Returns |
|---|---|
GET /v1/elections | Every election with expected and uploaded counts, percentage and when it was last checked. |
GET /v1/elections/{ref} | One election by ref: counts by local government and the first 60 polling units still without a sheet. |
GET /v1/states?ref={ref} | Upload counts by state, and how many sheets arrived in the last 15 minutes. Leave out ref for all elections. |
GET /v1/units?q={text}&ref={ref} | Polling units whose name or code matches, with whether the sheet is uploaded. q needs at least 3 letters. |
GET /v1/feed | Recent posts from X and news reports about the elections, with times. |
GET /v1/races | Election cycles (general, off-cycle, by-election, area council) and their races. |
GET /v1/candidates?race_id={id} | Candidates for a race, with party, status and the source we checked. |
GET /v1/parties | Registered parties with their logos. |
Example
curl https://platform.chatniai.com/v1/elections -H "Authorization: Bearer pij_live_YOUR_KEY"
Errors
- 401
invalid_api_key: the key is wrong or revoked. - 429
daily_limit: the key has used its 5,000 requests for today. - 404
not_found: unknown endpoint or election.
Candidates
A candidate appears only with a source link, and with a status: declared aspirant, won party primary, or cleared by INEC. Treat "cleared by INEC" as the only status that means a person is on the ballot.