796
edits
CivicAPI Documentation: Difference between revisions
Jump to navigation
Jump to search
no edit summary
m (Dartz moved page ElectionsAPI Documentation to CivicAPI Documentation: new name) |
No edit summary |
||
|
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 <code>/api/v1/upcomingraces</code> endpoint will give data for upcoming races data. This data currently goes up until the end of 2025, incrementing each year.
*Example URL: <code>https://computernewb.com/civicapi/api/v1/upcomingraces</code>
*Example output:
<pre>
{
"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."
}
]
}
</pre>
===Parameters===
*<code>election_name</code> - Name of the election
*<code>election_type</code> - The type of election. Current valid types are: <code>Statewide</code>, <code>Local</code>, <code>General</code>, and <code>Referendum</code>.
*<code>date</code> - The date of the election.
*<code>description</code> - Contains a small description of the election.
==race==
The <code>/api/v1/race/{country}/{state}/{type}/{year}</code> endpoint will return election data for a specified election. This is valid for both ongoing and historic elections.
* Example URL: <code>https://computernewb.com/civicapi/api/v1/race/us/pa/presidential/1789</code>
===Parameters===
*<code>race_id</code> - The race ID
*<code>country</code> - The name of the country the election is taking place in, in ISO 3166 format
*<code>state</code> - If applicable, the name of the state the election is taking place in, also in ISO 3166 format.
*<code>type</code> - The type of election. Valid election types are: <code>presidential</code>, <code>presidential_round2</code>, <code>governor</code>, <code>house</code>, <code>regent</code>, <code>parliament</code>, <code>senate</code>, <code>referendum</code>, <code>mayor</code>,<code>primary</code>, <code>prime_minister</code>, <code>papal</code>, <code>secretary_of_state</code>, <code>attorney_general</code>, <code>state_house</code>, <code>state_senate</code>, and <code>treasurer</code>.
*<code>year</code> - The year of the election.
*<code>data</code>
**<code>election_name</code>:
***<code>en_US</code> - The name of the election (in American English).
**<code>is_snap_election</code> - Specifies if the election is a snap election.
**<code>is_uncontested</code> - If there is only one (or no) candidate in the race, this will be set to <code>true</code>.
**<code>is_delayed</code> - Will be <code>true</code> if the election has been previously delayed.
**<code>has_map</code> - Specifies if the election has a map. If it does, you can generate an image of the map by adding <code>?generateMapImage</code> to the URL, or download the SVG directly by adding <code>?getMapSVG</code>.
**<code>polls_open</code> - The time when the polls open.
**<code>polls_close</code> - The time when the polls close.
**<code>term_begins</code> - Specifies when the elected candidate's term should begin.
**<code>term_ends</code> - Specifies when the elected candidate's term should end.
**<code>election_type</code> - Specifies the election type.
**<code>election_scope</code> - Specifies the scope of the election.
**<code>eligible_voters</code> - How many voters were eligible to vote in this election.
**<code>percent_reporting</code> - Estimated percentage reporting.
**<code>turnout</code> - The turnout, calculated by the number of votes + <code>eligible_voters</code> turned out.
**<code>last_updated</code> - Specifies when the data was last updated.
**<code>round</code> - Specifies the round.
**<code>sources</code> - Lists the sources used to gather the data.
**<code>district_details</code>:
***<code>district_name</code> - The name of the district.
***<code>district_country</code> - The country of the district.
***<code>district_map</code> - The map the district will use if <code>?generateMapImage</code> or <code>?getMapSVG</code> is specified.
**<code>candidates</code>:
***<code>name</code> - The name of the candidate
***<code>party</code> - The candidate's party
***<code>candidate_id</code> - The candidate's ID in the database
***<code>incumbent</code> - Specifies if the candidate was an incumbent
***<code>is_major</code> - Specifies if the candidate is a major candidate. By our definition, any candidate that received more than 7% of the vote is considered a "major" candidate.
***<code>write_in_candidate</code> - Specifies if this is a write-in candidate.
***<code>winner</code> - Specifies if this candidate won the election.
***<code>candidate_color</code> - The candidate's color (used for maps).
***<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 electoral votes the candidate received. Only valid for US presidential elections and certain US governor elections.
| |||