FecResults
FecResults is a Ruby library that provides access to federal election results as published by the Federal Election Commission. Although it is primarily a campaign finance disclosure agency, the FEC also compiles election results on its site. This library provides ways to access summary and contest-specific information about elections for the U.S. House of Representatives, the U.S. Senate and President from 2000-2012. This data represents regularly-scheduled primary and general elections, plus special elections held on the date of general elections. It does not include special elections held outside the regularly scheduled election calendar. The results are race-wide only; they do not contain any geographic breakdowns such as county.
What's not here is results below the "race-wide" level; there are no county or precinct-level results, only those for the state and House district.
Please be aware that there can be typos in some of the FEC results files, mainly in the FEC candidate IDs.
Installation
Add this line to your application's Gemfile:
gem 'fec_results'
And then execute:
$ bundle
Or install it yourself as:
$ gem install fec_results
Getting Started
FecResults can be used to retrieve both summary and contest-specific election results. Every instance of an FecResults class must include a year passed into the new method.
Summary Results
The Summary class represents state, race and chamber totals for 2000-2012, plus a few other methods that are not strictly results themselves. Summary methods return Ruby objects built with OpenStruct. To get started, create an instance of the Summary class using a year hash:
s = FecResults::Summary.new(:year => 2012)
Summary objects have a handful of methods, from the general election votes by race type (President, Senate, House) to party vote totals by chamber. To retrieve general election votes:
general_votes = s.general_election_votes
=> [<OpenStruct state="AL", presidential_votes=2074338, senate_votes=nil, house_votes=1933630>, <OpenStruct state="AK", presidential_votes=300495, senate_votes=nil, house_votes=289804>,...]
general_votes.
alabama = general_votes.first
=> <OpenStruct state="AL", presidential_votes=2074338, senate_votes=nil, house_votes=1933630>
alabama.house_votes
=> 1933630
Another way to isolate a single state is to pass in an optional hash with the state abbreviation to the method called. The state filter is the only filter for Summary objects.
alabama_votes = s.general_election_votes({:state => 'AL'})
=> [<OpenStruct state="AL", presidential_votes=2074338, senate_votes=nil, house_votes=1933630>, <OpenStruct state="AK", presidential_votes=300495, senate_votes=nil, house_votes=289804>]
The Summary object methods work for all years except house_party_gains, which only applies to the 2010 cycle. In addition to summary election results, each cycle also has a party_labels method that lists political parties and the abbreviations used by the FEC for that cycle's results data.
Presidential Results
In presidential years (2000, 2004, 2008 and 2012), FecResults offers totals of the popular and electoral vote, along with election results for both the primary and general elections. Retrieving presidential data works the same way, by passing a year:
p = FecResults::President.new(:year => 2000)
p.primary_party_summary
=> [<OpenStruct party="Democratic Party (D)", total_votes=15975066>, #<OpenStruct party="Republican Party (R)", total_votes=7940331>, ..]
Presidential methods include popular vote totals, state totals for electoral and popular votes, primary totals by party and election results for the primary and general elections.
Congressional Results
FecResults offers House and Senate results for 2000-2012, which are built using the Result object (as are presidential results). For congressional results, the file can take awhile to load, so try not to call results more than once, but rather save the output to a variable:
c = FecResults::Congress.new(:year => 2012)
results = c.results
results.first
=> <FecResults::Result:0x007fb46e297870 @year=2012, @chamber="H", @state="AL", @district="01", @fec_id="H2AL01077", @incumbent=true, @candidate_last="Bonner", @candidate_first="Jo", @candidate_name="Bonner, Jo", @party="R", @primary_votes=48702, @primary_pct=55.54959907839358, @primary_unopposed=false, @runoff_votes=nil, @runoff_pct=nil, @general_votes=196374, @general_pct=97.85624588889553, @general_unopposed=false, @general_runoff_votes=nil, @general_runoff_pct=nil, @general_combined_party_votes=nil, @general_combined_party_pct=nil, @general_winner=true, @notes=nil>
Not all years have the same data available - for example, general election winners are not always marked. In addition, some states permit candidates to run as the nominee of multiple parties; these candidates usually have a Result instance with a combined parties total and separate instances for each party.
JSON API
Using the FecResultsGenerator library, there is a static file JSON API of data retrieved by FecResults. It covers the years 2000-2012 and consists of three sections: Congress, President and Summary, matching the classes found in the gem. You can browse the API by changing the year, class name and method name. Here is a listing of the endpoints, using 2012 data:
Summary
President
- Popular Vote Summary
- State Electoral and Popular Vote Summary
- General Election Results
- Primary Election Results