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