< back to index

HTTP request

GET https://api.wevoteusa.org/apis/v1/voterGuidesToFollowRetrieve (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
kind_of_ballot_item string What is the type of ballot item that we are retrieving? (kind_of_ballot_item is either "OFFICE", "CANDIDATE", "POLITICIAN" or "MEASURE")
ballot_item_we_vote_id string The unique identifier for a particular ballot item. If this variable is provided, we want to retrieve all of the voter guides that have something to say about this particular ballot item.
google_civic_election_id integer The unique identifier for a particular election. If not provided, use the most recent ballot for the voter's address.
search_string string A string of keyword(s) to search for (to find twitter handle or org name).
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.
start_retrieve_at_this_number integer In most elections we have well over the maximum_number_to_retrieve voter guides that we want to retrieve with each call. Setting this number lets us retrieve voter guides in "pages".
maximum_number_to_retrieve integer Defaults to 75 voter guides. Enter a value to set your own limit.
filter_voter_guides_by_issue boolean Filter the voter guides to contain organizations following the same issues as voter
add_voter_guides_not_from_election boolean When requesting election-related voter guides, if this is true, add to the end of the list additional voter guides not related to the election.

Response

{
  "status": string,
  "success": boolean,
  "voter_device_id": string (88 characters long),
  "google_civic_election_id": integer,
  "search_string": string,
  "start_retrieve_at_this_number": integer
  "number_retrieved": integer
  "maximum_number_to_retrieve": integer,
  "voter_guides": list
   [{
     "voter_guide_display_name": string (Name of this org or person),
     "voter_guide_owner_type": ORGANIZATION, PUBLIC_FIGURE, VOTER),
     "we_vote_id": string (We Vote ID of the voter guide),
     "organization_we_vote_id": string (We Vote ID for the org that owns the voter guide),
     "public_figure_we_vote_id": string (We Vote ID for the person that owns the voter guide),
     "voter_guide_image_url_large": string (We Vote ID for the person that owns the voter guide),
     "voter_guide_image_url_medium": string (We Vote ID for the person that owns the voter guide),
     "voter_guide_image_url_tiny": string (We Vote ID for the person that owns the voter guide),
     "last_updated": string (time in this format %Y-%m-%d %H:%M),
     "google_civic_election_id": integer,
     "twitter_description": string,
     "twitter_followers_count": integer,
     "twitter_handle": integer,
     "owner_voter_id": integer TO BE DEPRECATED,
     "ballot_item_we_vote_ids_this_org_supports": The list of ballot_item_we_vote_ids supported by this organization,
     "ballot_item_we_vote_ids_this_org_info_only": The list of ballot_item_we_vote_ids this organization has information about,
     "ballot_item_we_vote_ids_this_org_opposes": The list of ballot_item_we_vote_ids opposed by this organization,
     "issue_we_vote_ids_linked": The list of issue_we_vote_ids linked to this organization,
     "is_support": boolean (Exists if looking at voter guides for one ballot_item),
     "is_positive_rating": boolean (Exists if looking at voter guides for one ballot_item),
     "is_support_or_positive_rating": boolean (Exists if looking at one ballot_item),
     "is_oppose": boolean (Exists if looking at voter guides for one ballot_item),
     "is_negative_rating": boolean (Exists if looking at voter guides for one ballot_item),
     "is_oppose_or_negative_rating": boolean (Exists if looking at one ballot_item),
     "is_information_only": boolean (Exists if looking at voter guides for one ballot_item),
     "vote_smart_rating": integer (Exists if looking at voter guides for one ballot_item),
     "vote_smart_time_span": string (Exists if looking at voter guides for one ballot_item),
     "candidate_name": string (Exists if looking at voter guides for one ballot_item),
     "speaker_display_name": string (Exists if looking at voter guides for one ballot_item),
     "statement_text": string (Exists if looking at voter guides for one ballot_item),
     "more_info_url": string (Exists if looking at voter guides for one ballot_item),
   },],
}

Response Status Codes

Code Description
VOTER_GUIDES_TO_FOLLOW_RETRIEVED At least one voter guide was returned.
ERROR_GUIDES_TO_FOLLOW_NO_VOTER_DEVICE_ID A valid voter_device_id parameter was not included. Cannot proceed.
NO_VOTER_GUIDES_FOUND No voter guides exist in the database matching the search terms.

Try It Now: API Variables

Look up the election and ballot items that this person is focused on. Return the organizations, public figures, and voters that have shared voter guides available to follow. Take into consideration which voter guides the voter has previously ignored. Do not show voter guides the voter is already following.If neither ballot_item_we_vote_id (paired with kind_of_ballot_item) nor google_civic_election_id arepassed in, and google_civic_election_id is set to '0', then simply return a list of voter guides that haven't been followed yet. If google_civic_election_id is NOT set to 0, the routine tries tofigure out which election is being looked at in the voter_device_link or the voter_address.

Parameter name Value  
voter_device_id:
kind_of_ballot_item:
ballot_item_we_vote_id:
google_civic_election_id:
search_string:
use_test_election: True
False
start_retrieve_at_this_number:
maximum_number_to_retrieve:
filter_voter_guides_by_issue: True
False
add_voter_guides_not_from_election: True
False

(opens in new window)