A set of tools, configurations, and instructions to collect and serve election results on election night — the Super Bowl of data news — while still providing an off-season service and focusing on saving resources as much as possible. A project of MinnPost with support by OpenNews.
If you work at a small organization without access to AP or Reuters election data feeds, or are looking for more local results than these organizations provide, the Election Night API is here to help.
The purpose of this software is to make election results published by a state's Secretary of State or Board of Elections on election night available for use on websites or in other applications via an API.
This software will work best in states that publish election results live on election night in somewhat machine-friendly formats, like JSON, text files or maybe even Microsoft Excel, but you can still manually collect data in something like Google Spreassheets and supplement the results.
Detailed setup instructions can be found in the README.
A standard Python install. See the full instructions for more detail.
# Git code
$ git clone https://github.com/MinnPost/election-night-api.git && cd election-night-api
# Instal dependencies
$ pip install -r requirements.txt
Election Night API contains a basic template for scraping election night results files, but because each state and election is pretty different, custom scripts for parsing the results files must be written. You'll need to be able to write some basic Python to build a scraper for your state. For more details, see managing scrapers section and the example code.
# Start with the example
$ cp -r states/example states/xx
Run the scraper tool to save the data locally to the SQLite database. Some more details are available on the README.
# Get some help
$ bin/ena -h
# Get results for VA for the most recent election
$ bin/ena VA results
The API allows for arbitrary SQL selects of the data and returns JSON. Some more details are available on the README.
# Get all the contests
$ curl http://example-api.com/?q=SELECT%20*%20contests
[
{
"precincts_reporting": 4106,
"updated": 1415989261,
"county_id": "",
"title": "Attorney General",
"district_code": "",
"total_precincts": 4106,
"seats": 1,
"primary": 0,
"precinct_id": "",
"office_id": "0335",
"state": "mn",
"election": "20141104",
"office_name": "Attorney General",
"percent_reporting": 1,
"scope": "state",
"id": "id-MN----0335",
"total_votes": 1928980
},
...
]
You can run a local API for testing, but definitely don't use this for production. Some more details are available on the README.
# Run the basic API. It will be available at: http://localhost:5000/?q=
$ python tests/local_api.py
The API is intended to be deployed on a resourceful server, such as an Ubuntu server on EC2, on election night, to be able to handle high demand for the results. Detailed instructions can be found in the README.
# 1. Install code
# 2. Install Dumptruck
# 3. Install and confgiure FCGIWrap
# 4. Install and confgiure nginx
# 5. Schedule data collection (scraper)
When election night is over, demand is lessened, and results are no longer being updated frequently, it is easy to move the API off of your server and on to ScraperWiki, which has a free tier for journalists and free tier for everyone. See the full instructions on the README.