luigi-sunlight 0.1.0 → 0.2.0

data/CHANGES.textile

@@ -1,3 +1,11 @@
+h3. 0.2.0 / 2009-03-01
+
+* Add support for twitter_id and youtube_url on Legislator
+* Add Legislator#search_by_name for fuzzy name searching
+* Add Legislator#all_in_zipcode for better lookups on a five-digit zip code
+* Raise exception when API Key isn't set
+* Credit for various fixes goes to GitHub users pengwynn, hoverbird, and wilson
+
 h3. 0.1.0 / 2008-08-20
 
 * Initial version

data/README.textile

@@ -38,18 +38,22 @@ First, register for an API key "here":http://services.sunlightlabs.com/api/regis
 
 Then, you'll want to stick the following lines somewhere in your Ruby environment.
 
-<code>
+<pre><code>
   require 'rubygems'
   require 'sunlight'
   include Sunlight
   Sunlight.api_key = 'yourapikeyfromtheurlabove'
-</code>
+</code></pre>
 
-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.
+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 @sunlight.rb@ in @RAILS_ROOT/config/initializers@. They'll load on app startup.
 
 h2. Usage
 
-Now, it's time to get to the good stuff. The most useful method is @Legislator#all_for@:
+The Sunlight gem currently supports the Legislator and District objects. The Lobbyist object is coming soon.
+
+h3. Legislator
+
+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")
@@ -63,17 +67,28 @@ Now, it's time to get to the good stuff. The most useful method is @Legislator#a
   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/.
+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@.
 
-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:
+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":http://services.sunlightlabs.com/api/docs/legislators/. 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.
+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).
+
+<pre><code>
+	members_of_congress = Legislator.all_in_zipcode(90210)
+	
+	members_of_congress.each do |member|
+		# do stuff
+	end
+	
+</code></pre>
 
-You can also use the @Legislator#all_where@ method for searching based on available fields. You'll get back an array of Legislator objects:
+You can also use the @Legislator#all_where@ method for searching based on available fields. Again, you'll get back an array of @Legislator@ objects:
 
 <pre><code>
   johns = Legislator.all_where(:firstname => "John")
@@ -85,7 +100,18 @@ You can also use the @Legislator#all_where@ method for searching based on availa
   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:
+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 "Teddy Kennedey" (real name Edward Kennedy) 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 @Legislator@ objects:
+
+<pre><code>
+	legislators = Legislator.search_by_name("Teddy Kennedey")
+	legislators = Legislator.search_by_name("Johnny Boy Kerry", 0.91)
+</code></pre>
+
+
+h3. District
+
+
+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:
 
 <pre><code>
   district = District.get(:latitude => 33.876145, :longitude => -84.453789)
@@ -95,7 +121,7 @@ There's also the @District@ object. @District#get@ takes in either lat/long or a
   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.
+Finally, two more methods, @District.all_from_zipcode@ and @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.
 
 <pre><code>
   districts = District.all_from_zipcode(90210)    # returns array of District objects
@@ -107,7 +133,7 @@ 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.
+Copyright &copy; 2009 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

data/lib/sunlight.rb

@@ -2,58 +2,61 @@ require 'rubygems'
 require 'json'
 require 'cgi'
 require 'ym4r/google_maps/geocoding'
+require 'net/http'
 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)}"
+      if Sunlight.api_key == nil or Sunlight.api_key == ''
+        raise "Failed to provide Sunlight API Key"
+      else
+        "#{API_URL}#{api_method}.#{API_FORMAT}?apikey=#{Sunlight.api_key}#{hash2get(params)}"
+      end
     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/lib/sunlight/district.rb

@@ -1,9 +1,9 @@
 module Sunlight
 
   class District < SunlightObject
-        
+
     attr_accessor :state, :number
-    
+
     def initialize(state, number)
       @state = state
       @number = number
@@ -17,14 +17,14 @@ module Sunlight
     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)
@@ -33,7 +33,7 @@ module Sunlight
       else
         nil # appropriate params not found
       end
-      
+
     end
 
 
@@ -42,46 +42,46 @@ module Sunlight
     #   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
 
 
@@ -90,9 +90,9 @@ module Sunlight
     #   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  
@@ -100,9 +100,9 @@ module Sunlight
       end # if response.class
 
     end
