sunlightlabs-sunlight 1.0.0

data/CHANGES.textile

@@ -0,0 +1,29 @@
+h3. 1.0 / 2009-06-25
+
+* Move to the sunlightlabs GitHub account
+* Fully support the Sunlight Labs API, notably the Committee methods
+
+h3. 0.9.0 / 2009-03-15
+
+* Warning: This release is not backwards-compatible!
+* Change loading behavior of base functionality, works better with Rails and Merb
+* Sunlight::SunlightObject is now Sunlight::Base
+* For set up, Sunlight.api_key= is now Sunlight::Base.api_key=
+* For set up, using "include 'Sunlight'" is no longer recommended
+* Correct usage is Sunlight::Legislator.all_for(...) instead of just Legislator.all_for(...)
+* Credit to Rue the Ghetto (rughetto on GitHub) and Eric Mill for inspiring the improvements above
+* Add support for senate_class ("I", "II", or "III") and in_office (0 or 1) on Legislator
+* Add support for Lobbyists, Filings, and Issues
+* Huge credit to mindleak on GitHub for Lobbyist-related functionality
+
+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

@@ -0,0 +1,224 @@
+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 sunlightlabs-ruby-sunlightapi --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. _Note, this set up changed slightly as of version 0.9.0:_
+
+<pre><code>
+	require 'rubygems'
+	require 'sunlight'
+	Sunlight::Base.api_key = 'yourapikeyfromtheurlabove'
+</code></pre>
+
+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
+
+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 = 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"  
+</code></pre>
+
+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@. 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 = Sunlight::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 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 = Sunlight::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. Again, you'll get back an array of @Legislator@ objects:
+
+<pre><code>
+	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
+</code></pre>
+
+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 = Sunlight::Legislator.search_by_name("Teddy Kennedey")
+	legislators = Sunlight::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 = 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") 
+</code></pre>
+
+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 = 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",...]
+</code></pre>
+
+
+h3. Committees
+
+Members of Congress sit on all-important @Committees@, the smaller bodies that hold hearings and are first to review legislation.
+
+The @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:
+
+<pre><code>
+  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
+</code></pre>
+
+The @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:
+
+<pre><code>
+  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
+</code></pre>
+
+Coming from the opposite direction, the @Legislator@ object has a method for getting all committees for that particular Legislator, returning an array of @Committee@ objects:
+
+<pre><code>
+  legislators = Sunlight::Legislator.search_by_name("Ted Kennedy")
+  legislator = legislators.first
+  legislator.committees.each do |committee|
+    # do some stuff...
+  end
+</code></pre>
+
+h3. Lobbyists and Filings
+
+Moving away from members of Congress, the Sunlight API also exposes data on @Lobbyists@, the organizations and companies they lobby on behalf of, and the @Issues@ they lobby on. Lobbyists must submit filings to the Senate Office of Public Records, and these are represented as @Filings@ in the API.
+
+Like on the @Legislator@ object, the @Lobbyist@ object provides for fuzzy name search capability. However, because the universe of Lobbyists is much larger than Legislators, the confidence threshold defaults to 0.90 instead of 0.80, and also limits the search to Lobbyists who have filed in the current year. Both can be adjusted, and the method returns an array of @Lobbyist@ objects:
+
+<pre><code>
+	lobbyists = Lobbyist.search("Nisha Thompsen")
+	lobbyists = Lobbyist.search("Michael Klein", 0.95, 2007)	
+</code></pre>
+
+You can also use the @Filing@ object to get a specific filing record, where the unique identifier comes from the "Senate Office of Public Records":http://senate.gov/legislative/Public_Disclosure/LDA_reports.htm. The @Filing@ object will have an array of issues and lobbyists associated to it.
+
+<pre><code>
+	filing = Sunlight::Filing.get("29D4D19E-CB7D-46D2-99F0-27FF15901A4C")
+	filing.issues.each { |issue| ... }
+	filing.lobbyists.each { |lobbyist| ... }
+</code></pre>
+
+If you have a client name (that is, the organization or company the lobbyist works for) or the registrant name (the lobbyist), then you can also find associated filings. To use the @all_where@ method, pass in a hash with @:client_name@, @:registrant_name@, and @:year@ as the keys. You must pass in @:client_name@ or @:registrant_name@. 
+
+<pre><code>
+	filings = Filing.all_where(:client_name => "SUNLIGHT FOUNDATION")
+	filings.each do |filing|
+	  ...
+	  filing.issues.each { |issue| ... }
+	  filing.lobbyists.each { |issue| ... }    
+	end
+</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; 2009 by Luigi Montanez and the Sunlight Foundation 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.rb

@@ -0,0 +1,8 @@
+require 'rubygems'
+require 'json'
+require 'cgi'
+require 'ym4r/google_maps/geocoding'
+require 'net/http'
+include Ym4r::GoogleMaps
+
+Dir["#{File.dirname(__FILE__)}/sunlight/*.rb"].each { |source_file| require source_file }

data/lib/sunlight/base.rb

