< 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.

Parameter name Value  
voter_device_id:
google_civic_election_id:
search_string:
state_code:

(opens in new window)