Back to Docs

legislators.get & legislators.getList

Currently the Sunlight Labs API provides two methods for obtaining information about legislators: legislators.get and legislators.getList. Both of these methods operate in essentially the same way, the main difference being that legislator.get returns a single legislator (or an error if the query would have resulted in multiple legislators) and legislator.getList returns a list of legislators (a list of size one is allowed). In other words, legislator.get is purely a convenience method to avoid dealing with a list of values when only one value is needed.

Parameters

One or more parameters should be provided to a call to legislators.get or legislators.getList. Any parameters constrain the legislators which are returned, for example state=NY&party=R returns all Republicans from the state of New York whereas lastname=Biden would return any Legislators with the last name Biden.

Multiple Values for Single Parameter

When using legislators.getList it is possible to include multiple values for a single parameter. Doing so looks like:

legislators.getList?lastname=Obama&lastname=McCain

This query would return both 2008 presidential candidates.

This can help combine calls to reduce the overhead for example if you have a list of IDs that you need to get information on.

Special `all_legislators` parameter

By default, only current legislators (where in_office=1) are included in results from legislator.get or legislator.getList. If you are looking for information on former legislators with entries in the API be sure to include an &all_legislators=true parameter. When all_legislators is specified legislators with in_office=0 are included as well.

Return Value

Legislators are returned either in XML or JSON with all of the fields listed below:

Errors

Errors are indicated by setting the HTTP status code to 400 and returning a text string describing the error. The following errors may be encountered via legislators.get and legislators.getList:

Multiple Legislators Returned - returned if legislators.get is called with parameters that match more than one legislator
Invalid Parameter - returned if a parameter is provided that does not match one of the field names

Fields

The following fields are both available as parameters and also returned in the Legislator data type:

Parameter	Description
title	Title held by this legislator, either Sen or Rep
firstname	Legislator's first name
middlename	Legislator's middle name or initial
lastname	Legislator's last name
name_suffix	Legislator's suffix (Jr., III, etc.)
nickname	Preferred nickname of legislator (if any)
party	Legislator's political party (D, I, or R)
state	2 letter abbreviation of legislator's state
district	If legislator is a representative, their district. 0 is used for At-Large districts
in_office	1 if legislator is currently serving, 0 if legislator is no longer in office due to defeat/resignation/death/etc.
gender	M or F
phone	Congressional office phone number
fax	Congressional office fax number
website	URL of Congressional website
webform	URL of web contact form
email	Legislator's email address (if known)
congress_office	Legislator's Washington DC Office Address
bioguide_id	Legislator ID assigned by Congressional Biographical Directory (also used by Washington Post)
votesmart_id	Legislator ID assigned by Project Vote Smart
fec_id	Federal Election Commission ID
govtrack_id,	ID assigned by Govtrack.us
crp_id	ID provided by Center for Responsive Politics
eventful_id	Performer ID on eventful.com
sunlight_old_id	ID used by deprecated Sunlight Labs API (should not be used except for legacy purposes)
congresspedia_url	URL of Legislator's entry on Congresspedia
twitter_id	Congressperson's official Twitter account

Example Calls

legislators.get.json?state=NC&district=4

{"response": 
{"legislator": 
{"district": "4", 
"title": "Rep", 
"eventful_id": "P0-001-000016562-5", 
"state": "NC",
"votesmart_id": "119", 
"party": "D", 
"email": "", 
"crp_id": "N00002260", 
"website": "http:\/\/price.house.gov\/", 
"fax": "202-225-2014", 
"govtrack_id": "400326", 
"firstname": "David", 
"middlename": "Eugene", 
"lastname": "Price", 
"congress_office": "2162 Rayburn House Office Building", 
"bioguide_id": "P000523", 
"webform": "http:\/\/price.house.gov\/contact\/contact_form.shtml",
"nickname": "", 
"phone": "202-225-1784", 
"fec_id": "H6NC04037", 
"gender": "M", 
"name_suffix": "", 
"sunlight_old_id": "fakeopenID319", 
"congresspedia_url": "http:\/\/www.sourcewatch.org\/index.php?title=David_Price"}
}}

legislators.getList.xml?state=NY&title=Sen

<response>
  <legislators>
    <legislator>
        <district>Junior Seat</district>
        <title>Sen</title>
        <eventful_id>P0-001-000015656-6</eventful_id>
        <state>NY</state>
        <votesmart_id>55463</votesmart_id>
        <party>D</party>
        <email/>
        <crp_id>N00000019</crp_id>
        <website>http://clinton.senate.gov/</website>
        <fax>202-228-0282</fax>
        <govtrack_id>300022</govtrack_id>
        <firstname>Hillary</firstname>
        <middlename>Rodham</middlename>
        <lastname>Clinton</lastname>
        <congress_office>476 Russell Senate Office Building</congress_office>
        <bioguide_id>C001041</bioguide_id>
        <webform>http://clinton.senate.gov/contact/webform.cfm</webform>
        <nickname/>
        <phone>202-224-4451</phone>
        <fec_id>S0NY00188</fec_id>
        <gender>F</gender>
        <name_suffix/>
        <sunlight_old_id>fakeopenID456</sunlight_old_id>
        <congresspedia_url>http://www.sourcewatch.org/index.php?title=Hillary_Clinton</congresspedia_url>
    </legislator>
    <legislator>
        <district>Senior Seat</district>
        <title>Sen</title>
        <eventful_id>P0-001-000016112-4</eventful_id>
        <state>NY</state>
        <votesmart_id>26976</votesmart_id>
        <party>D</party>
        <email/>
        <crp_id>N00001093</crp_id>
        <website>http://schumer.senate.gov</website>
        <fax>202-228-3027</fax>
        <govtrack_id>300087</govtrack_id>
        <firstname>Charles</firstname>
        <middlename>E.</middlename>
        <lastname>Schumer</lastname>
        <congress_office>313 Hart Senate Office Building</congress_office>
        <bioguide_id>S000148</bioguide_id>
        <webform>
        http://schumer.senate.gov/SchumerWebsite/contact/webform.cfm
        </webform>
        <nickname>Chuck</nickname>
        <phone>202-224-6542</phone>
        <fec_id>S8NY00082</fec_id>
        <gender>M</gender>
        <name_suffix/>
        <sunlight_old_id>fakeopenID518</sunlight_old_id>
        <congresspedia_url>http://www.sourcewatch.org/index.php?title=Chuck_Schumer</congresspedia_url>
    </legislator>
  </legislators>
</response>