@@ -0,0 +1,57 @@
+module Sunlight
+
+  # Houses general methods to work with the Sunlight and Google Maps APIs
+  class Base
+
+    API_URL = "http://services.sunlightlabs.com/api/"
+    API_FORMAT = "json"
+    @@api_key = ''
+    
+    def self.api_key
+     @@api_key
+    end
+
+    def self.api_key=(key)
+     @@api_key = key
+    end
+
+    # Constructs a Sunlight API-friendly URL
+    def self.construct_url(api_method, params)
+      if api_key == nil or api_key == ''
+        raise "Failed to provide Sunlight API Key"
+      else
+        "#{API_URL}#{api_method}.#{API_FORMAT}?apikey=#{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:
+    #   Legislator::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 Base
+
+end # module Sunlight

data/lib/sunlight/district.rb

@@ -0,0 +1,108 @@
+module Sunlight
+
+  class District < Base
+
+    attr_accessor :state, :number
+
+    def initialize(state, number)
+      @state = state
+      @number = number
+    end
+
+
+    # Usage:
+    #   Sunlight::District.get(:latitude => 33.876145, :longitude => -84.453789)    # returns one District object or nil
+    #   Sunlight::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:
+    #   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:
+    #   Sunlight::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:
+    #   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  
+        nil
+      end # if response.class
+
+    end
+
+
+
+  end # class District
+
+end # module Sunlight

data/lib/sunlight/filing.rb

@@ -0,0 +1,119 @@
+module Sunlight
+  
+  class Filing < Base
+    attr_accessor :filing_id, :filing_period, :filing_date, :filing_amount,
+                  :filing_year, :filing_type, :filing_pdf, :client_senate_id,
+                  :client_name, :client_country, :client_state,
+                  :client_ppb_country, :client_ppb_state, :client_description,
+                  :client_contact_firstname, :client_contact_middlename,
+                  :client_contact_lastname, :client_contact_suffix,
+                  :registrant_senate_id, :registrant_name, :registrant_address,
+                  :registrant_description, :registrant_country,
+                  :registrant_ppb_country, :lobbyists, :issues
+
+    # 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 Filing.instance_methods.include? key
+      end
+    end
+
+    #
+    # Get a filing based on filing ID.
+    #
+    # See the API documentation:
+    #
+    # http://wiki.sunlightlabs.com/index.php/Lobbyists.getFiling
+    #
+    # Returns:
+    #
+    # A Filing and corresponding Lobbyists and Issues matching
+    # the given ID, or nil if one wasn't found.
+    #
+    # Usage:
+    #
+    #   filing = Sunlight::Filing.get("29D4D19E-CB7D-46D2-99F0-27FF15901A4C")
+    #   filing.issues.each { |issue| ... }
+    #   filing.lobbyists.each { |lobbyist| ... }
+    #
+    def self.get(id)
+      url = construct_url("lobbyists.getFiling", :id => id)
+
+      if (response = get_json_data(url))
+        if (f = response["response"]["filing"])
+          filing = Filing.new(f)
+          filing.lobbyists = filing.lobbyists.map do |lobbyist|
+            Lobbyist.new(lobbyist["lobbyist"])
+          end
+          filing.issues = filing.issues.map do |issue|
+            Issue.new(issue["issue"])
+          end
+          filing
+        else
+          nil
+        end
+      else
+        nil
+      end
+    end
+
+    #
+    # Search the filing database. At least one of client_name or
+    # registrant_name must be provided, along with an optional year.
+    # Note that year is recommended, as the full data set dating back
+    # to 1999 may be enormous.
+    #
+    # See the API documentation:
+    #
+    # http://wiki.sunlightlabs.com/index.php/Lobbyists.getFilingList
+    #
+    # Returns:
+    #
+    # An array of Filing objects that match the conditions
+    #
+    # Usage:
+    #
+    #   filings = Filing.all_where(:client_name => "SUNLIGHT FOUNDATION")
+    #   filings.each do |filing|
+    #     ...
+    #     filing.issues.each { |issue| ... }
+    #     filing.lobbyists.each { |issue| ... }    
+    #   end
+    #
+    def self.all_where(params)
+      if params[:client_name].nil? and params[:registrant_name].nil?
+        nil
+      else
+        url = construct_url("lobbyists.getFilingList", params)
+        
+        if (response = get_json_data(url))
+          filings = []
+          
+          response["response"]["filings"].each do |result|
+            filing = Filing.new(result["filing"])
+
+            filing.lobbyists = filing.lobbyists.map do |lobbyist|
+              Lobbyist.new(lobbyist["lobbyist"])
+            end
+            filing.issues = filing.issues.map do |issue|
+              Issue.new(issue["issue"])
+            end
+
+            filings << filing
+          end
+          
+          if filings.empty?
+            nil
+          else
+            filings
+          end
+        else
+          nil
+        end
+      end # if params
+    end # def self.all_where
+    
+  end # class Filing
+
+end # module Sunlight

data/lib/sunlight/issue.rb

