CivicAPI Documentation: Difference between revisions
Jump to navigation
Jump to search
No edit summary |
(Blanked the page) Tag: Blanking |
||
| Line 1: | Line 1: | ||
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 |
|||