|
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 <code>election</code> endpoint will give you access to election information, both historic and current.
===/v1/election/{country}/{election}/getyears===
This endpoint can be used to get a list of valid election years.
Example URL: <code>https://computernewb.com/election/api/v1/election/kp/parliament/getyears</code>
===/v1/election/{country}/{election}/{year}===
This can be used to fetch information about a country-wide election. The <code>year</code> 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 <code>election</code> arguments are <code>presidential</code>, <code>parliament</code>, and <code>governor</code>
====Parameters====
*<code>election_name</code> - The name of the election
*<code>election_type</code> - The type of election. Currently, valid election types are <code>popular</code>, <code>primary</code>, <code>parliament</code>, and <code>electoral</code>.
*<code>percent_reporting</code> - Specifies the number of precincts reporting.
*<code>votes_needed</code> - Will list the number of votes needed in a parliamentary or electoral vote to win the election. This parameter does not exist if <code>election_type</code> is <code>popular</code>.
*<code>round</code> - Specifies the current round of voting in the election.
*<code>is_snap_election</code> - Specifies if the election is a snap election.
*<code>is_ongoing</code> - Specifies if the election is currently ongoing.
*<code>has_map</code> - Specifies if the election supports a map. A map can be generated with <code>/v1/election/{country}/{election}/{year}/map</code> (more information below)
*<code>map</code> - Specifies the map file to use.
*<code>polls_open</code> - Specifies the date of the polls for the election opening, in Epoch milliseconds.
*<code>polls_close</code> - Specifies the date of the polls for the election closing, in Epoch milliseconds.
*<code>term_start</code> - Specifies when the winner's term will begin, in Epoch milliseconds.
*<code>term_end</code> - Specifies when the winner's term will end, in Epoch milliseconds.
*<code>sources</code> - Lists the sources which were used to gather the data.
*<code>candidates</code> - The list of candidates in the race.
**<code>name</code> - Candidate's name
**<code>incumbent</code> - Specifies whether the candidate is an incumbent.
**<code>write_in</code> - Specifies whether the candidate is a write-in candidate.
**<code>dropped_out</code> - Specifies whether the candidate has dropped out of the race. Only exists if the <code>election_type</code> is <code>primary</code>.
**<code>party</code> - Candidate's party
**<code>votes</code> - The number of votes the candidate received
**<code>delegates</code> - The number of delegates the candidate received. Normally only exists if the <code>election_type</code> is <code>primary</code>, but one US presidential elections (the 1824 election) also used delegates to elect the president.
**<code>percent</code> - The percentage of votes the candidate received
**<code>electoral_votes</code> - The number of electoral votes the candidate received. Only exists if the <code>election_type</code> is <code>electoral</code>.
**<code>seats_won</code> - The number of seats the candidate won. Only exists if the <code>election_type</code> is <code>parliament</code>.
**<code>states_carried</code> - The number of states the candidate received. Only exists if the <code>election_type</code> is <code>electoral</code>.
**<code>contests_won</code> - The number of contests the candidate won. Only exists if the <code>election_type</code> is <code>primary</code>.
**<code>winner</code> - Specifies if the candidate has been declared the winner.
*<code>region_results</code> - Results of the states/regions/constituencies/counties/oblasts/etc.
**<code>region</code> - The region
***<code>candidates</code> - The list of candidates in the region.
****<code>name</code> - Candidate's name
****<code>party</code> - Candidate's party
****<code>votes</code> - The number of votes the candidate received
****<code>percent</code> - The percentage of votes the candidate received
**<code>electoral_votes</code> - Specifies the number of electoral votes of the region. Only exists if the election_type is <code>electoral</code>.
**<code>percent_reporting</code> - Specifies the number of precincts reporting in the region.
**<code>winner</code> - The winner of the region.
**<code>fill</code> - The region winner's hex color, for filling maps in with.
Example URL: <code>https://computernewb.com/election/api/v1/election/us/presidential/1789</code>
===/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 <code>has_map</code> is <code>true</code>. Otherwise, it will throw a 404 error.
Example URL: <code>https://computernewb.com/election/api/v1/election/us/presidential/1789/map</code>
===/v1/election/{country}/{election}/{year}/{region}===
This can be used to fetch information about a specific region's election results. The <code>year</code> 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 <code>election</code> arguments are <code>presidential</code> and <code>governor</code>
====Parameters====
*<code>election_name</code> - The name of the election
*<code>election_type</code> - The type of election. Currently, valid election types are <code>popular</code>, <code>primary</code>, <code>parliament</code>, and <code>electoral</code>.
*<code>votes_needed</code> - Will list the number of votes needed in a parliamentary or electoral vote to win the election. This parameter does not exist if <code>election_type</code> is <code>popular</code>.
*<code>percent_reporting</code> - Returns the number of precincts reporting in the election.
*<code>round</code> - Specifies the current round of voting in the election.
*<code>is_snap_election</code> - Specifies if the election is a snap election.
*<code>is_ongoing</code> - Specifies if the election is currently ongoing.
*<code>has_map</code> - Specifies if the election supports a map. A map can be generated with <code>/v1/election/{country}/{election}/{year}/map</code> (more information below)
*<code>map</code> - Specifies the map file to use.
*<code>polls_open</code> - Specifies the date of the polls for the election opening, in Epoch milliseconds.
*<code>polls_close</code> - Specifies the date of the polls for the election closing, in Epoch milliseconds.
*<code>term_start</code> - Specifies when the winner's term will begin, in Epoch milliseconds.
*<code>term_end</code> - Specifies when the winner's term will end, in Epoch milliseconds.
*<code>sources</code> - Lists the sources which were used to gather the data.
*<code>candidates</code> - The list of candidates in the race.
**<code>name</code> - Candidate's name
**<code>incumbent</code> - Specifies whether the candidate is an incumbent.
**<code>write_in</code> - Specifies whether the candidate is a write-in candidate.
**<code>dropped_out</code> - Specifies whether the candidate has dropped out of the race. Only exists if the election_type is <code>primary</code>.
**<code>party</code> - Candidate's party
**<code>votes</code> - The number of votes the candidate received
**<code>percent</code> - The percentage of votes the candidate received
**<code>electoral_votes</code> - The number of electoral votes the candidate received. Only exists if the election_type is <code>electoral</code>.
**<code>states_carried</code> - The number of states the candidate received. Only exists if the election_type is <code>electoral</code>.
**<code>seats_won</code> - The number of seats the candidate won. Only exists if the election_type is <code>parliament</code>.
**<code>delegates</code> - The number of delegates the candidate won. Only exists if the election_type is <code>primary</code>.
**<code>winner</code> - Specifies if the candidate has been declared the winner.
*<code>region_results</code> - Results of the counties/districts/parishes/boroughs/etc.
**<code>region</code> - The region name
***<code>candidates</code> - The list of candidates in the region.
****<code>name</code> - Candidate's name
****<code>party</code> - Candidate's party
****<code>votes</code> - The number of votes the candidate received
****<code>percent</code> - The percentage of votes the candidate received
**<code>electoral_votes</code> - Specifies the number of electoral votes of the region. Only exists if the election_type is <code>electoral</code>.
**<code>percent_reporting</code> - Specifies the number of precincts in the region reporting.
**<code>winner</code> - The winner of the region.
**<code>fill</code> - The region winner's hex color, for filling maps in with.
Example URL: <code>https://computernewb.com/election/api/v1/election/us/governor/2022/mn</code>
===/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 <code>has_map</code> is <code>true</code>. Otherwise, it will throw a 404 error.
Example URL: <code>https://computernewb.com/election/api/v1/election/us/governor/2022/mn/map</code>
===/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 <code>map</code> argument yet.
(not implemented yet; no docs)
==poll==
The <code>poll</code> 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 <code>predictions</code> 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====
*<code>name</code> - Name of the forecast
*<code>url</code> - URL of the forecast
*<code>last_updated</code> - When the forecast was last updated.
*<code>votes_needed</code> - Votes needed to win
*<code>before_biden_dropout</code> - Returns if the forecast was done before Joe Biden dropped out of the race.
*<code>map</code> - Specifies the map to use.
*<code>candidates</code> - The list of candidates in the race.
**<code>name</code> - Candidate's name
**<code>incumbent</code> - Specifies whether the candidate is an incumbent.
**<code>party</code> - Candidate's party
**<code>electoral_votes</code> - The number of electoral votes the candidate received in the prediction
**<code>candidate_color</code> - Specifies the candidate's color on the map
**<code>winner</code> - Specifies if the candidate has been declared the winner.
*<code>region_results</code> - Results of the counties/districts/parishes/boroughs/etc.
**<code>region</code> - The region name
***<code>winner</code> - Specifies the name of the candidate who won the region
***<code>fill</code> Specifies the hex color fill to use on a map
Example URL: <code>http://computernewb.com/election/api/v1/predictions/presidential/polymarket</code>
===/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: <code>https://computernewb.com/election/api/v1/predictions/presidential/polymarket/map</code>
==gas==
The <code>gas</code> endpoint returns prices for gas across the US (and maybe other countries in the future).
(not implemented yet; no docs)
==amendment==
The <code>amendment</code> 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.
*<code>amendment_name</code> - Name of the amendment
*<code>amendment_full_name</code> - Full title of the amendment
*<code>adopted</code> - Date of adoption, in Epoch milliseconds.
*<code>text</code> - The text of the amendment
Example URLs:
*<code>https://computernewb.com/api/v1/amendment/us/1st</code> - Returns the First Amendment
*<code>https://computernewb.com/api/v1/amendment/us/</code> - Returns all the amendments
|