< 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
show_positions_this_voter_follows boolean True default shows the positions of organizations, public figures and friends this voter is following. If False, show positions that the voter is NOT following.

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
   [
     "position_we_vote_id": string,
     "ballot_item_display_name": string (either measure name or candidate name),
     "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,
     "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,
     "more_info_url": string,
     "statement_text": string,
     "last_updated": string,
   ],
}

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 organizations 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 organizations, friends, and public figures this voter follows. (Or show the positions the voter is NOT following if show_positions_this_voter_follows is False.)

Parameter name Value  
voter_device_id:
kind_of_ballot_item:
ballot_item_id:
ballot_item_we_vote_id:
stance:
friends_vs_public:
show_positions_this_voter_follows: True
False

(opens in new window)