Drumbone API

Deprecation Notice

This API is deprecated in favor of the Real Time Congress API. It contains most legislative information that Drumbone does. Drumbone may be deactivated in the near future.

Introduction

Drumbone is a RESTful JSON API over data about legislators, bills, and roll call votes. Unlike the Sunlight Labs Congress API, all data is taken from existing APIs and data sources (especially GovTrack); there is no original data here.

The name "Drumbone" is taken from the name of an instrument created from PVC pipes whose length can be adjusted as needed to create various sounds and music. Accordingly, the purpose of Drumbone is to pipe in data from disparate sources, and redistribute it in the simplest and most flexible format possible.

Drumbone is designed to serve thin clients, and applications where bandwidth is at a premium. It was originally built to serve a mobile app, the Congress Android app), and a widget service, Sunlight's Politiwidgets. The idea is to give you all the information you need to fill in a user interface in one HTTP call. It is not meant to serve as a bulk data repository. Drumbone uses GovTrack for that, and so should you.

Drumbone is written in Ruby, with the Sinatra framework, and uses MongoDB for data storage. The code for this service is available on Github.

GovTrack

Drumbone's data on bills and roll call votes is entirely dependent on the public data that GovTrack provides, and any use of it through Drumbone is subject to GovTrack's original license terms. GovTrack has been a foundational source of data about Congress since 2004, and their data underlies many Sunlight projects, including OpenCongress. Many thanks go to GovTrack for its role in supporting an ecosystem of open data about Congress.

Getting Started

API Details

The URL structure is:

http://drumbone.services.sunlightlabs.com/v1/api/[method].json

All responses are in JSON. XML is not likely to be supported.

You must pass in a Sunlight Labs API key in order to use the service. This can be provided in the query string, using the format "apikey=[yourApiKey]", or as an HTTP request header named "X-APIKEY".

This is version 1 of the API. New data and methods may be added to it without notification, but no data will be removed, and no backwards-incompatible changes will be made without seeking community input, or advancing to a version 2.

Data and Methods

There are 3 kinds of documents in the API:

  • Legislator - A legislator in Congress. Legislators go as far back as the Sunlight Congress API.
  • Bill - A bill, or resolution, in Congress. Bills go as far back as the 111th Congress.
  • Roll - A roll call vote by the House or Senate. Roll calls go as far back as the 111th Congress.

And 5 methods:

  • 3 singular methods - legislator, bill, roll
  • 2 plural methods - bills, rolls

Singular methods return one document, and require a unique key to locate it. If the unique key is missing or not found, a 404 response will be returned (except for JSONP - see the "JSONP" section for details).

Plural methods return an array of documents. These methods accept various filtering parameters (for example, an "enacted" flag for bills), an "order" parameter for sorting, and pagination parameters.

Look at the page for each document type, linked above, to see the set of unique keys, filtering parameters, and ordering parameters available for each.

Partial Responses

By default, responses will return the entire set of information in each document. This is often quite large, especially for bills and roll calls, and usually you'll only want a specific subset of the document.

You can specify exactly which fields of the document you want using a "sections" parameter, using commas to separate multiple sections.

Every field on the document is its own section. There is also a "magic" section called basic on every document, which will return a specific set of scalar values at the top level of the document. The contents of the "basic" section are listed on the page for each document type: legislators, bills, and roll calls.

You can get more granular and request subsections by using the dot operator to dive down through the document (e.g. "contracts.total_amount", "voters.L000551"). Think of it as accessing the document as a JSON object in JavaScript.

JSONP support

Drumbone supports JSONP. If you pass in a query string parameter named "callback", this will trigger a JSONP response, with the data wrapped inside a call to the value of the "callback" parameter.

Important - 404 errors are handled differently for JSONP requests. Normally, if your call to a singular method ("legislator", "bill", "roll") doesn't have a result, you'll get a 404 error code. However, since JSONP requests are typically done inside of a browser, using a script tag and not an XmlHttpRequest, your callback would simply never be executed if a 404 occurred.

For this reason, JSONP requests that would ordinarily result in a 404 will result in a 200 response code, whose response body will be a JSON document with a root key of "error". Your JavaScript callback method should expect this possibility.

Filtering and sorting

Results for plural methods can be filtered and sorted on various parameters, specific to each document type.

To filter on a parameter, simply use it as a key and value pair. Use "true" or "false" for boolean flags. To sort by a parameter, use "order" with the field name as the value. To control the direction of the ordering, use "sort" with a value of "asc" or "desc" (defaults to "desc").

Look at the documentation for legislators, bills, and roll calls to see which fields are available for filtering and sorting.

For example, this is the URL to fetch some basic information about the latest bill passed by the House in the 111th Congress:

Note: The above example filters on "enacted", even though it's already sorting by "enacted_at". This is because sorting on a timestamp will not filter out null values - so if you order on a timestamp with a sort of "ASC", without filtering on other fields, results with null timestamps will show up at the top of the results. This is why, for every timestamp on a document that has a chance of being null, there is a corresponding flag to help filter results.

Pagination

Results for plural methods are paginated. To control it, use "page" and "per_page" parameters to specify how many results you want, and where to start from. The default number of documents per page is 20, and can be set to a maximum of 500.