< back to index
HTTP request
GET http://api.wevoteusa.org/apis/v1/candidatesQuery (Jump to "Try It Now")
Required Parameters
| Parameter name |
Value |
Description |
| electionDay |
string |
Date of the election in this format: YYYY-MM-DD
For all elections in a year, pass in: YYYY
For all elections in a month, pass in: YYYY-MM |
Optional Parameters
| Parameter name |
Value |
Description |
| raceOfficeLevelList |
list of strings |
Limit the candidates returned to: Federal, State, Local |
| searchText |
string |
The word or words we want to search for in all candidates. |
| state |
string |
Limit the candidates returned to this state. |
| useWeVoteFormat |
boolean |
Return the candidate variables in snake case variable name format to match other We Vote APIs. |
Response
{
"status": string,
"success": boolean,
"candidatesIndexStart": integer,
"candidatesReturnedCount": integer,
"candidatesTotalCount": integer,
"electionDay": string,
"kind": string,
"state": string,
"candidates": list
[
"id": integer,
"status": string,
"success": boolean,
"ballot_item_display_name": string,
"ballotpedia_candidate_id": integer,
"ballotpedia_candidate_summary": string,
"ballotpedia_candidate_url": string,
"candidate_photo_url_large": string,
"candidate_photo_url_medium": string,
"candidate_photo_url_tiny": string,
"kind_of_ballot_item": string,
"last_updated": string (time in this format %Y-%m-%d %H:%M:%S),
"order_on_ballot": integer,
"party": string,
"we_vote_id": string,
],
"election": {
"electionDay": string,
"id": integer,
"name": string,
"ballotpediaId": string,
"googleCivicId": string,
"voteUSAId": string,
"weVoteId": string,
},
"elections": list
[
"electionDay": string,
"id": integer,
"name": string,
"ballotpediaId": string,
"googleCivicId": string,
"voteUSAId": string,
"weVoteId": string,
],
}
Response Status Codes
| Code |
Description |
| CANDIDATES_RETRIEVED |
Candidates were returned. |
| NO_CANDIDATES_RETRIEVED |
There are no candidates stored for this Office. |
Try It Now: API Variables
Retrieve all the candidates in a particular election or state. This API maintains compatibility with the Vote-USA API of the same name. For We Vote usage, we offer an option to return variables with 'snake case' formatting as opposed to 'camel case'.