A Ruby wrapper for the New York Times Congress API.
Ruby
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin
lib
spec
LICENSE
README.mkdn
Rakefile
TODO
VERSION.yml
nytimes-congress.gemspec

README.mkdn

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. 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.

Introducing 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).

>> 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.

Current Member

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

Members by Vote Type

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"}

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. 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")

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 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'

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) 2010 Patrick Ewing (patrick.henry.ewing@gmail.com) and Derek Willis (dwillis@gmail.com).

Made available under the MIT License (read LICENSE for details).