< back to index
HTTP request
GET https://api.wevoteusa.org/apis/v1/ballotItemOptionsRetrieve (Jump to "Try It Now")
Required Parameters
| Parameter name |
Value |
Description |
| voter_device_id |
string |
An 88 character unique identifier linked to a voter record on the server |
| api_key |
string (from post, cookie, or get (in that order)) |
The unique key provided to any organization using the WeVoteServer APIs |
| google_civic_election_id |
integer |
The unique identifier for a particular election. If NOT provided, we instead use the google_civic_election_id for the person who is signed in. |
Optional Parameters
| Parameter name |
Value |
Description |
| search_string |
string |
Search words to use to find the candidate or measure for voter guide. |
| state_code |
string |
The us state we want ballot item options for. |
Response
{
"status": string,
"success": boolean,
"search_string": string,
"ballot_item_list": candidate dict
[
"ballot_item_display_name": string,
"ballotpedia_candidate_id": integer,
"ballotpedia_candidate_url": string,
"ballotpedia_person_id": integer,
"candidate_contact_form_url": string,
"candidate_email": string,
"candidate_name": string,
"candidate_phone": string,
"candidate_photo_url_large": string,
"candidate_photo_url_medium": string,
"candidate_photo_url_tiny": string,
"candidate_url": string,
"candidate_we_vote_id": string,
"candidate_website": string,
"contest_office_id": integer,
"contest_office_we_vote_id": string,
"contest_office_name": string,
"google_civic_election_id": integer,
"id": integer,
"kind_of_ballot_item": string (CANDIDATE),
"maplight_id": integer,
"ocd_division_id": string,
"order_on_ballot": integer,
"party": string,
"politician_id": integer,
"politician_we_vote_id": string,
"state_code": string,
"facebook_url": string,
"twitter_url": string,
"twitter_handle": string,
"google_plus_url": string,
"youtube_url": string,
"we_vote_id": string,
"wikipedia_url": string,
],
"ballot_item_list": measure dict
[
"ballot_item_display_name": string,
"google_civic_election_id": integer,
"id": integer,
"kind_of_ballot_item": string (MEASURE),
"measure_subtitle": string,
"measure_text": string,
"measure_url": string,
"measure_we_vote_id": string,
"no_vote_description": string,
"state_code": string,
"yes_vote_description": string,
],
}
Response Status Codes
| Code |
Description |
| CANDIDATES_RETRIEVED OFFICES_RETRIEVED MEASURES_RETRIEVED |
Ballot items were found. |
| NO_CANDIDATES_RETRIEVED NO_OFFICES_RETRIEVED NO_MEASURES_RETRIEVED |
Candidates, offices or measures were not able to be retrieved. |
Try It Now: API Variables
Returns measures and candidates based on search terms, so we can help volunteers or staff find offices, candidates or measures when they are building out organizational voter guides. This information is not organized in a hierarchy, but is instead provided in a simple list for browser-side quick search features.