< back to index

HTTP request

GET or POST https://api.wevoteusa.org/apis/v1/voterGuidePossibilityHighlightsRetrieve (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
url_to_scan string The url of the list of endorsements that the voter is viewing.

Optional Parameters

Parameter name Value Description
google_civic_election_id integer The Google civic election ID. Provide a value, only if you want data for a prior election.
pdf_url string The url of the list of endorsements, if the endorsement was originally on a pdf.
visible_text_to_scan text Visible text from the page we are scanning. Only accepted in POST.
use_vertex_to_scan_url_if_no_visible_text_provided boolean IF visible_text_to_scan is provided using POST, we always use Vertex AI to identify the likely human names within the text provided. If this variable is set to True (which is the default), use Vertex to scan the url_to_scan (i.e., webpage) IFF a value is NOT provided in visible_text_to_scan. Note that if visible_text_to_scan has a value, we do NOT use Vertex AI to scan the url_to_scan. In all cases, Vertex AI adds about 2-3 seconds to the response time.

Response

{
  "status": string,
  "success": boolean,
  "url_to_scan": string,
  "pdf_url": string,
  "highlight_list": list [
    {
      "name": string,
      "we_vote_id": string,
      "display": string, ('STORED', 'DELETED', 'POSSIBILITY', or 'DEFAULT')
      "stance": string, ('SUPPORT', 'OPPOSED', or 'INFO_ONLY')
      "prior": integer, ('1' if from a prior election)
    }
  ],
  "never_highlight_on": list [
     "*.wevote.us",
     "api.wevoteusa.org",
     "localhost"
  ]
}

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.
VOTER_GUIDE_POSSIBILITY_NOT_FOUND A voter guide possibility was not found at that URL.
VOTER_GUIDE_POSSIBILITY_FOUND_WITH_URL A voter guide possibility entry was found.

Try It Now: API Variables

WeVote's Political Data team reviews endorsement websites. We scan an organization's webpage that contains political endorsements. (Ex/ The National Bird Conservatory endorses Donald Duck for County Tax Collector) WeVote finds the owner of the web page, then finds all of the candidates listed on the page. We store in temporary tables, the SUPPORT and OPPOSE endorsements found on this page, and let a Political Data Manager review these endorsements as they are captured. Once the Political Data Manager has reviewed these endorsements, they can be saved to our publicly available list of endorsements. This tool helps our team provide quality assurance as we collect the data. This voterGuidePossibilityHighlightsRetrieve API connects WeVote's Chrome Extension to the 'Endorsement Websites' admin tools on WeVoteServer, and returns what candidates have been identified, and whether the endorsing organization SUPPORTs, OPPOSEs, or shares INFO_ONLY about the candidate. This API also returns names found on the page who might be politicians, so the Political Data Manager can more easily capture endorsements.
GET: Switch from GET to POST

Parameter name Value  
voter_device_id:
url_to_scan:
google_civic_election_id:
pdf_url:
visible_text_to_scan:
use_vertex_to_scan_url_if_no_visible_text_provided: True
False

(opens in new window)