-    
-    
+
+
 
   end # class District
 
-end # module Sunlight
+end # module Sunlight

data/lib/sunlight/legislator.rb

@@ -1,13 +1,14 @@
 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
-    
+                  :govtrack_id, :crp_id, :event_id, :congresspedia_url, :youtube_url,
+                  :twitter_id, :fuzzy_score
+
     # Takes in a hash where the keys are strings (the format passed in by the JSON parser)
     #
     def initialize(params)
@@ -15,9 +16,9 @@ module Sunlight
         instance_variable_set("@#{key}", value) if Legislator.instance_methods.include? key
       end
     end
-    
-    
-    
+
+
+
     #
     # Useful for getting the exact Legislators for a given district.
     #
@@ -35,10 +36,10 @@ module Sunlight
     #   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
+    #   Legislator.all_for(:address => "90210") # it'll work, but use all_in_zip instead
     #
     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])
@@ -46,10 +47,10 @@ module Sunlight
       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.
@@ -59,16 +60,16 @@ module Sunlight
     #   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:
@@ -86,26 +87,109 @@ module Sunlight
     #   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
     
+    #
+    # When you only have a zipcode (and could not get address from the user), use this.
+    # It specifically accounts for the case where more than one Representative's district
+    # is in a zip code.
+    # 
+    # If possible, ask for full address for proper geocoding via Legislator#all_for, which
+    # gives you a nice hash.
+    #
+    # Returns:
+    #
+    # An array of Legislator objects
+    #
+    # Usage:
+    #
+    #   legislators = Legislator.all_in_zipcode(90210)
+    #
+    def self.all_in_zipcode(zipcode)
+
+      url = construct_url("legislators.allForZip", {:zip => zipcode})
+      
+      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 # def self.all_in_zipcode
+    
     
+    # 
+    # Fuzzy name searching. Returns possible matching Legislators 
+    # along with a confidence score. Confidence scores below 0.8
+    # mean the Legislator should not be used.
+    #
+    # The API documentation explains it best:
+    # 
+    # http://wiki.sunlightlabs.com/index.php/Legislators.search
+    #
+    # Returns:
+    #
+    # An array of Legislators, with the fuzzy_score set as an attribute
+    #
+    # Usage:
+    #
+    #   legislators = Legislator.search_by_name("Teddy Kennedey")
+    #   legislators = Legislator.search_by_name("Johnny Kerry", 0.9)
+    #
+    def self.search_by_name(name, threshold='0.8')
+      
+      url = construct_url("legislators.search", {:name => name, :threshold => threshold})
+      
+      if (response = get_json_data(url))
+        
+        legislators = []
+        response["response"]["results"].each do |result|
+          if result
+            legislator = Legislator.new(result["result"]["legislator"])
+            fuzzy_score = result["result"]["score"]
+            
+            if threshold.to_f < fuzzy_score.to_f
+              legislator.fuzzy_score = fuzzy_score.to_f
+              legislators << legislator
+            end
+          end
+        end
+        
+        if legislators.empty?
+          nil
+        else
+          legislators 
+        end
+        
+      else
+        nil
+      end
+      
+    end # def self.search_by_name
     
   end # class Legislator
 
-end # module Sunlight
+end # module Sunlight

data/sunlight.gemspec

@@ -1,7 +1,7 @@
 Gem::Specification.new do |s|
   s.name = "sunlight"
-  s.version = "0.1.0"
-  s.date = "2008-08-28"
+  s.version = "0.2.0"
+  s.date = "2009-03-01"
   s.summary = "Library for accessing the Sunlight Labs API."
   s.email = "luigi.montanez@gmail.com"
   s.homepage = "http://github.com/luigi/sunlight"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: luigi-sunlight
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Luigi Montanez
@@ -9,11 +9,12 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-08-28 00:00:00 -07:00
+date: 2009-03-01 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: json
+  type: :runtime
   version_requirement: 
   version_requirements: !ruby/object:Gem::Requirement 
     requirements: 
@@ -23,6 +24,7 @@ dependencies:
     version: 
 - !ruby/object:Gem::Dependency 
   name: ym4r
+  type: :runtime
   version_requirement: 
   version_requirements: !ruby/object:Gem::Requirement 
     requirements: