luigi-sunlight 0.1.0

data/CHANGES.textile

@@ -0,0 +1,3 @@
+h3. 0.1.0 / 2008-08-20
+
+* Initial version

data/README.textile

@@ -0,0 +1,131 @@
+h1. Sunlight Labs API Gem
+
+NOTE: This file is formatted in Textile and best viewed on "GitHub":http://github.com/luigi/sunlight.
+
+h2. Description
+
+A little gem that integrates with the Sunlight Labs API. From the "official site":http://services.sunlightlabs.com/api/:
+
+bq. 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":http://services.sunlightlabs.com/api/docs/. 
+
+Also, the Sunlight gem integrates with the Google Maps API for "street address geocoding":http://code.google.com/apis/maps/documentation/services.html#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.
+
+
+h2. Installation
+
+The following gems are required:
+
+* json
+* ym4r
+
+@$ sudo gem install json ym4r@
+
+Then, install the stable Sunlight gem:
+
+@$ sudo gem install sunlight@
+
+Or, if you're adventurous, the latest dev version (which should be quite stable):
+
+@$ sudo gem install luigi-sunlight --source=http://gems.github.com@
+
+
+
+h2. Set Up
+
+First, register for an API key "here":http://services.sunlightlabs.com/api/register/. 
+
+Then, you'll want to stick the following lines somewhere in your Ruby environment.
+
+<code>
+  require 'rubygems'
+  require 'sunlight'
+  include Sunlight
+  Sunlight.api_key = 'yourapikeyfromtheurlabove'
+</code>
+
+If you're testing this out in IRB, you'll run them one at a time. Using Rails? Stick them in a file called @sunlight.rb@ in RAILS_ROOT/config/initializers.
+
+h2. Usage
+
+Now, it's time to get to the good stuff. The most useful method is @Legislator#all_for@:
+
+<pre><code>
+  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"  
+</code></pre>
+
+Note that you should make the best attempt to get a full street address. 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). Make sure to review all the available fields from the "Sunlight Labs API":http://services.sunlightlabs.com/api/docs/legislators/.
+
+So @Legislator#all_for@ returns a hash of @Legislator@ objects, and the keys are @:senior_senator@, @:junior_senator@, and @:representative@. You can also pass in a lat/long pair:
+
+<pre><code>
+  congresspeople = Legislator.all_for(:latitude => 33.876145, :longitude => -84.453789)
+</code></pre>
+
+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 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 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:
+
+<pre><code>
+  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
+</code></pre>
+
+There's also the @District@ object. @District#get@ takes in either lat/long or an address and does it's best to return correct Congressional District:
+
+<pre><code>
+  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") 
+</code></pre>
+
+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.
+
+<pre><code>
+  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",...]
+</code></pre>
+
+
+h2. License
+
+See the terms of usage for the "Sunlight Labs API":http://services.sunlightlabs.com/api/ and the "Google Maps API":http://code.google.com/apis/maps/terms.html.
+
+Copyright &copy; 2008 by Luigi Montanez 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.

data/lib/sunlight/district.rb

