Sunlight Congress API

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

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.

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

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

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

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 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

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.

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
}

See Paging envelope for details

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

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
  }
});

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:

• 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. "transparency accountability"~5)

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

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=,

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

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 Printing 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.

• 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”).

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

• 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.

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

Planned Additions

• Draft legislation in the House, as posted to docs.house.gov.
• Reports by GAO, CBO, and Congressional committees.

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:

• GovTrack Data API
• New York Times Congress API

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.