On our new API homepage, we recently added the Drumbone API. It’s a light, flexible, JSON-only API over Congressional legislator, bill, and vote data, and we currently use it in two of our products. I wanted to take a minute and explain why we built this, especially in the face of the existing suite of community sources for this data.

At the beginning of this year, we began building a widget service for all kinds of information about legislators and their voting records on bills, which has shaped up as Politiwidgets. It was clear we’d need some kind of aggregator for all of this data, that could be delivered up to the widgets on demand.

At the same time, I wanted to enhance our Congress app for Android with information about bills and voting records. This was trickier than I expected, because of the constraints in bandwidth and memory that mobile devices face. There are APIs out there for bill and vote information already (including the NY Times Congress API, the OpenCongress API, and GovTrack’s APIs and bulk data), and they are all excellent data sources for other web apps. From the perspective of a mobile device though, the responses these APIs return are unwieldy, and not ideal for thin clients.

Drumbone is built to power both of these apps. It offers a RESTful JSON API that is quick and easy for the Congress app to consume, using Android’s built-in JSON parser, and a JSONP interface that is straightforward for the JavaScript-powered widgets to use to populate themselves.

You can get data about individual legislators (by bioguide ID or GovTrack ID), individual bills, individual roll call votes, and search for paginated results for bills and roll call votes. For searching on multiple legislators, use the Sunlight Congress API. Information only goes back to the beginning of the current Congress, the 111th.

Probably the most useful thing about Drumbone is the ability to request partial responses. By specifying a comma separated list of “sections”, you can request only the pieces of information you want about a document, drastically lowering the size of the response. Google did something similar in introducing partial responses with several of its APIs back in March, with only slightly more complicated syntax.

The Congress app for Android uses this for bills, only requesting basic information for displaying lists of search results, and then requesting additional information, such as the bill’s potentially lengthy summary, asynchronously once the screen for that bill is displayed. You can request only subsections as well, nested arbitrarily deeply. For example, Politiwidgets uses this for its voting record widget – this widget fetches information about a roll call, and needs basic biographical information about the voter. But to get this information for all 100 or 435 voters would be huge, so it requests a subsection of the roll call object from the “voters” section for just that legislator, which are keyed by bioguide_id (“voters.L000551” for Barbara Lee).

On the backend, Drumbone is built in Ruby on top of MongoDB, using the Sinatra microframework, and the code can be found on Github. This was my first experience using a schemaless database, and I found it a fun and enlightening experience. Drumbone turned out to be particularly well suited for this, as the set of data present about each item is so large that being able to nest data arbitrarily deeply (and even index nested keys) was a huge boon. Every field in a given response is part of the same collection (a table) and document (a row).

Check out the full documentation for more information about what data’s available. I need to emphasize that this is not meant to be an API to get bulk data from, or to use for anything other than thin clients. For archival use, you should use GovTrack for bill/vote data, and the Sunlight Congress API for legislator data.

We wrote this service for us, but there’s no reason others shouldn’t be able to use it. You can use your existing Sunlight API key if you have one, or sign up for one. There’s also a Ruby wrapper for Drumbone, and a mostly-extracted Java wrapper inside the Android app code, both up on Github, to make it easy to start playing around with what’s available. For discussion, join the Sunlight Labs API mailing list.

Finally, a huge thank you to GovTrack, and its excellent repository of data. GovTrack does all the hard work of pulling this information from THOMAS, and makes all of our lives much easier for doing so. The use of Drumbone’s bill and vote information is subject to Govtrack’s license terms, and we encourage you to list GovTrack in your attribution.