- Using the API
- Full text search
- Bulk Data
- Client Libraries
A live JSON API for the people and work of Congress, provided by the Sunlight Foundation.
- Look up members of Congress by location or by zip code.
- Official Twitter, YouTube, and Facebook accounts.
- The daily work of Congress: bills, amendments, nominations.
- The live activity of Congress: past and future votes, floor activity, hearings.
All requests require a Sunlight API key. An API key is free, and has no limits or use restrictions.
Using the API
https://) is used by default, and strongly recommended.
|/legislators||Current legislators’ names, IDs, biography, and social media.|
|/legislators/locate||Find representatives and senators for a
|/districts/locate||Find congressional districts for a
|/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.|
If you wish to check the status of the API, visit the root (no API key required):
If everything’s up, you’ll get a 200 and the following JSON:
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:
Or, by setting the key as the value of an
X-APIKEY HTTP request header.
You can request specific fields by supplying a comma-separated list of fields as the
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
You can filter on many fields with a simple key/value pair:
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:
See the documentation for a specific data type to see what fields can be filtered on.
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
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
Bills that got an up or down vote in the House
Bills cosponsored by both John McCain and Joe Lieberman
Bills sponsored by either John McCain or Joe Lieberman
All results in the Congress API are paginated. Set
page to control the page size and offset. The maximum
per_page is 50.
At the top-level of every response are count and page fields, with pagination information.
count The total number of documents that match the query.
per_page value used to find the response. Defaults to 20.
page value used to find the response. Defaults to 1.
The number of actual documents in the response. Can be less than the given
per_page if there are too few documents.
Sort results by one or more fields with the
order is optional, but if no
order is provided, the order of results is not guaranteed to be predictable.
__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
Legislators from each state, sorted by last name within state
Most relevant bills matching “health care”
If CORS isn’t an option, you can provide a
query parameter to return results the API thinks match your query best. Queries are interpreted as phrases.
Senate hearings matching “environment”
House floor updates matching “committee of the whole”
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:
<item> fields in the response will look something like:
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.
/bills maps bills’
introduced_on field to RSS’
<pubDate> field on output. You can override that with:
That will populate
<pubDate> with the contents of
history.enacted_at for each bill.
<pubDate>will always attempt to parse the field and produce a date.
<description>will always wrap its value in a
CDATAblock, as in the above example.
- If a field is missing or is
null, the value populated in RSS will be
- Though you can specify subfields, like
history.enacted_at, with the dot operator, support in RSS output is limited to direct subkeys. In other words, there can be no arrays in the subfield path.
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”
- Wildcards: use
*as a wildcard within words (e.g.
nanotech*). Cannot be used within phrases.
- Adjacency: append
~and a number to a phrase to allow the words to come within X words of each other. (e.g.
Bills matching “freedom of information” and words starting with “accountab”
Bills with “transparency” and “accountability” within 5 words of each other
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
By default, highlighting is performed with the
</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 matching “immigration”, with excerpts with no highlighting
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
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.
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.
We help maintain a repository of public domain images of members of Congress, located at:
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.
Core information for legislators, committees, and bills come from public domain scrapers and bulk data at github.com/unitedstates.
- Scrapers for bulk bill data in JSON from THOMAS.gov, 1973-present.
- Legislator and committee bulk data in YAML from various sources, 1789-present.
- Popular nicknames for bills in CSV, manually updated and unofficial (e.g. “obamacare”).
- Node: Matthew Chase Whittemore’s sunlight-congress-api (unofficial)
- Ruby: Erik Michaels-Ober’s congress gem (unofficial)
- PHP: lobostome’s FurryBear (unofficial)
- Python: python-sunlight (docs)
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.
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:
- Open States API - Legislative data for all 50 US states, DC, and Puerto Rico.
- FederalRegister.gov API - Official (government-run) JSON API for the activity of the US’ executive branch. Includes all proposed and final regulations, executive orders, and all kinds of things.
- Capitol Words API - Search speeches of members of Congress (the Congressional Record), and get all sorts of language analysis on frequently used words and phrases.
- Influence Explorer API - Data around federal lobbying, grants, contracts, and state and federal campaign contributions.