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 either link to civicapi.org or list our name somewhere. Thank you!
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. |
| 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/bond measures, etc |
| Papal | Used only in Vatican City |
| Railroad Commissioner | |
| County Court Judge | |
| Supervisor of Elections | |
| City Council | |
| 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 January 4, 2025. However, we are working 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]&country=[string]&province=[string]&district=[string]&election_type=[string]&limit=[integer]
This endpoint allows you to search for races by name. You can filter by country, province (also known as states, regions, etc), districts (also known as counties, cantons, etc), election type, 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.
country string Filter results to a specific country with this param. Countries use ISO 3166-1 alpha-2 codes, i.e. US (for countries that are unrecognized by or were abolished prior to the founding of the United Nations, ISO-3166 alpha-3, i.e. USA, is used instead.)
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 10000.
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.
Get Race History
GET https://civicapi.org/api/v2/race/{raceid}/history/[timestamp]
This endpoint retrieves historical snapshots of a race. This endpoint can be used to build election timelines or visualize result progression.
NOTE: Historical data is available only for races tracked after October 9, 2025.
raceid string required The Race ID to view.
history paramReturns a list of available history timestamps for the specified race, if no date is specified.
Each timestamp is formatted as YYYY-MM-DDTHH:MM:SS.sssZ.
timestamp param | optional If a valid timestamp is provided, returns the full JSON snapshot of that race at the specified time. The JSON is the exact same as in fetching a race.
Response Body
id integer required ID of the election.
count integer required The number of snapshots.
timestamps object required Object containing valid timestamps, which is used to fetch the historical data. For example, https://civicapi.org/api/v2/race/6555/history/2025-10-10T18:47:13.546Z.
timestamp string required The timestamp, formatted as YYYY-MM-DDTHH:MM:SS.sssZ.
Get Election Dates
GET https://civicapi.org/api/v2/getElectionDates?country=[country]&province=[province]&year=[year]
This endpoint returns a list of past and current election dates for a given year. The results can be filtered by country or province.
year string | optionalFormat: YYYY. This param allows you to filter by year, i.e. 2025, 2024. Defaults to 2025 if no year is specified.
country string | optionalFilters election dates to a specific country. Takes ISO 3166-1 alpha-2 codes, i.e. US (for countries that are unrecognized or were abolished prior to the founding of the United Nations, ISO-3166 alpha-3 codes, i.e. USA, are used instead.) Leave blank to show all election dates.
province string | optionalFilters election dates to a specific province (also known as states, regions, etc). Takes ISO 3166-1 alpha-2 codes, i.e. AL
Response Body
year integer required Returns the year of the election dates.
total_unique_dates integer required Returns the number of valid election dates.
months object required Months returned. Will be empty if no months were found.
month string required The name of the month.
month_num integer required The number of the month (i.e. 8 for August).
dates object required The election dates for the month.
day integer required The day of the election(s).
date date required The date, returned in YYYY-MM-DDDD format. Can be used for i.e. searching in /api/v2/race/search using the startDate param.
slug string required The slug, formatted like month-day, i.e. august-12.
count integer required The number of races for the day.