Sunlight Labs API Gem
NOTE: This file is formatted in Textile and best viewed on GitHub.
See RDoc.info for the full RDoc.
A little gem that integrates with the Sunlight Labs API. From the official site:
The Sunlight Labs API provides methods for obtaining basic information on Members of Congress, legislator IDs used by various websites, and lookups between places and the politicians that represent them. The primary purpose of the API is to facilitate mashups involving politicians and the various other APIs that are out there.
Full API documentation available here.
Also, the Sunlight gem integrates with the Google Maps API for street address geocoding. Because some zip codes overlap two or more congressional districts, passing in a latitude/longitude will give users the most accurate information. Since it’s highly unlikely a user would know their exact lat/long, the Google Maps API is used to translate a street address string into a lat/long pair.
The following gems are required:
$ sudo gem install json geocoder
Then, install the gem:
$ sudo gem install sunlight
First, register for an API key here.
Then, you’ll want to stick the following lines somewhere in your Ruby environment. Note, this set up changed slightly as of version 0.9.0:
require 'rubygems' require 'sunlight' Sunlight::Base.api_key = 'yourapikeyfromtheurlabove'
If you’re testing this out in IRB, you’ll run them one at a time. If you’re using Rails >=2.1, stick them in a file called
RAILS_ROOT/config/initializers. They’ll load on app startup.
The Sunlight gem fully wraps the Sunlight Labs API.
Time to get to the good stuff. The most useful method is
congresspeople = Sunlight::Legislator.all_for(:address => "123 Fifth Ave New York, NY 10003") senior_senator = congresspeople[:senior_senator] junior_senator = congresspeople[:junior_senator] representative = congresspeople[:representative] junior_senator.firstname # returns "Kirsten" junior_senator.lastname # returns "Gillibrand" junior_senator.congress_office # returns "531 Dirksen Senate Office Building" junior_senator.phone # returns "202-224-4451"
Note that you should make the best attempt to get a full street address, as that is geocoded behind the scenes into a lat/long pair. If all you have is a five-digit zip code, you should not use
Legislator#all_for, instead opting for
Legislator#all_in_zipcode (see below). If you pass in a zip+4, then go ahead and use
Legislator#all_for returns a hash of
Legislator objects, and the keys are
:representative. Make sure to review all the available fields from the Sunlight Labs API. You can also pass in a lat/long pair:
congresspeople = Sunlight::Legislator.all_for(:latitude => 33.876145, :longitude => -84.453789)
This bypasses the geocoding necessary by the Google Maps API. For social networks and other applications with a User object, it makes sense to geocode the user’s address up front and save the lat/long data in the local database. Then, use the lat/long pair instead of address, which cuts a substantial bit of time from the
Legislator#all_for request since the Google Maps API Geocoding function doesn’t have to be called.
Have a five-digit zip code only? You can use the
Legislator#all_in_zipcode method, but keep in mind that a single zip may have multiple U.S. Representatives, as congressional district lines frequently divide populous zip codes. Unlike
Legislator#all_for, this method returns an array of legislators, and it’ll be up to you to parse through them (there will be a senior senator, a junior senator, and one or more representatives).
members_of_congress = Sunlight::Legislator.all_in_zipcode(90210) members_of_congress.each do |member| # do stuff end
You can also use the
Legislator#all_where method for searching based on available fields. Again, you’ll get back an array of
johns = Sunlight::Legislator.all_where(:firstname => "John") floridians = Sunlight::Legislator.all_where(:state => "FL") dudes = Sunlight::Legislator.all_where(:gender => "M") johns.each do |john| # do stuff end
Lastly, to provide your users with a name search functionality, use
Legislator#search_by_name, which uses fuzzy matching to compensate for nicknames and misspellings. So “Ed Markey” (real name Edward Markey) and “Jack Murtha” (real name John Murtha) will return the correct matches. You can specify a higher confidence threshold (default set to 0.80) if you feel that the matches being returned aren’t accurate enough. This also returns an array of
legislators = Sunlight::Legislator.search_by_name("Ed Markey") legislators = Sunlight::Legislator.search_by_name("Johnny Boy Kerry", 0.91)
There’s also the
District#get takes in either lat/long or an address and does it’s best to return the correct Congressional District:
district = Sunlight::District.get(:latitude => 33.876145, :longitude => -84.453789) district.state # returns "GA" district.number # returns "6" district = Sunlight::District.get(:address => "123 Fifth Ave New York, NY")
Finally, two more methods,
District.zipcodes_in, help you out when you want to get all districts in a given zip code, or if you want to get back all zip codes in a given district.
districts = Sunlight::District.all_from_zipcode(90210) # returns array of District objects zipcodes = Sunlight::District.zipcodes_in("NY", "10") # returns array of zip codes as strings ["11201", "11202", "11203",...]
Members of Congress sit on all-important
Committees, the smaller bodies that hold hearings and are first to review legislation.
Committee object has three identifying fields, and an array of subcommittees, which are
Committee objects themselves. To get all the committees for a given chamber of Congress:
committees = Sunlight::Committee.all_for_chamber("Senate") # or "House" or "Joint" some_committee = committees.last some_committee.name # "Senate Committee on Agriculture, Nutrition, and Forestry" some_committee.id # "SSAF" some_committee.chamber # "Senate" some_committee.subcommittees.each do |subcommittee| # do some stuff... end
Committee object also keeps a collection of members in that committee, but since that’s an API-heavy call, it must be done for each Committee one at a time:
committees = Sunlight::Committee.all_for_chamber("Senate") # or "House" or "Joint" some_committee = committees.last # some_committee.members starts out as nil some_committee.load_members # some_committee.members is now populated some_committee.members.each do |legislator| # do some stuff... end
Coming from the opposite direction, the
Legislator object has a method for getting all committees for that particular Legislator, returning an array of
legislators = Sunlight::Legislator.search_by_name("Byron Dorgan") legislator = legislators.first legislator.committees.each do |committee| # do some stuff... end
Copyright © 2009 by Luigi Montanez and the Sunlight Foundation. See LICENSE.textile for more information.