US elections data API.
An API for retrieving locally-relevant structured data about US elections.
$ curl -s https://elections.api.aclu.org/v1/pip?lat=40.7023699&lng=-74.012632
Output: example-output.json
All endpoints expect an HTTP GET request and respond in JSON format. The base URL for API requests is https://elections.api.aclu.org
.
Get an Apple Wallet pkpass based on polling place info.
Arguments:
address
: The polling place addresshours
: The polling place hourslat
: Latitudelng
: Longitude
Get an election calendar for a given state.
Arguments:
format
: Response format (optional; json or ics).state
: The state to load (e.g., ny).
Congress election lookup by location.
Arguments:
geometry
: Include GeoJSON geometries with districts (optional; geometry=1)lat
: Latitudelng
: Longitude
Congressional district lookup by location.
Arguments:
geometry
: Include GeoJSON geometries with districts (optional; geometry=1)lat
: Latitudelng
: Longitude
Index of all congressional legislators.
Arguments:
id
: Numeric part of aclu_id (optional; returns a single match).include
: Fields to include (optional; include=name)url_slug
: State and name URL slug (optional; returns a single match).
Index of congressional legislator scores.
No arguments.
County election lookup by location.
Arguments:
geometry
: Include GeoJSON geometries with districts (optional; geometry=1)lat
: Latitudelng
: Longitude
Get an approximate lat/lng location based on IPv4.
Arguments:
ip
: The IPv4 address to look up (optional; e.g., 38.109.115.130)legislators
: Use the resulting location to do a point-in-polygon congress_legislators lookup. (optional; set to 1 to include)pip
: Use the resulting location to do a point-in-polygon lookup. (optional; set to 1 to include state-level pip results)
Lookup Google Civic Info for an election.
Arguments:
address
: Address search string.ocd_id
: An Open Civic Data ID for the election.
Point in polygon election lookup by location.
Arguments:
geometry
: Include GeoJSON geometries with districts (optional; geometry=1)id
: Hyphen-separated list of numeric IDs (alternative to lat/lng)lat
: Latitudelng
: Longitudestate
: Instead of lat/lng or id, specify a state (e.g., state=ny)
State election lookup by location.
Arguments:
geometry
: Include GeoJSON geometries with districts (optional; geometry=1)lat
: Latitudelng
: Longitude
State legislature election lookup by location.
Arguments:
geometry
: Include GeoJSON geometries with districts (optional; geometry=1)lat
: Latitudelng
: Longitude
You can also load /v1
for a structured summary of the endpoints.
You can browse the included data
and sources
folders. Each has a Makefile
for downloading, processing, and indexing source data.
The API relies on other upstream services and expects some API keys to be defined as environment variables.
- Google Civic Info API:
GOOGLE_API_KEY
- Mapbox Geocoding API:
MAPBOX_API_KEY
- Google Geocoding API:
GOOGLE_API_KEY
(optional; only used for polling places) - ipstack:
IPSTACK_API_KEY
(optional; defaults to Maxmind)
Here are the steps to run the server locally for development purposes. For now you must run everything from the /usr/local/aclu
directory.
$ cd elections-api
$ createdb elections
$ make
$ cd server/
$ pip install -r requirements.txt
$ export GOOGLE_API_KEY="..."
$ export MAPBOX_API_KEY="..."
$ python server.py
The API server is designed to run on Ubuntu 16.04.
$ sudo mkdir -p /usr/local/aclu
$ sudo chown $USER:$USER /usr/local/aclu
$ cd /usr/local/aclu
If you work at the ACLU and have access to the private repo included as a submodule in the project, run:
$ git clone --recurse-submodules git@github.com:aclu-national/elections-api.git
Otherwise
$ git clone https://github.com/aclu-national/elections-api.git
$ cd elections-api
$ sudo ./scripts/setup_ubuntu.sh
The config file server/gunicorn.py
has environment variables and feature flags that you will need to edit.
Whenever updates are made to the data, PostGIS needs to be reindexed. This can take several minutes, so you'll want to be careful to only reindex machines that are out of the load balancer rotation.
$ cd /usr/local/aclu/elections-api
$ make
You can also reindex selected database tables.
$ make elections
WARNING: If you want to update the scores, by running make congress_scores
, make sure to run make congress_details
first. You can chain these together as one command: make congress_details && make congress_scores
When the API server code changes, the application server needs to be restarted after git pull
ing the changes. Be sure to create a CloudFront invalidation for the new results to take effect.
$ sudo service elections restart
When you ssh into the box and get a message like *** System restart required *** just reboot ubuntu
$ sudo reboot
Here's how you can use siege
to simulate 50 concurrent requests using a list of 1,000 random lat/lng lookups within the U.S.A.
$ export SIEGE_SCHEME="http"
$ export SIEGE_HOST="localhost:5000"
$ siege -c 50 -t 15S -f server/test_urls.txt -i
- Census TIGER/Line
- The Unified Judicial System of Pennsylvania
- @unitedstates
- Ballotpedia (not available for public release)