campaign_cash 2.3.2 → 2.4

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2011 The New York Times Company
+Copyright (c) 2012 The New York Times Company
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this library except in compliance with the License.

data/README.rdoc

@@ -8,10 +8,11 @@
 
 == DESCRIPTION:
 
-Simple ruby wrapper for The New York Times Campaign Finance API[http://developer.nytimes.com/docs/read/campaign_finance_api]. You'll need an API key. Tested under Ruby 1.8.7, 1.9.2 and 1.9.3 and JRuby 1.6.7.
+Simple ruby wrapper for portions of The New York Times Campaign Finance API[http://developer.nytimes.com/docs/read/campaign_finance_api]. You'll need an API key. Tested under Ruby 1.8.7, 1.9.2 and 1.9.3 and JRuby 1.6.7.
 
 == News
 
+* July 19, 2012: Version 2.4 released. Updated for new API responses and to return integers and floats.
 * April 10, 2012: Version 2.3.2 released. Bugfix for Committee#find.
 * March 22, 2012: Version 2.3.1 released. Added filing_id to Filing objects and Committee#unamended_filings method.
 * March 15, 2012: Version 2.3 released. Added committee_type to Filing objects and offset to Candidate methods.
@@ -213,6 +214,16 @@ If you're just interested in grabbing the contributions from a certain filing or
      q.date_coverage_to == "2011-12-31".to_date && q.report_title == "YEAR-END"
    end
 
+== Late Contributions
+
+During the final 20 days before a primary or general election, candidate committees that receive contributions of at least $1,000 must report them in filings to the F.E.C. within 48 hours of receipt. These contributions may be from individuals or other committees.
+
+  LateContribution.latest
+  #=> [#<CampaignCash::LateContribution:0x10116c6d0 @contributor_city="Brownsville", @contributor_zip=nil, @fec_committee_id="C00466854", @contributor_fec_id=nil, @fec_candidate_id="H0TN08246", @contributor_employer="Simmco", @transaction_id="20716.C7755", @contributor_street_2=nil, @contributor_prefix=nil, @office_state="TN", @contributor_state="TN", @fec_filing_id=798678, @contributor_street_1="PO Box 545", @contribution_date="2012-07-16", @contributor_last_name="Blurton", @contributor_organization_name=nil, @contributor_middle_name=nil, @contributor_suffix=nil, @contribution_amount="2500.0", @cycle=2012, @contributor_first_name="David", @entity_type="IND", @contributor_occupation="Owner">, ...]
+  
+  LateContribution.candidate("H0TN08246")
+  LateContribution.committee("C00466854") # must be a candidate committee
+
 == Electioneering Communications
 
 Electioneering Communications are broadcast ads funded by third party groups that mention one or more candidates, but don't specifically support or oppose one. <tt>ElectioneeringCommunication</tt> objects are available newest first, or by committee ID or date (all in groups of 20). Within each object is an array of <tt>electioneering_communication_candidates</tt> mentioned in the ad.

data/lib/campaign_cash/base.rb

@@ -6,105 +6,105 @@ require 'ostruct'
 
 module CampaignCash
   class Base
-  	API_SERVER = 'api.nytimes.com'
-  	API_VERSION = 'v3'
-  	API_NAME = 'elections/us'
-  	API_BASE = "/svc/#{API_NAME}/#{API_VERSION}/finances"
-  	CURRENT_CYCLE = 2012
-
-  	@@api_key = nil
-  	@@copyright = nil
-
-  	class << self
-
-  		##
-  		# The copyright footer to be placed at the bottom of any data from the New York Times. Note this is only set after an API call.
-  		def copyright
-  			@@copyright
-  		end
-  		
-  		def cycle
-  		  @@cycle
-  		end
-  		
-  		def base_uri
-  		  @@base_uri
-  		end
-  		
-  		##
-  		# Set the API key used for operations. This needs to be called before any requests against the API. To obtain an API key, go to http://developer.nytimes.com/
-  		def api_key=(key)
-  			@@api_key = key
-  		end
-
-  		def api_key
-  			@@api_key
-  		end
-  		
-  		def date_parser(date)
-  		  date ? Date.strptime(date, '%Y-%m-%d') : nil
-  		end
-  		
-  		def parse_candidate(candidate)
-  		  return nil if candidate.nil?
-  		  candidate.split('/').last.split('.').first
-  		end
-  		
-  		def parse_committee(committee)
-  		  return nil if committee.nil?
-  		  committee.split('/').last.split('.').first
-  		end
-  		
-  		# Returns the election cycle (even-numbered) from a date.
-  		def cycle_from_date(date=Date.today)
-  		  date.year.even? ? date.year : date.year+1
-  		end
-  		
-  		def check_offset(offset)
-  		  raise "Offset must be a multiple of 20" if offset % 20 != 0
-  		end
-
-  		##
-  		# Builds a request URI to call the API server
-  		def build_request_url(path, params)
-  			URI::HTTP.build :host => API_SERVER,
-  											:path => "#{API_BASE}/#{path}.json",
-  											:query => params.map {|k,v| "#{k}=#{v}"}.join('&')
-  		end
-
-  		def invoke(path, params={})
-  			begin
-  				if @@api_key.nil?
-  					raise "You must initialize the API key before you run any API queries"
-  				end
-
-  				full_params = params.merge 'api-key' => @@api_key
-  				full_params.delete_if {|k,v| v.nil?}
-  				
-  				check_offset(params[:offset]) if params[:offset]
-
-  				uri = build_request_url(path, full_params)
-
-  				reply = uri.read
-  				parsed_reply = JSON.parse reply
-
-  				if parsed_reply.nil?
-  					raise "Empty reply returned from API"
-  				end
-
-  				@@copyright = parsed_reply['copyright']
-  				@@cycle = parsed_reply['cycle']
-  				@@base_uri = parsed_reply['base_uri']
-
-  				parsed_reply
-  			rescue OpenURI::HTTPError => e
-  				if e.message =~ /^404/
-  					return nil
-  				end
-
-  				raise "Error connecting to URL #{uri} #{e}"
-  			end
-  		end
-  	end
+    API_SERVER = 'api.nytimes.com'
+    API_VERSION = 'v3'
+    API_NAME = 'elections/us'
+    API_BASE = "/svc/#{API_NAME}/#{API_VERSION}/finances"
+    CURRENT_CYCLE = 2012
+
+    @@api_key = nil
+    @@copyright = nil
+
+    class << self
+
+      ##
+      # The copyright footer to be placed at the bottom of any data from the New York Times. Note this is only set after an API call.
+      def copyright
+        @@copyright
+      end
+
+      def cycle
+        @@cycle
+      end
+
+      def base_uri
+        @@base_uri
+      end
+
+      ##
+      # Set the API key used for operations. This needs to be called before any requests against the API. To obtain an API key, go to http://developer.nytimes.com/
+      def api_key=(key)
+        @@api_key = key
+      end
+
+      def api_key
+        @@api_key
+      end
+
+      def date_parser(date)
+        date ? Date.strptime(date, '%Y-%m-%d') : nil
+      end
+
+      def parse_candidate(candidate)
+        return nil if candidate.nil?
+        candidate.split('/').last.split('.').first
+      end
+
+      def parse_committee(committee)
+        return nil if committee.nil?
+        committee.split('/').last.split('.').first
+      end
+
+      # Returns the election cycle (even-numbered) from a date.
+      def cycle_from_date(date=Date.today)
+        date.year.even? ? date.year : date.year+1
+      end
+
+      def check_offset(offset)
+        raise "Offset must be a multiple of 20" if offset % 20 != 0
+      end
+
+      ##
+      # Builds a request URI to call the API server
+      def build_request_url(path, params)
+        URI::HTTP.build :host => API_SERVER,
+          :path => "#{API_BASE}/#{path}.json",
+        :query => params.map {|k,v| "#{k}=#{v}"}.join('&')
+      end
+
+      def invoke(path, params={})
+        begin
+          if @@api_key.nil?
+            raise "You must initialize the API key before you run any API queries"
+          end
+
+          full_params = params.merge 'api-key' => @@api_key
+          full_params.delete_if {|k,v| v.nil?}
+
+          check_offset(params[:offset]) if params[:offset]
+
+          uri = build_request_url(path, full_params)
+
+          reply = uri.read
+          parsed_reply = JSON.parse reply
+
+          if parsed_reply.nil?
+            raise "Empty reply returned from API"
+          end
+
+          @@copyright = parsed_reply['copyright']
+          @@cycle = parsed_reply['cycle']
+          @@base_uri = parsed_reply['base_uri']
+
+          parsed_reply
+        rescue OpenURI::HTTPError => e
+          if e.message =~ /^404/
+            return nil
+          end
+
+          raise "Error connecting to URL #{uri} #{e}"
+        end
+      end
+    end
   end
 end

data/lib/campaign_cash/candidate.rb

@@ -1,145 +1,145 @@
 module CampaignCash
   class Candidate < Base
-    
+
     # Represents a candidate object based on the FEC's candidate and candidate summary files.
     # A candidate is a person seeking a particular office within a particular two-year election
     # cycle. Each candidate is assigned a unique ID within a cycle.
     attr_reader :name, :id, :state, :district, :party, :fec_uri, :committee_id, 
-                :mailing_city, :mailing_address, :mailing_state, :mailing_zip,
-                :total_receipts, :total_contributions, :total_from_individuals, 
-                :total_from_pacs, :candidate_loans, :total_disbursements,
-                :total_refunds, :debts_owed, :begin_cash, :end_cash, :status,
-                :date_coverage_to, :date_coverage_from, :relative_uri, :office
-    
+      :mailing_city, :mailing_address, :mailing_state, :mailing_zip,
+      :total_receipts, :total_contributions, :total_from_individuals, 
+      :total_from_pacs, :candidate_loans, :total_disbursements,
+      :total_refunds, :debts_owed, :begin_cash, :end_cash, :status,
+      :date_coverage_to, :date_coverage_from, :relative_uri, :office
+
     def initialize(params={})
       params.each_pair do |k,v|
         instance_variable_set("@#{k}", v)
       end
     end
-    
+
     # Creates a new candidate object from a JSON API response.
-		def self.create(params={})
-			self.new :name => params['name'],
-							 :id => params['id'],
-							 :state => parse_state(params['state']),
-							 :office => parse_office(params['id']),
-							 :district => parse_district(params['district']),
-							 :party => params['party'],
-							 :fec_uri => params['fec_uri'],
-							 :committee_id => parse_committee(params['committee']),
-							 :mailing_city => params['mailing_city'],
-							 :mailing_address => params['mailing_address'],
-							 :mailing_state => params['mailing_state'],
-							 :mailing_zip => params['mailing_zip'],
-							 :total_receipts => params['total_receipts'],
-							 :total_contributions => params['total_contributions'],
-							 :total_from_individuals => params['total_from_individuals'],
-							 :total_from_pacs => params['total_from_pacs'],
-							 :candidate_loans => params['candidate_loans'],
-							 :total_disbursements => params['total_disbursements'],
-							 :total_refunds => params['total_refunds'],
-							 :debts_owed => params['debts_owed'],
-							 :begin_cash => params['begin_cash'],
-							 :end_cash => params['end_cash'],
-							 :status => params['status'],
-							 :date_coverage_from => params['date_coverage_from'],
-							 :date_coverage_to => params['date_coverage_to'] 
-		end
-		
-		def self.create_from_search_results(params={})
-		  self.new :name => params['candidate']['name'],
-		           :id => params['candidate']['id'],
-		           :state => params['candidate']['id'][2..3],
-		           :office => parse_office(params['candidate']['id'][0..0]),
-		           :district => parse_district(params['district']),
-		           :party => params['candidate']['party'],
-		           :committee_id => parse_committee(params['committee'])
-		  
-		end
-		
-		def self.parse_state(state)
-		  state.split('/').last[0..1] if state
-		end
-		
-		def self.parse_office(id)
-		  return nil unless id
-		  if id[0..0] == "H"
-		    'house'
-		  elsif id[0..0] == 'S'
-		    'senate'
-		  else
-		    'president'
-		  end
-		end
-		
-		def self.parse_district(uri)
-		  if uri and uri.split('/').last.split('.').first.to_i > 0
-		    uri.split('/').last.split('.').first.to_i
-		  else
-		    0
-		  end
-		end
-		
-		def self.categories
-		  {
-          "individual_total" => "Contributions from individuals",
-          "contribution_total" => "Total contributions",
-          "candidate_loan" => "Loans from candidate",
-          "receipts_total" => "Total receipts",
-          "refund_total" => "Total refunds",
-          "pac_total" => "Contributions from PACs",
-          "disbursements_total" => "Total disbursements",
-          "end_cash" => "Cash on hand",
-          "debts_owed" => "Debts owed by",
+    def self.create(params={})
+      self.new :name => params['name'],
+        :id => params['id'],
+        :state => parse_state(params['state']),
+        :office => parse_office(params['id']),
+        :district => parse_district(params['district']),
+        :party => params['party'],
+        :fec_uri => params['fec_uri'],
+        :committee_id => parse_committee(params['committee']),
+        :mailing_city => params['mailing_city'],
+        :mailing_address => params['mailing_address'],
+        :mailing_state => params['mailing_state'],
+        :mailing_zip => params['mailing_zip'],
+        :total_receipts => params['total_receipts'].to_f,
+        :total_contributions => params['total_contributions'].to_f,
+        :total_from_individuals => params['total_from_individuals'].to_f,
+        :total_from_pacs => params['total_from_pacs'].to_f,
+        :candidate_loans => params['candidate_loans'].to_f,
+        :total_disbursements => params['total_disbursements'].to_f,
+        :total_refunds => params['total_refunds'].to_f,
+        :debts_owed => params['debts_owed'].to_f,
+        :begin_cash => params['begin_cash'].to_f,
+        :end_cash => params['end_cash'].to_f,
+        :status => params['status'],
+        :date_coverage_from => params['date_coverage_from'],
+        :date_coverage_to => params['date_coverage_to'] 
+    end
+
+    def self.create_from_search_results(params={})
+      self.new :name => params['candidate']['name'],
+        :id => params['candidate']['id'],
+        :state => params['candidate']['id'][2..3],
+        :office => parse_office(params['candidate']['id'][0..0]),
+        :district => parse_district(params['district']),
+        :party => params['candidate']['party'],
+        :committee_id => parse_committee(params['committee'])
+
+    end
+
+    def self.parse_state(state)
+      state.split('/').last[0..1] if state
+    end
+
+    def self.parse_office(id)
+      return nil unless id
+      if id[0..0] == "H"
+        'house'
+      elsif id[0..0] == 'S'
+        'senate'
+      else
+        'president'
+      end
+    end
+
+    def self.parse_district(uri)
+      if uri and uri.split('/').last.split('.').first.to_i > 0
+        uri.split('/').last.split('.').first.to_i
+      else
+        0
+      end
+    end
+
+    def self.categories
+      {
+        "individual_total" => "Contributions from individuals",
+        "contribution_total" => "Total contributions",
+        "candidate_loan" => "Loans from candidate",
+        "receipts_total" => "Total receipts",
+        "refund_total" => "Total refunds",
+        "pac_total" => "Contributions from PACs",
+        "disbursements_total" => "Total disbursements",
+        "end_cash" => "Cash on hand",
+        "debts_owed" => "Debts owed by",
       }
-		end
-		
-		# Retrieve a candidate object via its FEC candidate id within a cycle.
-		# Defaults to the current cycle.
+    end
+
+    # Retrieve a candidate object via its FEC candidate id within a cycle.
+    # Defaults to the current cycle.
     def self.find(fecid, cycle=CURRENT_CYCLE)
-			reply = invoke("#{cycle}/candidates/#{fecid}")
-			result = reply['results']
-			self.create(result.first) if result.first
+      reply = invoke("#{cycle}/candidates/#{fecid}")
+        result = reply['results']
+      self.create(result.first) if result.first
     end
-    
+
     # Returns leading candidates for given categories from campaign filings within a cycle.
     # See [the API docs](http://developer.nytimes.com/docs/read/campaign_finance_api#h3-candidate-leaders) for
     # a list of acceptable categories to pass in. Defaults to the current cycle.
     def self.leaders(category, cycle=CURRENT_CYCLE)
-			reply = invoke("#{cycle}/candidates/leaders/#{category}",{})
-			results = reply['results']
+      reply = invoke("#{cycle}/candidates/leaders/#{category}",{})
+        results = reply['results']
       results.map{|c| self.create(c)}
     end
-    
+
     # Returns an array of candidates matching a search term within a cycle. Defaults to the
     # current cycle.
     def self.search(name, cycle=CURRENT_CYCLE, offset=nil)
-			reply = invoke("#{cycle}/candidates/search", {:query => name, :offset => offset})
-			results = reply['results']      
+      reply = invoke("#{cycle}/candidates/search", {:query => name, :offset => offset})
+      results = reply['results']      
       results.map{|c| self.create_from_search_results(c)}
     end
-    
+
     # Returns an array of newly created FEC candidates within a current cycle. Defaults to the
     # current cycle.
     def self.new_candidates(cycle=CURRENT_CYCLE, offset=nil)
-			reply = invoke("#{cycle}/candidates/new",{:offset => offset})
-			results = reply['results']
+      reply = invoke("#{cycle}/candidates/new",{:offset => offset})
+      results = reply['results']
       results.map{|c| self.create(c)}      
     end
-    
+
     # Returns an array of candidates for a given state within a cycle, with optional chamber and
     # district parameters. For example, House candidates from New York. Defaults to the current cycle.
     def self.state(state, chamber=nil, district=nil, cycle=CURRENT_CYCLE, offset=nil)
       path = "#{cycle}/seats/#{state}"
-      if chamber
-        path += "/#{chamber}"
-        path += "/#{district}" if district
-      end
+        if chamber
+          path += "/#{chamber}"
+            path += "/#{district}" if district
+        end
       reply = invoke(path,{:offset => offset})
       results = reply['results']
       results.map{|c| self.create_from_search_results(c)}      
     end
-    
+
     instance_eval { alias :state_chamber :state }
   end
 end