Sunlight Labs API Gem

NOTE: This file is formatted in Textile and best viewed on GitHub.

A little gem that integrates with the Sunlight Labs API, originally build by luigi. From the official Sunlight 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.

This version of the library has been grabbed nearly verbatim from github.com/luigi/sunlight. Changes were made to make this work more reliably in Merb. In particular the base class SunlightObject was changed to include methods for the constants and accessors originally held in the Sunlight module. Now instead of including the module in another class, you can call the Sunlight::Legislator and Sunlight::District objects directly.

The following gems are required:

• json
• ym4r

$ sudo gem install json ym4r

The latest development version can be installed using:

$ sudo gem install rughetto-sunlight --source=http://gems.github.com

To install the stable gem, go to github.com/luigi/sunlight.

First, register for an API key here.

Then, you’ll want to stick the following lines somewhere in your Ruby environment.

  require 'rubygems'
  require 'sunlight'
  Sunlight::SunlightObject.api_key = 'yourapikeyfromtheurlabove' 
  # or it will read a file in your config directory called sunlight.api
  # each object can be initialized to a different key by calling the object's class method #api_key=

This library has been changed to use either Rails or Merb. For Rails, add the gem requirement in your particular environment file, and the Sunlight::Legislator and Sunlight::District classes will be available throughout the application.

If using merb, add the dependency requirement to your dependency.rb file:

  dependency "rughetto-sunlight",    :require_as => "sunlight"

Now, it’s time to get to the good stuff. The most useful method is Legislator#all_for:

  congresspeople = 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 "Hillary" 
  junior_senator.lastname           # returns "Clinton"   
  junior_senator.congress_office    # returns "476 Russell 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. A five-digit zip code alone won’t cut it, as there may be multiple congressional districts in a single zip code (there are ways to deal with this below). If you pass in a zip+4, then you’ll get much better geocoding results.

So Legislator#all_for returns a hash of Legislator objects, and the keys are :senior_senator, :junior_senator, and :representative. Make sure to review all the available fields from the Sunlight Labs API. You can also pass in a lat/long pair:

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

You can also use the Legislator#all_where method for searching based on available fields. You’ll get back an array of Legislator objects:

  johns = Legislator.all_where(:firstname => "John")
  floridians = Legislator.all_where(:state => "FL")
  dudes = Legislator.all_where(:gender => "M")

  johns.each do |john|
    # do stuff
  end

There’s also the District object. District#get takes in either lat/long or an address and does it’s best to return the correct Congressional District:

  district = District.get(:latitude => 33.876145, :longitude => -84.453789)
  district.state            # returns "GA"
  district.number           # returns "6"
  
  district = District.get(:address => "123 Fifth Ave New York, NY") 

Finally, two more methods, District.all_from_zipcode and District.zipcodes_in, help you out when all you have is a five-digit zip code and want to make sure you account for all the districts in a zip code, or if you want to get back all zipcodes in a given district.

  districts = District.all_from_zipcode(90210)    # returns array of District objects
  zipcodes = District.zipcodes_in("NY", "10")     # returns array of zip codes as strings  ["11201", "11202", "11203",...]

See the terms of usage for the Sunlight Labs API and the Google Maps API.

Copyright © 2008 by Rue the Ghetto under the MIT License.

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the “Software”), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.