A live JSON API for the people and work of Congress, provided by the Sunlight Foundation.

Features

Lots of features and data for members of Congress:

We also provide Congress' daily work:

All data is served in JSON, and requires a Sunlight API key. An API key is free to register and has no usage limits.

We have an API mailing list, and can be found on Twitter at @sunlightlabs. Bugs and feature requests can be made on Github Issues.

Methods

Calls to the Sunlight Congress API are of the form: 

http://congress.api.sunlightfoundation.com/[method]
/legislators Current legislators' names, IDs, biography, and social media.
/legislators/locateFind representatives and senators for a latitude/longitude or zip.
/districts/locateFind congressional districts for a latitude/longitude or zip.
/committees Current committees, subcommittees, and their membership.
/bills Legislation in the House and Senate, back to 2009. Updated daily.
/bills/searchFull text search over legislation.
/votes Roll call votes in Congress, back to 2009. Updated within minutes of votes.
/floor_updates To-the-minute updates from the floor of the House and Senate.
/hearings Committee hearings in Congress. Updated as hearings are announced.
/upcoming_bills Bills scheduled for debate in the future, as announced by party leadership.

Parameters

API Key

All requests to the Congress API require a Sunlight API key. An API key is free to register and has no usage limits.

API keys can be provided with a request through the query string: 

/bills?apikey=[your_api_key]

Or, by setting the key as the value of an X-APIKEY HTTP request header.

Filtering

You can filter on many fields with a simple key/value pair: 

/legislators?last_name=Smith
/bills?bill_type=hr&congress=112

The API will automatically treat numbers as numbers, and "true" and "false" as booleans. Dates and times are compared as strings.

To force the API to treat a value as a string, use quotes: 

/legislators?thomas_id="136"

See the documentation for a specific data type to see what fields can be filtered on.

Operators

The API supports 8 operators that can be combined with filters:

gt - the field is greater than this value
gte - the field is greater than or equal to this value
lt - the field is less than this value
lte - the field is less than or equal to this value
not - the field is not this value
all - the field is an array that contains all of these values (separated by "|")
in - the field is a string that is one of these values (separated by "|")
nin - the field is a string that is not one of these values (separated by "|")
exists - the field is both present and non-null (supply "true" or "false")

All operators are applied by adding two underscores ("__") after the field name. They cannot be combined.

Senate votes that got more than 70 Yea votes 

/votes?breakdown.total.Yea__gte=70&chamber=senate

Bills that got an up or down vote in the House 

/bills?history.house_passage_result__exists=true&chamber=house

Bills cosponsored by both John McCain and Joe Lieberman 

/bills?cosponsor_ids__all=M000303|L000304

Bills sponsored by either John McCain or Joe Lieberman 

/bills?sponsor_id__in=M000303|L000304

Pagination

All results in the Congress API are paginated. Set per_page and page to control the page size and offset. The maximum per_page is 50. 

/floor_updates?chamber=house&per_page=50&page=3

At the top-level of every response are count and page fields, with pagination information. 

"count": 163,
"page": {
  "per_page": 50,
  "page": 3,
  "count": 50
}

count
The total number of documents that match the query.

page.per_page
The per_page value used to find the response. Defaults to 20.

page.page
The page value used to find the response. Defaults to 1.

page.count
The number of actual documents in the response. Can be less than the given per_page if there are too few documents.

Sorting

Sort results by one or more fields with the order parameter. order is optional, but if no order is provided, the order of results is not guaranteed to be predictable.

Append __asc or __desc to the field names to control sort direction. The default direction is desc, because it is expected most queries will sort by a date.

Any field which can be used for filtering may be used for sorting. On full-text search endpoints (URLs ending in /search), you may sort by score to order by relevancy.

Most recent bills 

/bills?order=introduced_on

Legislators from each state, sorted by last name within state 

/legislators?order=state__asc,last_name__asc

Most relevant bills matching "health care" 

/bills/search?query="health care"&order=score

Partial responses

You can request specific fields by supplying a comma-separated list of fields as the fields parameter.

Many fields are not returned unless requested. If you don't supply a fields parameter, you will get the most commonly used subset of fields only.

To save on bandwidth, parsing time, and confusion, it's recommended to always specify which fields you will be using.

Latest vote numbers and their results 

/votes?fields=roll_id,result,breakdown.total
"results": [
  {
    "breakdown": {
      "total": {
        "Yea": 222,
        "Nay": 190,
        "Not Voting": 19,
        "Present": 0
      }
    },
    "result": "Passed",
    "roll_id": "h43-2013"
  },
  {
    "breakdown": {
      "total": {
        "Yea": 261,
        "Nay": 154,
        "Not Voting": 16,
        "Present": 0
      }
    },
    "result": "Passed",
    "roll_id": "h44-2013"
  }
  ...
]