@@ -0,0 +1,108 @@
+module Sunlight
+
+  class District < SunlightObject
+        
+    attr_accessor :state, :number
+    
+    def initialize(state, number)
+      @state = state
+      @number = number
+    end
+
+
+    # Usage:
+    #   District.get(:latitude => 33.876145, :longitude => -84.453789)    # returns one District object or nil
+    #   District.get(:address => "123 Fifth Ave New York, NY")     # returns one District object or nil
+    #
+    def self.get(params)
+
+      if (params[:latitude] and params[:longitude])
+        
+        get_from_lat_long(params[:latitude], params[:longitude])
+        
+      elsif (params[:address])
+
+        # get the lat/long from Google
+        placemarks = Geocoding::get(params[:address])
+        
+        unless placemarks.empty?
+          placemark = placemarks[0]
+          get_from_lat_long(placemark.latitude, placemark.longitude)
+        end
+
+      else
+        nil # appropriate params not found
+      end
+      
+    end
+
+
+
+    # Usage:
+    #   District.get_from_lat_long(-123, 123)   # returns District object or nil
+    #
+    def self.get_from_lat_long(latitude, longitude)
+      
+      url = construct_url("districts.getDistrictFromLatLong", {:latitude => latitude, :longitude => longitude})
+      
+      if (result = get_json_data(url))
+            
+        districts = []
+        result["response"]["districts"].each do |district|
+          districts << District.new(district["district"]["state"], district["district"]["number"])
+        end
+      
+        districts.first
+        
+      else  
+        nil
+      end # if response.class
+    
+    end
+    
+
+
+    # Usage:
+    #   District.all_from_zipcode(90210)    # returns array of District objects
+    #
+    def self.all_from_zipcode(zipcode)
+      
+      url = construct_url("districts.getDistrictsFromZip", {:zip => zipcode})
+      
+      if (result = get_json_data(url))
+            
+        districts = []
+        result["response"]["districts"].each do |district|
+          districts << District.new(district["district"]["state"], district["district"]["number"])
+        end
+        
+        districts
+      
+      else  
+        nil
+      end # if response.class
+      
+    end
+
+
+
+    # Usage:
+    #   District.zipcodes_in("NY", 29)     # returns ["14009", "14024", "14029", ...]
+    #
+    def self.zipcodes_in(state, number)
+      
+      url = construct_url("districts.getZipsFromDistrict", {:state => state, :district => number})
+      
+      if (result = get_json_data(url))
+        result["response"]["zips"]
+      else  
+        nil
+      end # if response.class
+
+    end
+    
+    
+
+  end # class District
+
+end # module Sunlight

data/lib/sunlight/legislator.rb

@@ -0,0 +1,111 @@
+module Sunlight
+
+  class Legislator < SunlightObject
+    
+
+    attr_accessor :title, :firstname, :middlename, :lastname, :name_suffix, :nickname,
+                  :party, :state, :district, :gender, :phone, :fax, :website, :webform,
+                  :email, :congress_office, :bioguide_id, :votesmart_id, :fec_id,
+                  :govtrack_id, :crp_id, :event_id, :congresspedia_url
+    
+    # Takes in a hash where the keys are strings (the format passed in by the JSON parser)
+    #
+    def initialize(params)
+      params.each do |key, value|    
+        instance_variable_set("@#{key}", value) if Legislator.instance_methods.include? key
+      end
+    end
+    
+    
+    
+    #
+    # Useful for getting the exact Legislators for a given district.
+    #
+    # Returns:
+    #
+    # A Hash of the three Members of Congress for a given District: Two
+    # Senators and one Representative.
+    #
+    # You can pass in lat/long or address. The district will be
+    # determined for you:
+    #
+    #   officials = Legislator.all_for(:latitude => 33.876145, :longitude => -84.453789)
+    #   senior = officials[:senior_senator]
+    #   junior = officials[:junior_senator]
+    #   rep = officials[:representative]
+    #
+    #   Legislator.all_for(:address => "123 Fifth Ave New York, NY 10003")
+    #   Legislator.all_for(:address => "90210") # not recommended, but it'll work
+    #
+    def self.all_for(params)
+      
+      if (params[:latitude] and params[:longitude])
+        Legislator.all_in_district(District.get(:latitude => params[:latitude], :longitude => params[:longitude]))
+      elsif (params[:address])
+        Legislator.all_in_district(District.get(:address => params[:address]))
+      else
+        nil # appropriate params not found
+      end
+      
+    end
+    
+    
+    #
+    # A helper method for all_for. Use that instead, unless you 
+    # already have the district object, then use this.
+    #
+    # Usage:
+    #
+    #   officials = Legislator.all_in_district(District.new("NJ", "7"))
+    #
+    def self.all_in_district(district)
+      
+      senior_senator = Legislator.all_where(:state => district.state, :district => "Senior Seat").first
+      junior_senator = Legislator.all_where(:state => district.state, :district => "Junior Seat").first
+      representative = Legislator.all_where(:state => district.state, :district => district.number).first
+            
+      {:senior_senator => senior_senator, :junior_senator => junior_senator, :representative => representative}
+      
+    end
+    
+    
+    #
+    # A more general, open-ended search on Legislators than #all_for.
+    # See the Sunlight API for list of conditions and values:
+    #
+    # http://services.sunlightlabs.com/api/docs/legislators/
+    #
+    # Returns:
+    #
+    # An array of Legislator objects that matches the conditions
+    #
+    # Usage:
+    #
+    #   johns = Legislator.all_where(:firstname => "John")
+    #   floridians = Legislator.all_where(:state => "FL")
+    #   dudes = Legislator.all_where(:gender => "M")
+    #
+    def self.all_where(params)
+      
+      url = construct_url("legislators.getList", params)
+      
+      if (result = get_json_data(url))
+            
+        legislators = []
+        result["response"]["legislators"].each do |legislator|
+          legislators << Legislator.new(legislator["legislator"])
+        end
+        
+        legislators
+      
+      else  
+        nil
+      end # if response.class
+      
+    end
+    
+    
+    
+  end # class Legislator
+
+end # module Sunlight

