CivicAPI Documentation

WIP documentation of CivicAPI. CivicAPI, as the name suggests, is an API which provides political data, both for US and international.

Requests are rate-limited to prevent abuse.

upcomingraces

The /api/v1/upcomingraces endpoint will give data for upcoming races data. This data currently goes up until the end of 2025, incrementing each year.

Example URL: https://computernewb.com/civicapi/api/v1/upcomingraces
Example output:

{
  "Austria": [
    {
      "election_name": "Styrian state elections",
      "election_type": "Statewide",
      "date": "2024-11-24T00:00:00",
      "description": "State elections in the Austrian state of Styria will be held on November 24."
    }
  ]
}

Parameters

election_name - Name of the election
election_type - The type of election. Current valid types are: Statewide, Local, General, and Referendum.
date - The date of the election.
description - Contains a small description of the election.

race

The /api/v1/race/{country}/{state}/{type}/{year} endpoint will return election data for a specified election. This is valid for both ongoing and historic elections.

Example URL: https://computernewb.com/civicapi/api/v1/race/us/pa/presidential/1789

Parameters

race_id - The race ID
country - The name of the country the election is taking place in, in ISO 3166 format
state - If applicable, the name of the state the election is taking place in, also in ISO 3166 format.
type - The type of election. Valid election types are: presidential, presidential_round2, governor, house, regent, parliament, senate, referendum, mayor,primary, prime_minister, papal, secretary_of_state, attorney_general, state_house, state_senate, and treasurer.
year - The year of the election.
data
- election_name:
  - en_US - The name of the election (in American English).
- is_snap_election - Specifies if the election is a snap election.
- is_uncontested - If there is only one (or no) candidate in the race, this will be set to true.
- is_delayed - Will be true if the election has been previously delayed.
- has_map - Specifies if the election has a map. If it does, you can generate an image of the map by adding ?generateMapImage to the URL, or download the SVG directly by adding ?getMapSVG.
- polls_open - The time when the polls open.
- polls_close - The time when the polls close.
- term_begins - Specifies when the elected candidate's term should begin.
- term_ends - Specifies when the elected candidate's term should end.
- election_type - Specifies the election type.
- election_scope - Specifies the scope of the election.
- eligible_voters - How many voters were eligible to vote in this election.
- percent_reporting - Estimated percentage reporting.
- turnout - The turnout, calculated by the number of votes + eligible_voters turned out.
- last_updated - Specifies when the data was last updated.
- round - Specifies the round.
- sources - Lists the sources used to gather the data.
- district_details:
  - district_name - The name of the district.
  - district_country - The country of the district.
  - district_map - The map the district will use if ?generateMapImage or ?getMapSVG is specified.
- candidates:
  - name - The name of the candidate
  - party - The candidate's party
  - candidate_id - The candidate's ID in the database
  - incumbent - Specifies if the candidate was an incumbent
  - is_major - Specifies if the candidate is a major candidate. By our definition, any candidate that received 7% or more of the vote is considered a "major" candidate.
  - dropped_out - Specifies if the candidate dropped out of the election.
  - write_in_candidate - Specifies if this is a write-in candidate.
  - winner - Specifies if this candidate won the election.
  - candidate_color - The candidate's color (used for maps).
  - votes - The number of votes the candidate received.
  - percent - The percentage of votes the candidate received.
  - electoral_votes - The electoral votes the candidate received. Only valid for US presidential elections and certain US governor elections.
  - states_carried - The number of states the candidate has carried.
  - seats_won - The number of seats the candidate has won.
  - delegates - The number of delegates the candidate has been awarded.