Client-side support

The Congress API supports CORS for all domains, so requests using any modern JavaScript library inside any modern browser should Just Work.

If CORS isn't an option, you can provide a callback parameter to wrap the results in a JavaScript function, suitable for use with JSONP. This can be used to make cross-domain requests to the Congress API within the browser, when CORS is not supported.

For example: 

/legislators?last_name=Reid&callback=myCallback

will return: 

myCallback({
  "results": [
    {
      "bioguide_id": "R000146",
      "chamber": "senate",
      "last_name": "Reid"
      ...
    }
  ],
  "count": 1,
  "page": {
    "count": 1,
    "per_page": 20,
    "page": 1
  }
}
});

Provide a query parameter to return results the API thinks best match your query. Queries are interpreted as phrases.

Senate hearings matching "environment" 

/hearings?query=environment&chamber=senate

House floor updates matching "committee of the whole" 

/floor_updates?query=committee of the whole&chamber=house

Explain mode

Add an explain=true parameter to any API request to return a JSON response with how the API interpreted the query, and database-specific explain information.

This is a convenience for debugging, not a "supported" API feature. Don't make automatic requests with explain mode turned on.

Full text search

Endpoints ending with /search that are given a query parameter perform full text search. These queries can use some advanced operators. Queries are interpreted as keywords (use quotes to form phrases).

Laws matching "health care" and "medicine" 

/bills/search?query="health care" medicine&history.enacted=true

Operators allowed:

Bills matching "freedom of information" and words starting with "accountab" 

/bills/search?query="freedom of information" accountab*

Bills with "transparency" and "accountability" within 5 words of each other 

/bills/search?query="transparency accountability"~5

Highlighting

When performing full text search, you can retrieve highlighted excerpts of where your search matched by using the parameter highlight=true. (This will make the request slower, so only use if needed.)

Recent bills matching "gun control", with highlighting 

/bills/search?query="gun control"&highlight=true&order=introduced_on

By default, highlighting is performed with the <em> and </em> tags. Control these tags by passing start and close tags to the highlight.tags parameter. (Disable the highlighting of search terms altogether, leaving only a plain text excerpt, by passing a lone comma, ,.)

Bills matching "immigration", with excerpts highlighted with <b> tags 

/bills/search?query=immigration&highlight=true&highlight.tags=<b>,</b>

Bills matching "immigration", with excerpts with no highlighting 

/bills/search?query=immigration&highlight=true&highlight.tags=,

Control the size of highlighted excerpts with the highlight.size parameter. (Note: This doesn't always work; the database makes a best attempt.) The default highlight.size is 200.

Bills matching "drugs", with larger excerpts 

/bills/search?query=drugs&highlight=true&highlight.size=500

Bulk Data

We provide some bulk data for direct download, separately. The Congress API as documented above is not designed for retrieving bulk data -- requests are limited to a maximum of 50 per page, and many fields need to be specifically requested. If you need data in bulk, please use these resources rather than fetching it all through the API.

Legislator spreadsheet

We offer a CSV of basic legislator information for direct download here.

It includes basic information about names, positions, biographical details, contact information, social media accounts, and identifiers for various public databases.

It contains current information only - it does not include a legislator's history of changes to name, party, chamber, etc.

Zip Codes to Congressional Districts

We provide a CSV connecting Zip Code Tabulation Areas (ZCTAs) to congressional districts for direct download here.

This is the data we use in our /legislators/locate and /districts/locate endpoints when a zip is provided. These are technically not zip codes, but ZCTAs: all of our warnings and caveats about using ZCTAs apply.

Legislator Photos

We provide zip files of official photos of members of Congress, as taken from the Congressional Pictorial Directory. We offer them in 3 sizes, and the files are all named using the member's Bioguide ID.

Core Information

Core information for legislators, committees, and bills come from public domain scrapers and bulk data at github.com/unitedstates.

Client Libraries

If you've written a client library, please tweet at @sunlightlabs or email us so we can link to it here.

Other

Migrating from our old Sunlight Congress API

This Sunlight Congress API replaces and deprecates our old Sunlight Congress API. We will keep the old Congress API running until at least the end of the 113th Congress (January 2015). We advise users of the old Congress API to upgrade to this one as soon as possible.

We have prepared a migration guide that shows how to move from each method in the old API to the new API.

Planned Additions

To suggest new data and features, open a ticket on Github Issues.

More APIs

If the Sunlight Congress API doesn't have what you're looking for, check out other Congress APIs:

Or if you're looking for other government data: