Overview

Using the Congress API, you can retrieve legislative data from the House of Representatives, the Senate and the Library of Congress. The API, which originated at The New York Times in 2009, includes details about members, votes, bills, nominations and other aspects of congressional activity. This document describes the requests that users can make of the API and the responses that it returns.

In this document, curly braces { } indicate required variables. Square brackets [ ] indicate optional parameters or placeholders.

Get an API Key

You can sign up to request an API key at ProPublica’s Data Store.

Scope of Data

The Congress API returns the following types of data:

Most of the data in the ProPublica Congress API is updated daily, while votes are updated every 30 minutes.

Terms of Use

Use of this API is available under a Creative Commons Attribution-NonCommercial-NoDerivs 3.0 United States license. Commercial users may be subject to additional use fees. To request permission for any commercial use, please fill out the API key request form.

All users are required to abide by the following terms of use for data provided by the API:

  1. You can’t republish the raw data in its entirety, or otherwise distribute the data (in whole or in part) on a stand-alone basis.
  2. You can’t change the data except to update or correct it.
  3. Unless authorized, you can’t charge people money to look at the data, or sell advertising specifically against it. (It may be used on advertising-supported websites or on paid-access sites that provide other content, benefits and/or services.)
  4. You can’t sub-license or resell the data to others.
  5. If you use the data for publication, you must cite ProPublica.
  6. We do not guarantee the accuracy or completeness of the data. You acknowledge that the data may contain errors and omissions.
  7. We are not obligated to update the data, but in the event we do, you are solely responsible for checking our site for any updates.
  8. You will indemnify, hold harmless, and defend ProPublica from and against any claims arising out of your use of the data.

Authentication

To use the Congress API, you must sign up for an API key. Usage is limited to 5000 requests per day (rate limits are subject to change). The API key must be included in all API requests to the server, as a header:

X-API-Key: PROPUBLICA_API_KEY

To authorize, use this code:

With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "X-API-Key: PROPUBLICA_API_KEY"

Make sure to replace PROPUBLICA_API_KEY with your API key.

Requests

The Congress API uses a RESTful style. See individual methods below for permitted requests. The API only accepts GET requests. All requests begin with:

https://api.propublica.org/congress/{version}/

The current version is v1. For requests that have a congress parameter, the current Congress is 115.

Common Parameters

These parameters are used in all request types. See below for URI structures and additional parameters for each type of request.

The following parameters are optional:

Responses

The API provides JSON and XML responses for every type of request, and supports JSONP callbacks. Responses that are not date-based return the first 20 results; pagination is available via an offset query string parameter using multiples of 20 for most votes, nomination and bill requests that return more than one object.

Errors

This error section is stored in a separate file in includes/_errors.md. Slate allows you to optionally separate out your docs into many files…just save them to the includes folder and add them to the top of your index.md’s frontmatter. Files are included in the order listed.

The ProPublica Congress API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request is improperly formed
403 Forbidden – Your request did not include an authorization header
404 Not Found – The specified record(s) could not be found
406 Not Acceptable – You requested a format that isn’t json or xml
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – The service is currently not working. Please try again later.

Data Sources

The data returned by the Congress API is compiled from the following sources:

Certain fields in the API responses (such as party totals and vote agreement percentages) are calculated by ProPublica, based on these data sources. The data returned by the Congress API is in the public domain.

Data Update Schedules