data/lib/sunlight.rb

@@ -0,0 +1,59 @@
+require 'rubygems'
+require 'json'
+require 'cgi'
+require 'ym4r/google_maps/geocoding'
+include Ym4r::GoogleMaps
+
+module Sunlight
+  
+  API_URL = "http://services.sunlightlabs.com/api/"
+  API_FORMAT = "json"
+  attr_accessor :api_key
+  
+  # Houses general methods to work with the Sunlight and Google Maps APIs
+  class SunlightObject
+    
+    
+    # Constructs a Sunlight API-friendly URL
+    def self.construct_url(api_method, params)
+      "#{API_URL}#{api_method}.#{API_FORMAT}?apikey=#{Sunlight.api_key}#{hash2get(params)}"
+    end
+    
+    
+        
+    # Converts a hash to a GET string
+    def self.hash2get(h)
+      
+      get_string = ""
+      
+      h.each_pair do |key, value|
+        get_string += "&#{key.to_s}=#{CGI::escape(value.to_s)}"
+      end
+      
+      get_string
+      
+    end # def hash2get
+    
+    
+    # Use the Net::HTTP and JSON libraries to make the API call
+    #
+    # Usage:
+    #   District.get_json_data("http://someurl.com")    # returns Hash of data or nil
+    def self.get_json_data(url)
+      
+      response = Net::HTTP.get_response(URI.parse(url))
+      if response.class == Net::HTTPOK
+        result = JSON.parse(response.body)
+      else
+        nil
+      end
+      
+    end # self.get_json_data
+    
+    
+    
+  end # class SunlightObject
+  
+end # module Sunlight
+
+Dir["#{File.dirname(__FILE__)}/sunlight/*.rb"].each { |source_file| require source_file }

data/sunlight.gemspec

@@ -0,0 +1,14 @@
+Gem::Specification.new do |s|
+  s.name = "sunlight"
+  s.version = "0.1.0"
+  s.date = "2008-08-28"
+  s.summary = "Library for accessing the Sunlight Labs API."
+  s.email = "luigi.montanez@gmail.com"
+  s.homepage = "http://github.com/luigi/sunlight"
+  s.authors = ["Luigi Montanez"]
+  s.files = ['sunlight.gemspec', 'lib/sunlight.rb', 'lib/sunlight/district.rb', 
+    'lib/sunlight/legislator.rb', 'README.textile', 'CHANGES.textile']
+  s.add_dependency("json", [">= 1.1.3"])
+  s.add_dependency("ym4r", [">= 0.6.1"])
+  s.has_rdoc = true
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification 
+name: luigi-sunlight
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Luigi Montanez
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-08-28 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: json
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.1.3
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: ym4r
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.6.1
+    version: 
+description: 
+email: luigi.montanez@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- sunlight.gemspec
+- lib/sunlight.rb
+- lib/sunlight/district.rb
+- lib/sunlight/legislator.rb
+- README.textile
+- CHANGES.textile
+has_rdoc: true
+homepage: http://github.com/luigi/sunlight
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Library for accessing the Sunlight Labs API.
+test_files: []
+