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.

You can also fetch elections via ID - i.e. /api/v1/race/{id}

• Example URLs: https://computernewb.com/civicapi/api/v1/race/us/pa/presidential/1789
• https://computernewb.com/civicapi/api/v1/race/19

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 a map is available, you can add ?generateMap to the end of the URL to download an SVG map, or generate a PNG with ?generateMapPNG.
  • 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.

search

The /api/v1/search endpoint allows you to search for elections.