congressapi / legislators.get(List)

legislators.get and 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=Pelosi would return any Legislators with the last name Pelosi.

See http://groups.google.com/group/sunlightlabs-api-discuss/browse_thread/thread/e166c9cb755f4bd2?hl=en and the preceding thread http://groups.google.com/group/sunlightlabs-api-discuss/msg/05cfa8f1780834ca?hl=en for discussions on identifiers relevant to legislators. The Sunlight Foundation had introduced its own ID for legislators, but abandoned that ID. In many cases, the bioguide_id works well to synch data from sunlight.

Multiple Values for Parameters

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&all_legislators=1

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.

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

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

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

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 [http://bioguide.congress.gov/biosearch/biosearch.asp Congressional Biographical Directory] (also used by Washington Post/NY Times)
votesmart_id
Legislator ID assigned by [http://votesmart.org Project Vote Smart]
fec_id
[http://fec.gov Federal Election Commission] ID
govtrack_id,
ID assigned by [http://govtrack.us Govtrack.us]
crp_id
ID provided by [http://opensecrets.org Center for Responsive Politics]
congresspedia_url
URL of Legislator's entry on [http://congresspedia.org Congresspedia]
twitter_id
Congressperson's official [http://twitter.com Twitter] account
youtube_url
Congressperson's official [http://youtube.com Youtube] account
facebook_id
Facebook ID, if the legislator has a username then http://facebook.com/facebook_id will work, some users only have numeric ids in which case to get their URL you'll need to visit http://graph.facebook.com/facebook_id to get the URL (this graph url should work for all users)
senate_class
for senators I, II, or III depending on the Senator's election term
birthdate
YYYY-MM-DD formatted birth date

Examples

legislators.get.json?lastname=Pelosi
legislators.getList.xml?state=NY&party=R