Introduction
civicAPI is a free API which provides realtime election results and calls, as well as polling data and other information. The rate limit is 40 queries per minute, although this can be increased if necessary. Please contact us for more information.
The API is open to the public and does not require authentication. The API is free for all personal, non-commercial, or commercial purposes. Attribution is required for non-personal projects - please link to civicapi.org.
Race Types
A list of race types that'll be returned by the API.
| Type | Notes |
|---|---|
| President | |
| Senate | |
| House of Representatives | Used only in U.S. elections (even in countries that have a "House of Representatives") |
| State House | |
| State Senate | |
| State Supreme Court | |
| Governor | |
| Lieutenant Governor | |
| Primary | |
| Early Vote | |
| Parliament | |
| Mayor | |
| Attorney General | |
| Auditor | |
| State Treasurer | |
| Local | Used for small, local offices |
| Supreme Court | |
| Referendum | Used for any kind of referendum - including state amendments, ballot measure etc |
| Papal | Used only in Vatican City |
| Railroad Commissioner | |
| County Court Judge | |
| Supervisor of Elections | |
| City Sheriff | |
| Director of the Poor | Only used in old (pre-1825) U.S. elections |
| Comptroller | |
| Agriculture Commissioner | |
| Superintendent of Public Instruction | |
| Land Commissioner |
Race Scopes
A list of race scopes that'll be returned by the API.
| Scope | Notes | Priority |
|---|---|---|
| General | Used for country-wide elections | 8 |
| Referendum | 5 | |
| Runoff | Used for all runoff elections, regardless if they are local, statewide, or general primaries. | 6 |
| Primary | Used for all non-jungle primaries, regardless if they are local, statewide or general primaries. | 4 |
| Jungle Primary | 3 | |
| Statewide | Used for province-wide votes, i.e. a governor election | 7 |
| Local | Used for local elections, i.e. a mayor election, township, etc | 1 |
| Ranked Choice Voting | 2 |
Supported Years
Our API currently goes back to March 25, 2025. However, we are workng on adding historic elections.
API v2 Overview
URL Structure: https://civicapi.org/api/v2/(endpoint)
Verify API Status
GET https://civicapi.org/api/v2/status
This endpoint verifies the API status.
Response Body
status string required This will always return "ok".
Search Race
GET https://civicapi.org/api/v2/race/search?startDate=[date]&endDate=[date]&query=[string]&province=[string]&district=[string]&limit=[integer]
This endpoint allows you to search for races by name. You can filter by province (also known as states, regions, etc), districts (also known as counties, cantons, etc), and beginning/ending date.
startDate date Format: YYYY-MM-DD. Filters races to ones that occur on or after this date.
endDate date Format: YYYY-MM-DD. Filters races to ones that occur before this date.
query string Race to search for. This param is optional if you specify a province, district, or date, otherwise it is required.
province string | optional Filter results to a specific province with this param. Provinces use ISO 3166-1 alpha-2 codes.
district string | optional Filter results to a specific district with this param. Districts in our API use full English names. Can be combined with province or used on its own. You can specify null to filter for elections without a district.
limit integer | optional Number of races to return. Default is 20, maximum is 1000.
Response Body
count integer required Number of races found/returned.
races object required Races returned by the query. This will be empty if no races were found.
id integer required The ID of the race.
type string required The race type.
country string required The country of the race, in ISO 3166-1 alpha-2 format.
province string | null required The province of the race, in ISO 3166-1 alpha-2 format.
district string | null required The district (parish, borough, county, canton, etc) of the race. Full English name is used.
election_name string required The name of the election.
election_type string required The type of election.
election_date string required The date of the election, in ISO 8601 format. The time is always set to UTC, regardless of the election country's timezone.
candidates object required An object containing candidate information for the race.
name string required The name of the candidate.
party string required The party of the candidate.
votes integer required The votes the candidate received.
percent integer required The percentage of the vote the candidate received.
Get Race by ID
GET https://civicapi.org/api/v2/race/{raceid}?[generateMap|generateMapPNG]&data=[csv|json]&[embed]&[precinct]
This endpoint allows you to get information about a race.
raceid string required The Race ID to view.
?generateMap param | optional If specified, the API will return an SVG map render of the results. Only works if has_map is true. You will receive an error otherwise.
?generateMapPNG param | optional If specified, the API will return a PNG map render of the results. Only works if has_map is true. You will receive an error otherwise.
?data=[csv|json] param | optional Specifies the format the data is returned in. Default is json. If csv is given, an OpenElections-compatible CSV file of the results will be returned.
?embed param | optional Returns a JSON object containing the election name, ID, and an iframe for embedding the results on a website.
iframe string required HTML code of an iframe for embedding the results onto a website, blog, etc.
race_id integer required ID of the race
election_name string required Name of the election.
?precinct param By default, precinct data is omitted (unless its the only data available) due to its large size. This param will include precinct data in the region_results object if it exists.
Response Body
election_name string required Name of the election, in English.
election_type string required The type of election.
election_scope string required The scope of the election.
election_date string required The date of the election, in ISO 8601 format. The timezone is always set to UTC, regardless of the region's time zone.
country string required The country of the election, in either ISO 3166 alpha-2 format. For unrecognized territories and countries that ceased to exist before the founding of the United Nations, ISO 3166-1 alpha-3 is used instead.
province string | null required The province (state, canton, federal district, etc) of the election. If none exists, this will be null.
district string | null required The district (county, division, kreise, etc) of the election. If none exists, this will be null.
municipality string | null required The municipality (town, city, etc) of the election. If none exists, this will be null.
polls_open timedate required Polls open date, in ISO 8601 format. The timezone is always set to UTC, regardless of the region's time zone
polls_closed timedate required Polls closed date, in ISO 8601 format. The timezone is always set to UTC, regardless of the region's time zone
is_disputed boolean required Specifies if the election has been disputed by a major government body or organization.
has_map boolean required Specifies if the election has a map.
registered_voters integer | null required The number of registered voters.
percent_reporting integer required The percentage of vote reporting.
last_updated timedate required Polls open date, in ISO 8601 format. The timezone is always set to UTC, regardless of the region's time zone
round integer required The round of the election.
candidates object required Object containing candidates.
name string required Name of the candidate, in English.
party string required Party of the candidate.
incumbent boolean required Specifies if the candidate is an incumbent.
major_candidate boolean required Specifies if the candidate is a major candidate. Per our definition, a major candidate is someone who receives >7% of the vote. (During live elections, this is always false.)
winner boolean required Specifies if the candidate won election.
color string required Hex color of the candidate.
votes integer required Number of votes the candidate received.
percent integer required Percentage of votes candidate received.
electoral_votes integer Number of electoral votes the candidate received.
seats integer Number of seats the candidate won. Usually used as a party total.
delegates integer Number of delegates the candidate received.
legislative_votes integer Number of legislative votes the candidate received.
fusion_votes object Number of fusion votes the candidate received.
(party_name) integer required The party name is used as the key name. Contains the number of votes.
region_results object Object containing the region results.
region object Region object.
name string required The name of the region.
type string required The type of region.
fill string required The fill of the region.
candidates object required Candidates object.
name string required The name of the candidate.
party string required The party of the candidate.
incumbent boolean required Specifies if the candidate is an incumbent.
major_candidate boolean required Specifies if the candidate is a major candidate. Per our definition, a major candidate is someone who receives >7% of the vote.
winner boolean required Specifies if the candidate is a winner.
color string required Candidate color, in hex.
votes integer required Number of votes candidate received.
percent integer required Percentage of votes candidate received.