Sunlight Labs Services

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