CivicAPI Documentation

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

Requests are rate-limited to prevent abuse.

election

The election endpoint will give you access to election information, both historic and current.

/v1/election/{country}/{election}/{year}

This can be used to fetch information about a country-wide election. The year argument can be used to narrow down the results to a specific year. If one isn't specified, it will return all the elections found.

Valid election arguments are presidential, parliament, and governor

Parameters

• election_name - The name of the election
• election_type - The type of election. Currently, valid election types are popular, primary, parliament, and electoral.
• percent_reporting - Specifies the number of precincts reporting.
• votes_needed - Will list the number of votes needed in a parliamentary or electoral vote to win the election. This parameter does not exist if election_type is popular.
• round - Specifies the current round of voting in the election.
• is_snap_election - Specifies if the election is a snap election.
• is_ongoing - Specifies if the election is currently ongoing.
• has_map - Specifies if the election supports a map. A map can be generated with /v1/election/{country}/{election}/{year}/map (more information below)
• map - Specifies the map file to use.
• polls_open - Specifies the date of the polls for the election opening, in Epoch milliseconds.
• polls_close - Specifies the date of the polls for the election closing, in Epoch milliseconds.
• term_start - Specifies when the winner's term will begin, in Epoch milliseconds.
• term_end - Specifies when the winner's term will end, in Epoch milliseconds.
• sources - Lists the sources which were used to gather the data.
• candidates - The list of candidates in the race.
  • name - Candidate's name
  • incumbent - Specifies whether the candidate is an incumbent.
  • write_in - Specifies whether the candidate is a write-in candidate.
  • dropped_out - Specifies whether the candidate has dropped out of the race. Only exists if the election_type is primary.
  • party - Candidate's party
  • votes - The number of votes the candidate received
  • delegates - The number of delegates the candidate received. Normally only exists if the election_type is primary, but some US presidential elections (such as the 1824 election) also used delegates to elect the president.
  • percent - The percentage of votes the candidate received
  • electoral_votes - The number of electoral votes the candidate received. Only exists if the election_type is electoral.
  • seats_won - The number of seats the candidate won. Only exists if the election_type is parliament.
  • states_carried - The number of states the candidate received. Only exists if the election_type is electoral.
  • winner - Specifies if the candidate has been declared the winner.
• region_results - Results of the states/regions/constituencies/counties/oblasts/etc.
  • region - The region
    • candidates - The list of candidates in the region.
      • name - Candidate's name
      • party - Candidate's party
      • votes - The number of votes the candidate received
      • percent - The percentage of votes the candidate received
  • electoral_votes - Specifies the number of electoral votes of the region. Only exists if the election_type is electoral.
  • percent_reporting - Specifies the number of precincts reporting in the region.
  • winner - The winner of the region.
  • fill - The region winner's hex color, for filling maps in with.

Example URL: https://computernewb.com/election/api/v1/election/us/presidential/1789

/v1/election/{country}/{election}/{year}/map

This endpoint can be used to generate a map. It returns a PNG of a filled out map. This endpoint will only work if has_map is true. Otherwise, it will throw a 404 error.

Example URL: https://computernewb.com/election/api/v1/election/us/presidential/1789/map

/v1/election/{country}/{election}/{year}/{region}

This can be used to fetch information about a specific region's election results. The year argument can be used to narrow down the results to a specific year. If one isn't specified, it will return all the elections found.

Valid election arguments are presidential and governor

Parameters

