< back to index

HTTP request

GET https://api.wevoteusa.org/apis/v1/voterGuidesUpcomingRetrieve (Jump to "Try It Now")

Required Parameters

Parameter name Value Description
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
google_civic_election_id_list[] integerlist The unique identifier for one or more elections. If not provided, use all the upcoming elections.
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.

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:%S),
     "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

Retrieve all voter guides for all upcoming elections.

Parameter name Value  
google_civic_election_id_list[]:
start_retrieve_at_this_number:
maximum_number_to_retrieve:

(opens in new window)