Computernewb Wiki

CivicAPI Documentation

Revision as of 04:47, 24 July 2024 by Dartz (talk | contribs)

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.
  • 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 the 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
    • 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.
    • 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 the 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.
  • polls_close - Specifies the date of the polls for the election closing.
  • term_start - Specifies when the winner's term will begin.
  • term_end - Specifies when the winner's term will end.
  • 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
      • 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.
    • 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)

prediction

The prediction endpoint will give you predictions on the 2024 US presidential race

(not implemented yet; no docs)

amendment

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

(not implemented yet; no docs)

Retrieved from "https://computernewb.com/w/index.php?title=CivicAPI_Documentation&oldid=4190"