@@ -0,0 +1,15 @@
+module Sunlight
+
+  class Issue < Base
+    attr_accessor :code, :specific_issue
+
+    # 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 Issue.instance_methods.include? key
+      end
+    end
+  end
+
+end

data/lib/sunlight/legislator.rb

@@ -0,0 +1,214 @@
+module Sunlight
+
+  class Legislator < Base
+
+
+    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, :youtube_url,
+                  :twitter_id, :fuzzy_score, :in_office, :senate_class
+
+    # 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
+    
+    # Get the committees the Legislator sits on
+    #
+    # Returns:
+    #
+    # An array of Committee objects, each possibly
+    # having its own subarray of subcommittees
+    def committees
+      url = Sunlight::Base.construct_url("committees.allForLegislator", {:bioguide_id => self.bioguide_id})
+
+       if (result = Sunlight::Base.get_json_data(url))
+         committees = []
+         result["response"]["committees"].each do |committee|
+           committees << Sunlight::Committee.new(committee["committee"])
+         end
+       else
+         nil # appropriate params not found
+       end
+       committees
+    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]
+    #
+    #   Sunlight::Legislator.all_for(:address => "123 Fifth Ave New York, NY 10003")
+    #   Sunlight::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])
+        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 = Sunlight::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 = Sunlight::Legislator.all_where(:firstname => "John")
+    #   floridians = Sunlight::Legislator.all_where(:state => "FL")
+    #   dudes = Sunlight::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 = Sunlight::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 = Sunlight::Legislator.search_by_name("Teddy Kennedey")
+    #   legislators = Sunlight::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

data/lib/sunlight/lobbyist.rb

@@ -0,0 +1,63 @@
+module Sunlight
+
+  class Lobbyist < Base
+    attr_accessor :firstname, :middlename, :lastname, :suffix,
+                  :official_position, :filings, :fuzzy_score
+  
+    # 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 Lobbyist.instance_methods.include? key
+      end
+    end
+
+    #
+    # Fuzzy name searching of lobbyists. Returns possible matching Lobbyists
+    # along with a confidence score. Confidence scores below 0.8
+    # mean the lobbyist should not be used.
+    #
+    # See the API documentation:
+    #
+    # http://wiki.sunlightlabs.com/index.php/Lobbyists.search
+    #
+    # Returns:
+    #
+    # An array of Lobbyists, with the fuzzy_score set as an attribute
+    #
+    # Usage:
+    #
+    #   lobbyists = Lobbyist.search("Nisha Thompsen")
+    #   lobbyists = Lobbyist.search("Michael Klein", 0.95, 2007)
+    #
+    def self.search_by_name(name, threshold=0.9, year=Time.now.year)
+
+      url = construct_url("lobbyists.search", :name => name, :threshold => threshold, :year => year)
+      
+      if (results = get_json_data(url))
+        lobbyists = []
+        results["response"]["results"].each do |result|
+          if result
+            lobbyist = Lobbyist.new(result["result"]["lobbyist"])
+            fuzzy_score = result["result"]["score"]
+
+            if threshold.to_f < fuzzy_score.to_f
+              lobbyist.fuzzy_score = fuzzy_score.to_f
+              lobbyists << lobbyist
+            end
+          end
+        end
+
+        if lobbyists.empty?
+          nil
+        else
+          lobbyists
+        end
+      
+      else
+        nil
+      end
+    end # def self.search
+  end # class Lobbyist
+
+end

data/sunlight.gemspec

@@ -0,0 +1,18 @@
+Gem::Specification.new do |s|
+  s.name = "sunlight"
+  s.version = "1.0.0"
+  s.date = "2009-06-10"
+  s.summary = "Library for accessing the Sunlight Labs API."
+  s.description = "Library for accessing the Sunlight Labs API."
+  s.rubyforge_project = "sunlight"
+  s.email = "luigi@sunlightfoundation.com"
+  s.homepage = "http://github.com/luigi/sunlight"
+  s.authors = ["Luigi Montanez"]
+  s.files = ['sunlight.gemspec', 'lib/sunlight.rb', 'lib/sunlight/base.rb',
+             'lib/sunlight/district.rb', 'lib/sunlight/legislator.rb', 
+             'lib/sunlight/filing.rb',  'lib/sunlight/issue.rb',
+             'lib/sunlight/lobbyist.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,81 @@
+--- !ruby/object:Gem::Specification 
+name: sunlightlabs-sunlight
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+platform: ruby
+authors: 
+- Luigi Montanez
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-06-10 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: json
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.1.3
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: ym4r
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.6.1
+    version: 
+description: Library for accessing the Sunlight Labs API.
+email: luigi@sunlightfoundation.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- sunlight.gemspec
+- lib/sunlight.rb
+- lib/sunlight/base.rb
+- lib/sunlight/district.rb
+- lib/sunlight/legislator.rb
+- lib/sunlight/filing.rb
+- lib/sunlight/issue.rb
+- lib/sunlight/lobbyist.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: sunlight
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Library for accessing the Sunlight Labs API.
+test_files: []
+