< back to index
HTTP request
GET https://api.wevoteusa.org/apis/v1/positionListForBallotItem (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 |
| kind_of_ballot_item |
string |
The kind of ballot item we want positions for. (kind_of_ballot_item is either "OFFICE", "CANDIDATE", "POLITICIAN" or "MEASURE") |
| ballot_item_id |
integer |
The unique internal identifier of the ballot item we want positions for. (either ballot_item_id OR ballot_item_we_vote_id required -- not both. If it exists, ballot_item_id is used instead of ballot_item_we_vote_id) |
| ballot_item_we_vote_id |
string |
The unique identifier for this ballot_item across all networks (either ballot_item_id OR ballot_item_we_vote_id required -- not both. NOTE: In the future we might support other identifiers used in the industry. |
Optional Parameters
| Parameter name |
Value |
Description |
| stance |
string |
Default is ANY_STANCE. Other options include SUPPORT, STILL_DECIDING, INFO_ONLY, NO_STANCE, OPPOSE, PERCENT_RATING |
| friends_vs_public |
string |
Default is FRIENDS_AND_PUBLIC. Other options include FRIENDS_ONLY, PUBLIC_ONLY, FRIENDS_AND_PUBLIC |
| private_citizens_only |
boolean |
Defaults to False. If False, only retrieve positions from groups and public figures. If True, only return positions from private citizens. |
Response
{
"status": string,
"success": boolean,
"count": integer,
"kind_of_ballot_item": string (CANDIDATE, MEASURE), (One of these: 'CANDIDATE', 'MEASURE', 'OFFICE', 'UNKNOWN',)
"ballot_item_id": integer,
"ballot_item_we_vote_id": string,
"position_list": list
[
"ballot_item_display_name": string (either measure name or candidate name),
"ballot_item_image_url_https_large": string,
"ballot_item_image_url_https_medium": string,
"ballot_item_image_url_https_tiny": string,
"ballot_item_we_vote_id": string,
"is_support": boolean,
"is_positive_rating": boolean,
"is_support_or_positive_rating": boolean,
"is_oppose": boolean,
"is_negative_rating": boolean,
"is_oppose_or_negative_rating": boolean,
"is_information_only": boolean,
"is_public_position": boolean,
"last_updated": string (time in this format %Y-%m-%d %H:%M:%S),
"more_info_url": string,
"position_we_vote_id": string (the position identifier that moves server-to-server),
"position_ultimate_election_date": integer,
"position_year": integer,
"speaker_display_name": string,
"speaker_image_url_https_large": string,
"speaker_image_url_https_medium": string,
"speaker_image_url_https_tiny": string,
"speaker_twitter_handle": string,
"speaker_type": string, (One of these: 'ORGANIZATION', 'VOTER', 'PUBLIC_FIGURE', 'UNKNOWN',)
"speaker_id": integer,
"speaker_we_vote_id": string,
"statement_text": string,
"twitter_followers_count": integer,
],
}
Response Status Codes
| Code |
Description |
| VALID_VOTER_DEVICE_ID_MISSING |
Cannot proceed. A valid voter_device_id parameter was not included. |
| VALID_VOTER_ID_MISSING |
Cannot proceed. A valid voter_id was not found. |
| UNABLE_TO_RETRIEVE-CANDIDATE_ID_AND_MEASURE_ID_MISSING |
Cannot proceed. Neither candidate_id nor measure_id were included. |
| SUCCESSFUL_RETRIEVE_OF_POSITIONS |
The number of opposes for this ballot item was retrieved. |
| SUCCESSFUL_RETRIEVE_OF_POSITIONS_NOT_FOLLOWED |
The number of endorsers that oppose this ballot item that voter is NOT following. |
Try It Now: API Variables
A list of all positions (support/oppose/info) for this Ballot Item (Office, Candidate or Measure) from endorsers, friends, and public figures this voter follows. (Or show the positions the voter is NOT following if show_positions_this_voter_follows is False.)