< back to index

HTTP request

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

Required Parameters

Parameter name Value Description
year string Year in this format: YYYY

Optional Parameters

Parameter name Value Description
race_office_level list of strings Limit the representatives returned to: Federal, State, Local
search_text string The word or words we want to search for in all representatives.
state string Limit the representatives returned to this state.

Response

{
  "status": string,
  "success": boolean,
  "index_start": integer,
  "kind": string,
  "office_held_list": {
     "district_id": string,
     "district_name": string,
     "name": string,
     "ocd_division_id": string,
     "office_held_description": string,
     "office_held_facebook_url": string,
     "office_held_id": integer,
     "office_held_name": string,
     "office_held_twitter_handle": string,
     "office_held_url": string,
     "office_held_we_vote_id": string,
     "state_code": string,
     "vote_usa_office_id": string,
   },
  "representatives": list
   [
     {
       "id": integer,
       "we_vote_id": string,
       "ballot_item_display_name": string,
       "facebook_url": string,
       "instagram_followers_count": integer,
       "instagram_handle": string,
       "is_battleground_race_2019": boolean,
       "is_battleground_race_2020": boolean,
       "is_battleground_race_2021": boolean,
       "is_battleground_race_2022": boolean,
       "is_battleground_race_2023": boolean,
       "is_battleground_race_2024": boolean,
       "is_battleground_race_2025": boolean,
       "is_battleground_race_2026": boolean,
       "is_battleground_race_2027": boolean,
       "is_battleground_race_2028": boolean,
       "is_battleground_race_2029": boolean,
       "is_battleground_race_2030": boolean,
       "is_claimed_profile": boolean,
       "last_updated": string (time in this format %Y-%m-%d %H:%M:%S),
       "linked_campaignx_we_vote_id": string,
       "linkedin_url": string,
       "ocd_division_id": string,
       "office_held_id": string,
       "office_held_district_name": string,
       "office_held_name": string,
       "office_held_we_vote_id": string,
       "political_party": string,
       "politician_id": integer,
       "politician_we_vote_id": string,
       "profile_image_background_color": string,
       "representative_contact_form_url": string,
       "representative_email": string,
       "representative_email2": string,
       "representative_email3": string,
       "representative_name": string,
       "representative_phone": string,
       "representative_phone2": string,
       "representative_phone3": string,
       "representative_photo_url_large": string,
       "representative_photo_url_medium": string,
       "representative_photo_url_tiny": string,
       "representative_url": string,
       "seo_friendly_path": string,
       "state_code": string,
       "supporters_count": integer,
       "twitter_url": string,
       "twitter_handle": string,
       "twitter_description": string,
       "twitter_followers_count": integer,
       "wikipedia_url": string,
       "year_in_office_2023": boolean,
       "year_in_office_2024": boolean,
       "year_in_office_2025": boolean,
       "year_in_office_2026": boolean,
       "year_in_office_2027": boolean,
       "year_in_office_2028": boolean,
       "year_in_office_2029": boolean,
       "year_in_office_2030": boolean,
       "youtube_url": string,
     },
   ],
  "returned_count": integer,
  "total_count": integer,
  "state": string,
}

Response Status Codes

Code Description
REPRESENTATIVES_RETRIEVED Representatives were returned.
NO_REPRESENTATIVES_RETRIEVED There are no representatives stored for this Office.

Try It Now: API Variables

Retrieve all the representatives in a particular election or state.

Parameter name Value  
year:
search_text:
state:

(opens in new window)