lib/sunlight/filing.rb lib/sunlight/issue.rb lib/sunlight/lobbyist.rb spec/filing_spec.rb spec/issue_spec.rb spec/lobbyist_spec.rb @@ -8,6 +8,8 @@ h3. 0.9.0 / 2009-03-15 * 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 CHANGES.textile @@ -39,9 +39,9 @@ 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. _Note, this set up changed slightly as of version 0.9.0:_ <pre><code> - require 'rubygems' - require 'sunlight' - Sunlight::Base.api_key = 'yourapikeyfromtheurlabove' + 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. @@ -55,15 +55,15 @@ 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" + 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@. @@ -71,7 +71,7 @@ Note that you should make the best attempt to get a full street address, as that 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) + 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. @@ -80,23 +80,22 @@ Have a five-digit zip code only? You can use the @Legislator#all_in_zipcode@ met <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 = 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 + 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: @@ -113,18 +112,48 @@ 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") + 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",...] + 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. 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> README.textile @@ -18,8 +18,8 @@ describe Sunlight::Legislator do describe "#initialize" do it "should create an object from a JSON parser-generated hash" do - carolyn = Legislator.new(@example_hash) - carolyn.should be_an_instance_of(Legislator) + carolyn = Sunlight::Legislator.new(@example_hash) + carolyn.should be_an_instance_of(Sunlight::Legislator) carolyn.firstname.should eql("Carolyn") end spec/legislator_spec.rb @@ -1,2 +1 @@ -require File.dirname(__FILE__) + '/../lib/sunlight' -include Sunlight +require File.dirname(__FILE__) + '/../lib/sunlight' \ No newline at end of file spec/spec_helper.rb 37f8dcc82a48d46effeffd1df79afcdcf7b7cb6b Luigi Montanez luigi.montanez@gmail.com http://github.com/luigi/sunlight/commit/b4948c722d11ffcc46b9ccdb299bcd245fcce1b4 b4948c722d11ffcc46b9ccdb299bcd245fcce1b4 2009-03-15T12:39:12-07:00 2009-03-15T12:39:12-07:00 Add support for Lobbyists, Filings, and Issues ae8adc601948d61ccd8bcad8d908633f78adcc41 Luigi Montanez luigi.montanez@gmail.com