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

All requests require a Sunlight API key. An API key is free, and has no limits or use restrictions.

We have an API mailing list, and can be found on Twitter at @sunlightlabs. Report bugs and request features on GitHub Issues.

Using the API

https://congress.api.sunlightfoundation.com/[method]

Encryption (https://) is used by default, and strongly recommended.

Methods

Path Description
/legislators Current legislators’ names, IDs, biography, and social media.
/legislators/locate Find representatives and senators for a latitude/longitude or zip.
/districts/locate Find 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/search Full text search over legislation.
/amendments Amendments in the House and Senate, back to 2009. Updated daily.
/nominations Presidential nominations before the Senate, back to 2009. Updated daily.
/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.
/congressional_documents/search Congressional documents including House witness documents and House committee reports.
/documents/search Oversight documents including Government Accountability Office reports and Inspectors General reports.

Status endpoint

If you wish to check the status of the API, visit the root (no API key required):

https://congress.api.sunlightfoundation.com

If everything’s up, you’ll get a 200 and the following JSON:

{
  "status": 200,
  "message": "I live!",
  "documentation": "http://sunlightlabs.github.io/congress/",
  "code": "https://github.com/sunlightlabs/congress",
  "report_bugs": "https://github.com/sunlightlabs/congress/issues",
  "more_apis": "http://sunlightfoundation.com/api/"
}

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:

/legislators?apikey=[your_api_key]

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

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"
  }
  ...
]

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="01501"

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:

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

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 match your query best. 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.

RSS support (experimental)

Some endpoints support RSS output, in an XML format. This support is experimental, could change, and may have bugs. An API key is still required.

Enable RSS by passing format=rss, like so:

/bills?format=rss

The <item> fields in the response will look something like:

<item>
  <title>Establishing the budget for the United States Government for fiscal year 2015...</title>
  <description>
    <![CDATA[Sets forth the congressional budget for the federal government for FY2015...]]>
  </description>
  <link>http://beta.congress.gov/bill/113th/house-concurrent-resolution/96</link>
  <guid isPermaLink="false">hconres96-113</guid>
  <pubDate>Fri, 04 Apr 2014 00:00:00 -0400</pubDate>
</item>

The following endpoints support RSS:

RSS output is, by the spec’s design, limited to a small subset of generic fields. You will only get RSS’ most basic fields:

Each endpoint defines the best default database fields it can map to those RSS fields. See each supported endpoint’s documentation for what fields are RSS-mapped by default.

However, you can override those defaults with rss.[field] parameters that point to the field you’d like to be mapped instead.

For example, /bills maps bills’ introduced_on field to RSS’ <pubDate> field on output. You can override that with:

/bills?format=rss&order=history.enacted_at&rss.pubDate=history.enacted_at

That will populate <pubDate> with the contents of history.enacted_at for each bill.

Some notes:

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 help maintain a repository of public domain images of members of Congress, located at:

https://github.com/unitedstates/images

Images are collected primarily from the Government Publishing Office’s Member Guide, and hosted at predictable URLs, using the member of Congress’ Bioguide ID.

See the URL documentation for complete details.

Are we missing some photos? Raise the issue and let us know - we welcome contributions!

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.

Congress on IFTTT

The Sunlight Foundation has an IFTTT channel that offers some “triggers” based on events in Congress.

Check out our shared recipes and our favorite recipes for some examples of how to make use of our congressional data with IFTTT.

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: