The NY Times has been quietly scraping the web for data related to the United States Congress, and making the data freely available through a public API. nytimes-congress aims to make it even easier to write Ruby applications using this data, and also provides a command shell for interacting with the API directly.
The Congress Shell (congresh for short/cute) is a simple interactive prompt that wraps IRB. It includes your API key (see setup below) and provides a few conveniences for test-driving the API.
You get a Congress object either by calling Congress.new with a number and chamber with an optional session number, or by using the Senate and House constants which return the current session of each:
current_senate = Senate
current_house = House
2007_senate = Congress.new(109, 'senate')
2009_house_2nd_session = Congress.new(111, 'house', 2)
Through a Congress object, you can get a hash of Legislators, keyed by congressional Bio ID.
>> senators = Senate.members
You could crawl the Hash values to find the bio ID in question, as this is a useful key to use across other open government APIs (notably Sunlight).
>> coburn = senators.values.find {|legislator| legislator.last_name == "Coburn"}
>> bio_id = coburn.id
Legislators come down the wire with a lot of interesting info, such as how often they vote along party lines, what roles they serve in Congress and more. Check out the full set of attributes in the Legislator class.
You can also grab a Legislator directly by their Bio ID. This call includes full details on the congressperson's roles, biographical info and more:
>> Legislator.find('C001041')
When accessing a Legislator from a collection of congress members, they include only a limited set of attributes. However, the library will make a second API call and lazy-load full attributes if you ask for them specifically. So even though a Legislator object returned through Congress.members don't have the #gender attribute, if you call for a specific Legislators gender, that data will be fetched and populated just in time.
If you need to check the current representative for a House district or senators from a state, each chamber exposes a method for that. Note that the senate call does not need a district and returns a list of two senators.
>> pa19 = House.current_member_for_state_district("PA", 19)
>> pa19.values.each do |member| puts member.name end
Todd R. Platts
These responses are returned as an array of hashes rather than a single hash (like the Legislator methods), because the order matters. These methods return members ordered according to rank for missed votes percentage, voting with party percentage, the number of "Lone No" votes and perfect voting attendance. Missed votes ranks in descending order (most votes missed first), while voting with party ranks in ascending order (lowest party agreement percentage first).
>> party = House.votes('party')
>> party.first
=> {"party_votes_pct"=>"70.49", "name"=>"Walt Minnick", "notes"=>"", "total_votes"=>"1326", "district"=>"1", "rank"=>"1", "votes_with_party"=>"18", "id"=>"M001175", "party"=>"D", "state"=>"ID"}
To find a Vote in any congress, you need to know the session (usually 1 or 2, although rarely congress will go into a 3rd session) and then the ID of the vote. Recent votes can be found easily through Thomas. Curious about the details of the "American Recovery and Reinvestment Act"? That's vote number 61:
>> vote = Senate.roll_call_vote(1, 61)
This returns a Vote object which also has an array of Positions, showing which legislators voted for and against this bill. Thus it would be simple to collect everyone who voted for and against this bill:
>> vote.positions.find_all {|position| position.for?}
>> vote.positions.find_all {|position| position.against?}
The vote also includes an array of vacant seats, if present.
You can also find recent votes, recently introduced bills and recently updated bills by any given member:
>> hillary = Legislator.find('C001041')
>> hillary.votes
>> hillary.bills("introduced")
Add Github to your rubygems sources (if you haven't already) and then install the gem: $ gem sources -a http://gems.github.com $ sudo gem install nytimes-congress
You'll also need to [get an API key]:http://developer.nytimes.com/apps/register from the [NY Times Developer Network]: http://developer.nytimes.com/. If you set the key returned to an environment variable as shown below, Congresh will pick it up and include it in all your requests. You can keep this in your bash profile, but I also recommend putting all your developer keys in a separate .api_keys file in your path
export NY_TIMES_CONGRESS_API_KEY="123456789ETC"
Then, just call 'congresh' at the command line, which will open up the Congresh shell.
Within an app, you can use the library like so:
require 'ny-times-congress'
include NYTimes::Congress
Base.api_key = '123456789ETC'
All information made available through this software is generously gathered and hosted by the New York Times (read Terms of Use below). Inspiration and code was borrowed from the excellent nytimes-movies gem written by Jacob Harris and the sunlight gem by Luigi Montanez. Thanks to Marcel Molina, Jr. for pairing with me on the lazy-loading idea.
All information made available through this software is generously organized and hosted by the New York Times and is subject to copyright. By obtaining an API key throught their Developer program and accessing this data you are agreeing to abide by certain rules and restrictions. These are available at the URLs below and you should read them before proceeding:
http://developer.nytimes.com/attribution http://developer.nytimes.com/Api_terms_of_use
Copyright (c) 2010 Patrick Ewing (patrick.henry.ewing@gmail.com) and Derek Willis (dwillis@gmail.com).
Made available under the MIT License (read LICENSE for details).