• election_name - The name of the election
• election_type - The type of election. Currently, valid election types are popular, primary, parliament, and electoral.
• votes_needed - Will list the number of votes needed in a parliamentary or electoral vote to win the election. This parameter does not exist if election_type is popular.
• percent_reporting - Returns the number of precincts reporting in the election.
• round - Specifies the current round of voting in the election.
• is_snap_election - Specifies if the election is a snap election.
• is_ongoing - Specifies if the election is currently ongoing.
• has_map - Specifies if the election supports a map. A map can be generated with /v1/election/{country}/{election}/{year}/map (more information below)
• map - Specifies the map file to use.
• polls_open - Specifies the date of the polls for the election opening, in Epoch milliseconds.
• polls_close - Specifies the date of the polls for the election closing, in Epoch milliseconds.
• term_start - Specifies when the winner's term will begin, in Epoch milliseconds.
• term_end - Specifies when the winner's term will end, in Epoch milliseconds.
• sources - Lists the sources which were used to gather the data.
• candidates - The list of candidates in the race.
  • name - Candidate's name
  • incumbent - Specifies whether the candidate is an incumbent.
  • write_in - Specifies whether the candidate is a write-in candidate.
  • dropped_out - Specifies whether the candidate has dropped out of the race. Only exists if the election_type is primary.
  • party - Candidate's party
  • votes - The number of votes the candidate received
  • percent - The percentage of votes the candidate received
  • electoral_votes - The number of electoral votes the candidate received. Only exists if the election_type is electoral.
  • states_carried - The number of states the candidate received. Only exists if the election_type is electoral.
  • seats_won - The number of seats the candidate won. Only exists if the election_type is parliament.
  • winner - Specifies if the candidate has been declared the winner.
• region_results - Results of the counties/districts/parishes/boroughs/etc.
  • region - The region name
    • candidates - The list of candidates in the region.
      • name - Candidate's name
      • party - Candidate's party
      • votes - The number of votes the candidate received
      • percent - The percentage of votes the candidate received
  • electoral_votes - Specifies the number of electoral votes of the region. Only exists if the election_type is electoral.
  • percent_reporting - Specifies the number of precincts in the region reporting.
  • winner - The winner of the region.
  • fill - The region winner's hex color, for filling maps in with.

Example URL: https://computernewb.com/election/api/v1/election/us/governor/2022/mn

/v1/election/{country}/{election}/{year}/{region}/map

This endpoint can be used to generate a map. It returns a PNG of a filled out map. This endpoint will only work if has_map is true. Otherwise, it will throw a 404 error.

Example URL: https://computernewb.com/election/api/v1/election/us/governor/2022/mn/map

/v1/election/{country}/{election}/{year}/{region}/{district}

This endpoint can be used to fetch results for a specific county/region/district/etc. This does not support the map argument yet.

(not implemented yet; no docs)

poll

The poll endpoint will give you the latest polls on various issues such as Trump vs. Harris, Biden approval rating, Harris approval rating, etc.

(not implemented yet; no docs)

predictions

The predictions endpoint returns forecasts on the 2024 US presidential race. Only supports presidential races for now but others may be supported in the future.

/v1/predictions/{type}/{source}

Parameters

• name - Name of the forecast
• url - URL of the forecast
• last_updated - When the forecast was last updated.
• votes_needed - Votes needed to win
• before_biden_dropout - Returns if the forecast was done before Joe Biden dropped out of the race.
• map - Specifies the map to use.
• candidates - The list of candidates in the race.
  • name - Candidate's name
  • incumbent - Specifies whether the candidate is an incumbent.
  • party - Candidate's party
  • electoral_votes - The number of electoral votes the candidate received in the prediction
  • candidate_color - Specifies the candidate's color on the map
  • winner - Specifies if the candidate has been declared the winner.
• region_results - Results of the counties/districts/parishes/boroughs/etc.
  • region - The region name
    • winner - Specifies the name of the candidate who won the region
    • fill Specifies the hex color fill to use on a map

Example URL: http://computernewb.com/election/api/v1/predictions/presidential/polymarket

/v1/predictions/{type}/{source}/map

This endpoint can be used to generate a map. It returns a PNG of a filled out electoral map. Example URL: https://computernewb.com/election/api/v1/predictions/presidential/polymarket/map

amendment

The amendment endpoint will return amendments from the US Constitution (and maybe other countries in the future)

/v1/amendment/{country}/{amendment}

This can be used to fetch an amendment. This endpoint currently only supports the US Constitution's amendments.

• amendment_name - Name of the amendment
• amendment_full_name - Full title of the amendment
• adopted - Date of adoption, in Epoch milliseconds.
• text - The text of the amendment

Example URLs:

• https://computernewb.com/api/v1/amendment/us/1st - Returns the First Amendment
• https://computernewb.com/api/v1/amendment/us/ - Returns all the amendments

upcoming

The upcoming endpoint will return upcoming elections.

(not implemented yet; no docs)