NY Times Congress =============== A Ruby wrapper for the New York Times Congress API. --------------------- 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](http://open.blogs.nytimes.com/2009/01/08/introducing-the-congress-api/). [ny-times-congress](http://github.com/hoverbird/ny-times-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. Introdushing Congresh --------------------- 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. Congress.new --------------------- 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 Legislator --------------------- 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). $ hrc = senators.values.find {|legislator| legislator.name == "Hillary Clinton"} $ bio_id = hrc.bio_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. Roll Call Votes --------------------- 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](http://thomas.loc.gov/home/rollcallvotes.html). 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?} You can also find recent votes by any given senator: $ hillary = Legislator.find('C001041') $ hillary.votes Setup --------------------- 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 hoverbird-ny-times-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 NYTIMES_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' Acknowledgements --------------------- 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. Terms of Use --------------------- 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 License --------------------- Copyright (c) 2009 Patrick Ewing Made available under the MIT License (read LICENSE for details).