< back to index

HTTP request

GET https://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'.

Parameter name	Value
electionDay:
searchText:
state:
useWeVoteFormat:	True False

(opens in new window)