< back to index

HTTP request

GET https://api.wevoteusa.org/apis/v1/voterBallotItemsRetrieveFromGoogleCivic (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

Optional Parameters

Parameter name Value Description
text_for_map_search string The voter's address we want to look up in the Google Civic API. If blank, we look this value up from the database.
use_test_election boolean If you need to request a test election, pass this with the value 'True'. Note that text_for_map_search (either passed into this API endpoint as a value, or previously saved with voterAddressSave) is required with every election, including the test election.


If the google_civic_election_id is 2000 then we are looking at test election data.

  "status": string,
  "success": boolean,
  "voter_device_id": string (88 characters long),
  "google_civic_election_id": integer,
  "state_code": string,
  "election_day_text": string,
  "election_description_text": string,
  "election_data_retrieved": boolean,
  "text_for_map_search": string,
  "polling_location_retrieved": boolean,
  "contests_retrieved": boolean,
  "ballot_location_display_name": string,
  "ballot_location_shortcut": string,
  "ballot_returned_we_vote_id": string,

Response Status Codes

Code Description
VALID_VOTER_DEVICE_ID_MISSING A valid voter_device_id parameter was not included. Cannot proceed.
VALID_VOTER_ID_MISSING A valid voter_id was not found from voter_device_id. Cannot proceed.
MISSING_ADDRESS_TEXT_FOR_BALLOT_SEARCH A voter address was not passed in.
GOOGLE_CIVIC_API_ERROR: Election unknown There is no upcoming election for this address. Or, the election has passed and the election data is no longer available.
GOOGLE_CIVIC_API_ERROR: Election is over The ballot data for this election is not being hosted by Google Civic any more.

Try It Now: API Variables

Tell the We Vote server to reach out to the Google Civic API and retrieve a list of ballot items for the current voter (based on the address saved with voterAddressSave), and store them in the We Vote database so we can display them with voterBallotItemsRetrieve, and other API calls.

Parameter name Value  
use_test_election: True

(opens in new window)