campaign_cash

____                            _                ____          _

/ | _ _ __ ___ _ __ __ () __ _ _ __ / | _ | | | | / | '_ _ | ' \ / | |/ _ | ' \ | | / ` / | '
| |__| (| | | | | | | |) | (| | | (| | | | | | |__| (| __ \ | | | __,|| || || ./ _,||_, || || __,|/| || || |__/

== DESCRIPTION:

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.9.3, 2.0.0 and 2.1.0.

== News

• Sept. 14, 2015: Version 2.9.2 released. Bug fix for Filing#today.
• July 28, 2015: Version 2.9.1 released. Patch for Committee#filings
• July 24, 2015: Version 2.9 released. Made Filing#search cycle-specific.
• June 15, 2015: Version 2.8.1 released. Bumped cycle to 2016 and fixed tests.
• Dec. 16, 2014: Version 2.8 released. Added Filing#search method to support name or id searches.
• Dec. 15, 2014: Version 2.7.2 released. Added date_filed to Filing objects.
• May 23, 2014: Version 2.7.1 released. Fixed Committee#search (thanks @alshaw!).
• March 3, 2014: Version 2.7 released. Updated for Ruby 2.x support, dropped support for 1.8.7.
• July 22, 2013: Version 2.6.2 released. Changed current cycle to 2014.
• April 10, 2013: Version 2.6.1 released. Fixed bad attribute name for Filing#filing_id.
• April 9, 2013: Version 2.6 released. Added missing attribute accessors to Filing objects.
• April 9, 2013: Version 2.5.1 released. Fixed a bug that showed committee_name in Filing objects as nil.
• Nov. 13, 2012: Version 2.5 released. Fixes a bug in Filing object attribute assignment.
• 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.
• March 9, 2012: Version 2.2.1 released. Added transfers_in attribute to President#detail.
• Feb. 8, 2012: Version 2.1.0 released. Added better support for independent expenditures and FilingSummary class for presidential candidate filings.
• Jan. 28, 2012: Version 2.0.8 released. Bugfix for Candidate#search. Thanks to @benjaminjackson for patch.
• Jan. 24, 2012: Version 2.0.7 released. Added candidate_name attribute accessor to IndependentExpenditure objects.
• Jan. 19, 2012: Version 2.0.6 released. Added transaction_id param to IndependentExpenditure objects.
• Jan. 19, 2012: Version 2.0.5 released. Bugfix to add amendment param to IndependentExpenditure objects.

== INSTALL:

Install Campaign Cash as a gem:

gem install campaign_cash

For use in a Rails 3 application, put the following in your Gemfile:

gem 'campaign_cash'

then issue the 'bundle install' command. Campaign Cash has been tested under Ruby 1.8.7 and 1.9.2.

== GETTING STARTED:

require 'rubygems' require 'campaign_cash'

You'll want to set your API key as an environment variable in order to run the tests. Otherwise, you'll need to set it like so:

include CampaignCash Base.api_key = YOUR_API_KEY

In a Rails app, you can put those lines in a file in config/initializers/.

Currently there are methods to support retrieving candidates, presidential candidates, committees, electronic filings, committee contributions and independent expenditures. Almost every method requires at least one parameter, the election cycle.

== Candidates

Candidate objects can be created in several ways. To locate a candidate by last name, supply the name and cycle:

Candidate.search("Bass", 2012) #=> [#<CampaignCash::Candidate:0x101bb3d00 @name="BASS, CHARLES F.", @state="NH", @party="REP", @district=2, @committee_id="C00302570", @office="house", @id="H0NH02017">, #<CampaignCash::Candidate:0x101bb2f90 @name="BASS, KAREN", @state="CA", @party="DEM", @district=33, @committee_id="C00476523", @office="house", @id="H0CA33117">]

Search returns an array of basic information about candidates, including the unique Federal Election Commission-provided identifier, which begins with an "H" for House candidates, "S" for Senate candidates and "P" for presidential candidates. The id, along with the election cycle, can be used to retrieve more information about a candidate:

Candidate.find("H0NH02017", 2012) #=> #<CampaignCash::Candidate:0x101b9af80 @name="BASS, CHARLES F.", @state="NH", @fec_uri="http://query.nictusa.com/cgi-bin/fecimg/?H0NH02017", @total_disbursements=120650.0, @total_contributions=570853.0, @mailing_address="PO BOX 210", @begin_cash=31676.0, @party="REP", @candidate_loans=nil, @total_receipts=577512.0, @date_coverage_from="2011-01-01", @mailing_city="PETERBOROUGH", @debts_owed=nil, @district=2, @total_from_pacs=414250.0, @mailing_zip="03458", @date_coverage_to="2011-09-30", @committee_id="C00302570", @total_refunds=nil, @office="house", @total_from_individuals=156603.0, @id="H0NH02017", @mailing_state="NH", @end_cash=488538.0, @status="I">

Candidate.find returns an object containing more detailed information for a candidate, including the latest financial summary from the F.E.C. and the candidate's committee ID, which can be used to make other method calls.

Several other canned queries are available. To list the top 20 candidates in terms of one of the financial categories (available by calling Candidate.categories or listed at http://developer.nytimes.com/docs/read/campaign_finance_api#h3-candidate-leaders), supply the category and cycle:

Candidate.leaders('end-cash', 2012) #=> [#<CampaignCash::Candidate:0x101b76b80 @name="OBAMA, BARACK", @state=nil, @fec_uri=nil, @total_disbursements=29327600.0, @total_contributions=65393200.0, @mailing_address=nil, @begin_cash=2303400.0, @party="DEM", @candidate_loans=nil, @total_receipts=nil, @date_coverage_from="2011-01-01", @mailing_city=nil, @debts_owed=1709300.0, @district=0, @total_from_pacs=nil, @mailing_zip=nil, @date_coverage_to="2011-09-30", @committee_id="C00430892", @total_refunds=944100.0, @office=nil, @total_from_individuals=65393200.0, @id=nil, @mailing_state=nil, @end_cash=61400700.0, @status="I">, #<CampaignCash::Candidate:0x101b75730 @name="SHELBY, RICHARD C", @state="AL", @fec_uri=nil, @total_disbursements=1508100.0, @total_contributions=4693320.0, @mailing_address=nil, @begin_cash=13381000.0, @party="REP", @candidate_loans=nil, @total_receipts=nil, @date_coverage_from="2009-01-01", @mailing_city=nil, @debts_owed=nil, @district=0, @total_from_pacs=1671200.0, @mailing_zip=nil, @date_coverage_to="2010-12-31", @committee_id="C00193623", @total_refunds=25800.0, @office=nil, @total_from_individuals=3022120.0, @id=nil, @mailing_state=nil, @end_cash=17156600.0, @status="I"> ...]

Please note that not all candidates file on the same schedule, so some of the "date_coverage_to" will be different for these responses. Senate candidates, in particular, often file twice a year during the odd-numbered years prior to a general election.

To retrieve an array of the 20 newest candidates (the F.E.C.'s data is updated every Monday), use the new_candidates class method:

Candidate.new_candidates #=> [#<CampaignCash::Candidate:0x101b11d20 @name="ANDERSON, JASON EDWARD", @state="AL", @fec_uri="http://query.nictusa.com/cgi-bin/fecimg/?H2AL05086", @total_disbursements=nil, @total_contributions=nil, @mailing_address=nil, @begin_cash=nil, @party="REP", @candidate_loans=nil, @total_receipts=nil, @date_coverage_from=nil, @mailing_city="HAZEL GREEN", @debts_owed=nil, @district=5, @total_from_pacs=nil, @mailing_zip="35750", @date_coverage_to=nil, @committee_id="C00508374", @total_refunds=nil, @office="house", @total_from_individuals=nil, @id="H2AL05086", @mailing_state="AL", @end_cash=nil, @status=nil>, #<CampaignCash::Candidate:0x101b10420 @name="NORRIS, PHILLIP DWIGHT", @state="AL", @fec_uri="http://query.nictusa.com/cgi-bin/fecimg/?H2AL07165", @total_disbursements=nil, @total_contributions=nil, @mailing_address=nil, @begin_cash=nil, @party="REP", @candidate_loans=nil, @total_receipts=nil, @date_coverage_from=nil, @mailing_city="HOOVER", @debts_owed=nil, @district=7, @total_from_pacs=nil, @mailing_zip="35216", @date_coverage_to=nil, @committee_id="C00508382", @total_refunds=nil, @office="house", @total_from_individuals=nil, @id="H2AL07165", @mailing_state="AL", @end_cash=nil, @status=nil>,

To retrieve an array of candidates for a particular seat, supply a state abbreviation, chamber ('house' or 'senate'), district (an integer or nil) and cycle. For example, the following asks for candidates for Maryland's 6th Congressional District in 2012:

Candidate.state_chamber('MD', 'house', 6, 2012) #=> [#<CampaignCash::Candidate:0x101abea58 @name="CLARK, CASEY", @state="MD", @party="DEM", @district=0, @committee_id="C00460436", @office="house", @id="H0MD06173">, #<CampaignCash::Candidate:0x101abe2b0 @name="TAYLOR, STEVEN MICHAEL", @state="MD", @party="REP", @district=0, @committee_id="C00481788", @office="house", @id="H0MD06181">, #<CampaignCash::Candidate:0x101abdb08 @name="BARTLETT, ROSCOE G. REP.", @state="MD", @party="REP", @district=0, @committee_id="C00255190", @office="house", @id="H2MD06054">,...]

== President

Presidential candidate objects are like regular Candidates, except that they have additional financial attributes that are calculated by The New York Times from electronic filings. There are two President methods. To retrieve a listing of all presidential candidates being tracked by The Times:

President.summary #=> [#<CampaignCash::President:0x101be6c78 @name="Barack Obama", @party="D", @total_receipts="99597680.72", @date_coverage_from="2011-01-01", @date_coverage_to="2011-09-30", @committee_id="C00431445", @id="P80003338", @end_cash="61403710.55", @total_disbursements="106877585.73">, #<CampaignCash::President:0x101be6688 @name="Mitt Romney", @party="R", @total_receipts="32605827.32", @date_coverage_from="2010-10-01", @date_coverage_to="2011-09-30", @committee_id="C00431171", @id="P80003353", @end_cash="14656965.83", @total_disbursements="17953283.44">,...]

To retrieve detailed information for a single presidential candidate, pass the appropriate committee_id and cycle:

President.detail('C00431171', 2012) #=> [#<CampaignCash::President:0x101bd3d58 @name="Romney, Mitt", @party="R", @contributions_less_than_200="3393540.5", @total_receipts="32605827.32", @date_coverage_from="2010-10-01", @net_candidate_contributions="0.0", @contributions_1500_2499="1566753.77", @federal_funds="0.0", @date_coverage_to="2011-09-30", @net_party_contributions="0.0", @committee_id="C00431171", @total_refunds="270101.47", @contributions_500_1499="5965455.03", @net_general_contributions="0.0", @id="P80003353", @end_cash="14656965.83", @net_pac_contributions="177301.13", @total_disbursements="17953283.44", @contributions_200_499="977647.0", @total_contributions="32482490.51", @net_primary_contributions="14656965.83", @net_individual_contributions="32035087.91", @contributions_max="19930000.0">]

Among the calculated attributes are totals for five ranges of contribution size (the maximum individual contribution for the 2012 cycle is $2,500 per person, per election, while in 2008 it was $2,300).

== Committees

Committee objects have information about F.E.C.-registered committees that may or may not be affiliated to a candidate. If a committee is associated with a candidate, it will have values for the district, party and candidate_id attributes. Party committees should also have the party attribute set. If it is defined as a leadership committee, a committee's leadership attribute will be set to True; a similar attribute, super_pac, is set to True if the committee is registered with the F.E.C. as a "Super PAC" able to raise unlimited amounts for independent expenditures.

Searching for a committee currently executes a "begins with" query, so to find all committees in the 2012 cycle that start with the word 'Growth':

Committee.search("Growth", 2012) #=> [#<CampaignCash::Committee:0x101bebb38 @name="GROWTH AND PROSPERITY POLITICAL ACTION COMMITTEE", @state="AL", @party="", @super_pac=nil, @leadership=true, @district=nil, @city="BIRMINGHAM", @id="C00388793", @treasurer="DOBBS, JOEY", @fec_uri="http://query.nictusa.com/cgi-bin/dcdev/forms/C00388793/", @zip="35222", @candidate_id=nil>, #<CampaignCash::Committee:0x101beb368 @name="GROWTH ENERGY PAC", @state="DC", @party="", @super_pac=nil, @leadership=false, @district=nil, @city="WASHINGTON", @id="C00475665", @treasurer="BUTTERFIELD, BEN", @fec_uri="http://query.nictusa.com/cgi-bin/dcdev/forms/C00475665/", @zip="20002", @candidate_id=nil>]

As with Candidate.search, the results of Committee.search return a subset of all Committee attributes. The full Committee object includes the most recent financial summary data available, plus the other election cycles that the committee is registered in dating back to 1980. Some committees have a sponsor, which could be a corporation, association or candidate. Also included are several F.E.C.-defined categories, including filing frequency, committee designation (who controls it, essentially), committee type (House, Senate, etc.) and interest group category (corporation, labor union, etc.). These last four attributes are not universally present in the data, which is why a Committee object has an independent leadership attribute even though the designation should indicate if it is a leadership committee. More details these codes is available from the F.E.C.: ftp://ftp.fec.gov/FEC/cm_dictionary.txt.

To fetch the details for a single committee in a cycle:

Committee.find("C00326389", 2012) #=> #<CampaignCash::Committee:0x101bd4118 @name="SNAKE RIVER SUGAR COMPANY POLITICAL ACTION COMMITTEE", @state="ID", @party="", @candidate_loans=nil, @total_receipts=30363.3, @date_coverage_from="2011-01-01", @designation="Unauthorized", @other_cycles=[2010, 2008, 2006, 2004, 2002, 2000, 1998], @city="BOISE", @debts_owed=nil, @total_from_pacs=nil, @date_coverage_to="2011-11-30", @filing_frequency="Monthly", @sponsor_name=nil, @total_refunds=nil, @total_from_individuals=30363.3, @id="C00326389", @leadership=false, @zip="83709", @end_cash=16845.2, @committee_type=nil, @fec_uri="http://query.nictusa.com/cgi-bin/dcdev/forms/C00326389/", @total_disbursements=46500.0, @total_contributions=30363.3, @interest_group="Cooperative", @super_pac=false, @address="1951 SOUTH SATURN WAY", @begin_cash=32981.9, @candidate_id=nil>

Individual Committee objects can retrieve an array of filings they have made during a given cycle:

committee = Committee.find("C00326389", 2012) committee.filings #=> [#<CampaignCash::Filing:0x101bc9100 @amended_uri=nil, @paper=false, @amended=false, @committee_name=nil, @date_coverage_from=#<Date: 4911793/2,0,2299161>, @original_uri=nil, @report_title="YEAR-END", @date_coverage_to=#<Date: 4911853/2,0,2299161>, @form_type="F3", @committee=nil, @original_filing=nil, @fec_uri="http://query.nictusa.com/cgi-bin/dcdev/forms/C00326389/756540/">,...]

The filings method returns an array of all filings, including originals and amendments. If you want to retrieve the list of unamended filings for a committee within a cycle -- in other words, the latest version of reports -- use the unamended_filings method:

committee = Committee.find("C00326389", 2012) committee.unamended_filings

For more information on Filing objects, see Filings below.

To retrieve a list of the 20 most recently added committees (note that no cycle parameter is needed; this method always uses the most recent cycle):

Committee.latest #=> [#<CampaignCash::Committee:0x101be6020 @name="AMERICA'S IMPACT POLITICAL FUND", @state="DC", @party="", @super_pac=false, @leadership=false, @district=nil, @city="WASHINGTON", @id="C00508366", @treasurer="BENJAMIN GOLDSMITH", @fec_uri="http://query.nictusa.com/cgi-bin/dcdev/forms/C00508366/", @zip="20005", @candidate_id=nil>, #<CampaignCash::Committee:0x101be55a8 @name="JASON ANDERSON FOR CONGRESS", @state="AL", @party="REP", @super_pac=false, @leadership=false, @district=nil, @city="HAZEL GREEN", @id="C00508374", @treasurer="CHRISTOPHER MARK ANDREWS", @fec_uri="http://query.nictusa.com/cgi-bin/dcdev/forms/C00508374/", @zip="35750", @candidate_id="H2AL05086">, ...]

"Super PACs" are independent-expenditure only committees formed in the wake of the 2010 Citizens United decision by the U.S. Supreme Court. They can raise money in unlimited donations from individuals, corporations, labor unions and other sources, but must register their intent to do so with the F.E.C. To retrieve the 20 most recent "Super PAC" registrations:

Committee.superpacs #=> [#<CampaignCash::Committee:0x101bcfe10 @name="HUMAN RIGHTS CAMPAIGN EQUALITY VOTES", @state="DC", @party="", @designation="Unauthorized", @city="WASHINGTON", @treasurer="JAMES M RINEFIERD", @district=nil, @filing_frequency="Quarterly", @id="C00508440", @leadership=false, @zip="20036", @committee_type=nil, @fec_uri="http://query.nictusa.com/cgi-bin/dcdev/forms/C00508440/", @interest_group=nil, @super_pac=true, @candidate_id=nil>, #<CampaignCash::Committee:0x101bcf348 @name="LEADERS FOR FAMILIES SUPER PAC INC", @state="IN", @party="", @designation="Unauthorized", @city="TERRE HAUTE", @treasurer="CHARLES HURLEY", @district=nil, @filing_frequency="Quarterly", @id="C00508317", @leadership=false, @zip="47807", @committee_type=nil, @fec_uri="http://query.nictusa.com/cgi-bin/dcdev/forms/C00508317/", @interest_group=nil, @super_pac=true, @candidate_id=nil>,...]

Committees make contributions to candidates, among other activities. Given a committee, cycle and recipient candidate, to see any contributions from the committee to the candidate:

Contribution.find('C00388793',2012,'H0NY19139') #=> #<CampaignCash::Contribution:0x101b6af60 @results=[#<OpenStruct party="REP", date=#<Date: 4911301/2,0,2299161>, primary_general="General", state="NY", amount=5000.0, image_uri="http://images.nictusa.com/cgi-bin/fecimg/?11932087309", name="HAYWORTH, NAN", district="19", candidate="H0NY19139">, #<OpenStruct party="REP", date=#<Date: 4911289/2,0,2299161>, primary_general="Primary", state="NY", amount=5000.0, image_uri="http://images.nictusa.com/cgi-bin/fecimg/?11932087308", name="HAYWORTH, NAN", district="19", candidate="H0NY19139">], @cycle=2012, @total_amount=10000.0, @committee="C00388793">

Removing the candidate's id from the previous method will yield an array of all contributions to candidates made by the committee during that cycle:

Contribution.find('C00388793',2012) #=> #<CampaignCash::Contribution:0x101b8c098 @results=[#<OpenStruct party="REP", date=#<Date: 4911479/2,0,2299161>, primary_general="Primary", state="IL", amount=2000.0, image_uri="http://images.nictusa.com/cgi-bin/fecimg/?11932087311", name="KINZINGER, ADAM", district="11", candidate=nil>, #<OpenStruct party="REP", date=#<Date: 4911471/2,0,2299161>, primary_general="Primary", state="MI", amount=2500.0, image_uri="http://images.nictusa.com/cgi-bin/fecimg/?11932087316", name="WALBERG, TIMOTHY L. HON.", district="07", candidate=nil>,...]

Both of the contribution responses have a results method that contains one or more contributions, assembled using Ruby's OpenStruct library. The image_uri attribute is a link to the page of the filing on fec.gov that contains that transaction.

== Filings

Committees file reports with the F.E.C. detailing their fundraising and expenditures, as well as administrative matters such as a change of address or in committee status. Campaign Cash provides access to both electronic filings, the method used by most committees, and images of paper filings, which are submitted by Senate candidates and two Senate party committees. To retrieve the most recent 20 filings from today:

Filing.today #=> [#<CampaignCash::Filing:0x101be03a0 @original_uri="http://query.nictusa.com/cgi-bin/dcdev/forms/C00016899/741687/", @amended_uri=nil, @amended=false, @committee_name="OHIO DEMOCRATIC PARTY", @date_coverage_from=#<Date: 4911487/2,0,2299161>, @original_filing=741687, @report_title="AUG MONTHLY", @date_coverage_to=#<Date: 4911547/2,0,2299161>, @form_type="F3", @committee="C00016899", @paper=nil, @fec_uri="http://query.nictusa.com/cgi-bin/dcdev/forms/C00016899/756832/">, #<CampaignCash::Filing:0x101bd9eb0 @original_uri=nil, @amended_uri=nil, @amended=false, @committee_name="CITIZENS FOR PAUL FEINER", @date_coverage_from=#<Date: 4911671/2,0,2299161>, @original_filing=nil, @report_title="YEAR-END", @date_coverage_to=#<Date: 4911853/2,0,2299161>, @form_type="F3", @committee="C00332411", @paper=nil, @fec_uri="http://query.nictusa.com/cgi-bin/dcdev/forms/C00332411/756831/">,...]

Each filing object contains several attributes that help place it into context. If the filing is amended by another filing, amended will be True and an amended_uri, the link to the updated filing, will appear. If a filing was submitted on paper, paper will be True. To retrieve filings from a specific date:

Filing.date(2012,1,9) # Jan. 9, 2012 #=> [#<CampaignCash::Filing:0x101aa5e68 @original_uri=nil, @amended_uri=nil, @amended=false, @committee_name="HOYT HILSMAN FOR CONGRESS", @date_coverage_from=#<Date: 4911671/2,0,2299161>, @original_filing=nil, @report_title="YEAR-END", @date_coverage_to=#<Date: 4911853/2,0,2299161>, @form_type="F3", @committee="C00435966", @paper=nil, @fec_uri="http://query.nictusa.com/cgi-bin/dcdev/forms/C00435966/756828/">, #<CampaignCash::Filing:0x101a9f978 @original_uri=nil, @amended_uri=nil, @amended=false, @committee_name="MARY PALLANT FOR CONGRESS", @date_coverage_from=#<Date: 4911671/2,0,2299161>, @original_filing=nil, @report_title="YEAR-END", @date_coverage_to=#<Date: 4911853/2,0,2299161>, @form_type="F3", @committee="C00415943", @paper=nil, @fec_uri="http://query.nictusa.com/cgi-bin/dcdev/forms/C00415943/756827/">,...]

To retrieve a list of Filing form types, which explain a little more about the form_type attributes on Filing objects:

Filing.form_types #=> [#<OpenStruct name="STATEMENT OF ORGANIZATION", id="F1">, #<OpenStruct name="24-HOUR NOTICE OF EXPENDITURES FROM CANDIDATE PERSONAL FUNDS", id="F10">, #<OpenStruct name="24-HOUR NOTICE OF EXPENDITURES FROM OPPONENT'S PERSONAL FUNDS", id="F11">, #<OpenStruct name="24-HOUR NOTICE OF SUSPENSION OF INDIVIDUAL CONTRIBUTION LIMITS", id="F12">,...]

The form type IDs can be used to retrieve the most recent filings of that type:

Filing.by_type(2012,'F1') # Latest Statements of Organization #=> [#<CampaignCash::Filing:0x101c5fee8 @original_uri=nil, @amended_uri=nil, @amended=false, @committee_name="DUNCAN D. HUNTER FOR CONGRESS", @date_coverage_from=nil, @original_filing=nil, @report_title="STATEMENT OF ORGANIZATION", @date_coverage_to=nil, @form_type=nil, @committee="C00433524", @paper=nil, @fec_uri="http://query.nictusa.com/cgi-bin/dcdev/forms/C00433524/756824/">, #<CampaignCash::Filing:0x101c5f448 @original_uri=nil, @amended_uri=nil, @amended=false, @committee_name="THE BILL KEATING COMMITTEE", @date_coverage_from=nil, @original_filing=nil, @report_title="STATEMENT OF ORGANIZATION", @date_coverage_to=nil, @form_type=nil, @committee="C00479063", @paper=nil, @fec_uri="http://query.nictusa.com/cgi-bin/dcdev/forms/C00479063/756813/">,...]

All Filing methods, with the exception of Filing.form_types, support the optional offset parameter, using multiples of 20.

== Independent Expenditures

Committees can spend money to elect or defeat candidates independently of their campaigns; such activities are called independent expenditures and are {specifically reported to the F.E.C.}[http://www.fec.gov/finance/disclosure/ie_reports.shtml]. To retrieve the 20 most recent IE transactions:

IndependentExpenditure.latest #=> [#<CampaignCash::IndependentExpenditure:0x101bd3920 @date_received=#<Date: 4911871/2,0,2299161>, @amount=200.0, @purpose="Online Advertising - 01/08/2012", @committee="C00503789", @district=0, @date=#<Date: 4911869/2,0,2299161>, @candidate="P20002721", @support_or_oppose="O", @committee_name="DGA ACTION", @office="President", @payee="Facebook", @state="", @fec_uri="http://images.nictusa.com/cgi-bin/fecimg/?12950041238">,...]

The support_or_oppose attribute contains either an "S" (for "Support") or "O" (for "Oppose"), indicating whether the expenditure is in favor or against the candidate identified. IEs should contain both the candidate mentioned in the expenditure and the office (state and district) that person is running for, but in practice some filings either omit this information or contain an incorrect candidate ID (usually a previous one for the correct candidate). The API does not guarantee that such mistakes will be corrected when you retrieve records. To retrieve recent IEs about a specific candidate, use that candidate's ID:

IndependentExpenditure.candidate("P60003654", 2012) # find independent expenditures about Newt Gingrich. #=> [#<CampaignCash::IndependentExpenditure:0x101bd8470 @date_received=#<Date: 4911865/2,0,2299161>, @amount=89961.8, @purpose="Direct Mail", @committee="C00490045", @district=0, @committee_name="RESTORE OUR FUTURE, INC.", @date=#<Date: 4911861/2,0,2299161>, @candidate="P60003654", @support_or_oppose="O", @office="President", @payee="Arena Communications", @state="FL", @fec_uri="http://images.nictusa.com/cgi-bin/fecimg/?12950036002">, #<CampaignCash::IndependentExpenditure:0x101bd1c38 @date_received=#<Date: 4911861/2,0,2299161>, @amount=108982.0, @purpose="National Email Communication and Production", @committee="C00507525", @district=0, @committee_name="WINNING OUR FUTURE", @date=#<Date: 4911859/2,0,2299161>, @candidate="P60003654", @support_or_oppose="S", @office="President", @payee="Marketel Media, Inc.", @state="", @fec_uri="http://images.nictusa.com/cgi-bin/fecimg/?12970039675">,...]

To retrieve IEs by date, use a string date in MM/DD/YYYY format:

IndependentExpenditure.date('12/28/2011') #=> #<CampaignCash::IndependentExpenditure:0x101a41968 @date_received=#<Date: 4911849/2,0,2299161>, @amount=19210.0, @purpose="TV Ad", @committee="C00508317", @district=0, @date=#<Date: 4911847/2,0,2299161>, @candidate="P20002721", @support_or_oppose="S", @committee_name="Leaders for Families Super PAC, Inc.", @office="President", @payee="NCC Media", @state="", @fec_uri="http://images.nictusa.com/cgi-bin/fecimg/?11953345841">, #<CampaignCash::IndependentExpenditure:0x101a3b130 @date_received=#<Date: 4911849/2,0,2299161>, @amount=10450.0, @purpose="TV Ad", @committee="C00508317", @district=0, @date=#<Date: 4911847/2,0,2299161>, @candidate="P20002721", @support_or_oppose="S", @committee_name="Leaders for Families Super PAC, Inc.", @office="President", @payee="WHO", @state="", @fec_uri="http://images.nictusa.com/cgi-bin/fecimg/?11953345842">,...]

Another way to fetch IEs is by the committee that paid for them, using the committee ID:

IndependentExpenditure.committee('C00508317', 2012) #=> [#<CampaignCash::IndependentExpenditure:0x1019c5638 @date_received=#<Date: 4911865/2,0,2299161>, @amount=4235.0, @purpose="Radio Ad Buy", @committee="C00508317", @district=0, @date=#<Date: 4911865/2,0,2299161>, @candidate="P20002721", @support_or_oppose="S", @committee_name="Leaders for Families Super PAC, Inc.", @office="President", @payee="WGIR-FM & WQSO-FM", @state="NH", @fec_uri="http://images.nictusa.com/cgi-bin/fecimg/?12950035907">,...]

There's also the option to retrieve the 20 most recent IEs for the presidential race:

IndependentExpenditure.president #=> [#<CampaignCash::IndependentExpenditure:0x10192a728 @date_received=#<Date: 4911855/2,0,2299161>, @amount=350.0, @purpose="Font Purchase", @committee="C00508002", @district=0, @date=#<Date: 4911915/2,0,2299161>, @candidate="", @support_or_oppose="S", @committee_name="ENDORSE LIBERTY INC", @office="President", @payee="Commercial Type", @state="", @fec_uri="http://images.nictusa.com/cgi-bin/fecimg/?12970010100">,...]

The IE responses also accept an optional offset argument, using multiples of 20.

== Individual Contributions

IndividualContribution objects are line items from committees' receipt filings. You can get them in three ways, by an FEC committee ID, a filing ID or an FEC candidate ID in groups of 20. These will be returned from newest to oldest. Note: in IndividualContribution responses, pac_name refers to any institutional donation, not just donations from other PACs.

IndividualContribution.committee("C00490045") # Restore Our Future #=> [#<CampaignCash::IndividualContribution:0x102fd3948 @display_name=nil, @fec_form_type=nil, @aggregate_amount=100000.0, @zip="94129", @zip5="94129", @state="CA", @middle_name=nil, @conduit_state=nil, @conduit_address_one=nil, @conduit_name=nil, @memo_code=nil, @last_name=nil, @candidate_id=nil, @back_ref_sched_name=nil, @conduit_zip=nil, @committee_id=133, @suffix=nil, @donor_cmte_id=nil, @flag_orgind="ORG", @back_ref_tran_id=nil, @city="San Francisco", @amended_cd=nil, @donor_district=nil, @id=4571002, @exclude=nil, @donor_candidate=nil, @prigen=nil, @donor_cand_id=nil, @donor_office=nil, @occupation=nil, @tran_id="SA11AI.4427", @lng=nil, @prefix=nil, @memo_text=nil, @lat=nil, @employer=nil, @pac_name="Wendt Family Trust", @amount=100000.0, @increased_limit=nil, @transaction_description=nil, @donor_state=nil, @date="2011-12-31", @filing_id=764828, @system_code=nil, @first_name=nil, @address_one="1 Muir Loop", @transaction_type=nil, @conduit_city=nil, @linenumber="SA11AI", @full_name=nil, @address_two=nil, @conduit_address_two=nil>, ...]

IndividualContribution.candidate("P80003338") # Barack Obama IndividualContribution.filing(762683) # Obama for America's 2011 year-end filing

If you're just interested in grabbing the contributions from a certain filing or date-range, but don't know that filing ID, get it via Committee#filings. Here's how to find the 2011 year-end filing ID for Restore Our Future, which you can then pass to IndividualContributions.

Committee.find("C00490045", 2012).filings.select do |q| 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. ElectioneeringCommunication objects are available newest first, or by committee ID or date (all in groups of 20). Within each object is an array of electioneering_communication_candidates mentioned in the ad.

ElectioneeringCommunication.latest #=> [#<CampaignCash::ElectioneeringCommunication:0x10370a180 @payee_suffix=nil, @cycle=2012, @communication_date="2012-02-06", @committee_name="Crossroads Grassroots Policy Strategies", @purpose="TV/Media Production (Every Level)", @payee_address_2=nil, @electioneering_communication_candidates=[{"candidate_state"=>"HI", "electioneering_communication_id"=>847, "filing_id"=>764901, "transaction_id"=>"C.", "amended_from"=>nil, "back_reference_tran_id_number"=>"E.1", "candidate_name"=>"OBAMA, BARACK", "fec_candidate_id"=>"P80003338", "candidate_district"=>nil}], @back_reference_tran_id_number=nil, @unique_id="1116aadc5d5b7c793f0d0adfebb503709da1029f", @payee_middle_name=nil, @amended_from=nil, @back_reference_sched_name=nil, @payee_organization="Upgrade Films", @payee_state="DC", @transaction_id="E.1", @election_code="P2012", @payee_city="Washington", @payee_address_1="3299 K Street NW, Ste 200", @amount=65, @entity_type="ORG", @payee_first_name=nil, @filing_id=764901, @filed_date="2012-02-07", @payee_last_name=nil, @fec_committee_id="C30001655", @expenditure_date="2012-01-30", @payee_zip="20007">, ...]

ElectioneeringCommunication.committee("C30001655") # Crossroads GPS ElectioneeringCommunication.date("02/06/2012") # EC's from February 6, 2012

== Note on Patches/Pull Requests

• Fork the project.
• Make your feature addition or bug fix.
• Add tests for it. This is important so I don't break it in a future version unintentionally.
• Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
• Send me a pull request. Bonus points for topic branches.

== Authors

• Derek Willis, [e-mail]
• Al Shaw, [e-mail]
• Jason Holt, [e-mail]
• Benjamin Jackson, http://twitter.com/benjaminjackson
• Daniel Leavitt, https://github.com/dleavitt

== Copyright

Copyright (c) 2015 The New York Times Company. See LICENSE for details.