Skip to content
This repository has been archived by the owner. It is now read-only.
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


A set of tools around election results, candidates, districts, and related data. Specifically, civix aims to provided:

  • A datase model for elections and related data.
  • Tools for importing data from multiple sources.
  • A simple interface to manage and manually edit data when needed.
  • Ability to export data to a static location such as S3.

Inspiration taken from Politico's civic suite of tools.

Getting started


The long term goal is: npm install civix -g

In the meantime, clone the project and do: npm install && npm link

Install dependencies:


  • CIVIC_LOGS: Path to where logs, defaults to .logs in the current working directory.
  • CIVIX_DEBUG: Turn on debugging
    • DEBUG=civix:*: Specific debugging
  • AP_API_KEY: Used by Elex to get AP data
  • SOS_FTP_USER: The FTP username to access to MN Secretary of State FTP site.
  • SOS_FTP_PASS: The FTP password to access to MN Secretary of State FTP site.
  • CIVIX_TEST_RESULTS: Whether to use test data from AP or MN Elections API.

Setting up the database.

  • This application requires Postgres/PostGIS. It might be possible to use another database with spatial data types, but this has not been tested.
    • TODO: Instructions on setting up Postgres and PostGIS.
    • If using on a Mac, this gist about setting up PostGIS is helpful, but needs to be adjusted for versions.
  • civix migrate: This will create tables in the database as needed.
    • TODO: Specific migrations not currently implemented.


Base data

Getting data is done with the civix import command.

  • Manually created core data:
    • Political parties: civix import civix-manual/parties
    • Boundary divisions: civix import civix-manual/divisions
  • Boundaries:
    • Country boundaries, including USA: civix import natural-earth/boundaries-countries
    • US state boundaries: civix import census-tiger/boundaries-states
    • US county boundaries: civix import census-tiger/boundaries-counties --year=XXX
      • Year options: 2017
    • US congressional boundaries: civix import census-tiger/boundaries-congressional --congress=XXX
      • Congress option can be 110 - 115
      • This may not be perfect, since these boundaries change at any time.
    • MN state house: civix import mn-state-leg/boundaries-state-house --year=XXX
      • Year options: 1994, 2002, 2012
    • MN state senate: civix import mn-state-leg/boundaries-state-senate --year=XXX
      • Year options: 1994, 2002, 2012
    • MN state municipal (cities and townships): civix import mn-state-leg/boundaries-municipal --year=XXX
      • Year options: 2014, 2016, 2018
    • MN state precincts: civix import mn-state-leg/boundaries-precincts --year=XXX
      • Year options: 2012, 2014, 2016, 2018
    • MN county commissioners: civix import mn-state-leg/boundaries-county-commissioner --year=XXX
      • Year options: 2012, 2014, 2016, 2018
    • MN hospital districts: civix import mn-state-leg/boundaries-hosptials --year=XXX
      • Year options: 2012, 2014, 2016, 2018
    • MN local wards: civix import mn-state-leg/boundaries-wards --year=XXX
      • Year options: 2014, 2016, 2018
    • MN local park boards: civix import mn-state-leg/boundaries-park-board --year=XXX
      • Year options: 2014, 2016, 2018
    • MN park districts: civix import mn-state-leg/boundaries-park-district --year=XXX
      • Year options: 2012, 2014, 2016, 2018
    • MN park districts: civix import mn-state-leg/boundaries-park-district --year=XXX
      • Year options: 2014, 2016, 2018
    • MN soil and water conservation districts: civix import mn-state-leg/boundaries-soil-water --year=XXX
      • Year options: 2012, 2014, 2016, 2018

TODO more

Election night data

  • AP data via the Elex
    • Get races/contests: civix ap-elex/ap-races
    • Get candidates: civix ap-elex/ap-candidates
    • Get results: civix ap-elex/ap-results

Export data

Exporting means exporting data from the database to JSON files in your local filesystem. This is done with civix export.

  • Contests and groups of contests: civix export core/contests

Publish data

To publish the exported flat files to S3, use civix publish

Data structure and models.

All about the data structure and database schema. See files in ./models/ for more technical information about the database models.

  • Boundaries: Boundary models describe geographical areas for offices and elections.
    • A Boundary entry describes an area, and connects it to a Division and possible a parent Boundary.
      • For example, the state of Minnesota is a boundary.
    • A Boundary Version describes the actual geographical shape of a boundary for a specific period in time. This entry also may include census fields such as FIPS, GEOID, or AFFGEOID.
      • For example, Minnesota Congressional District 2 is a boundary, but the specific shape of it as defined by the 2010 Census and started being used in 2012 is the specific boundary version.
    • A Division describes groups and heirarchy of boundaries.
      • For example, a state is a division, and a county is a divison that is a child of a state.
  • Government: Government models describes offices and bodies that have elected officials.
    • Body: A collection of related offices such as a state senate.
      • For example, the Minnesota State House
    • Office: A position that is filled by an elected official.
      • For example, the office of Minnesota's Congressional District 5
    • Party: A political party.
      • For example, the Republican party.
  • Elections: Election models bring together Boundaries and Government to describe election results.
    • Election: An election on a date in a place. Usually the place is a state.
      • For example, 2018 General Election in Minnesota.
    • Candidate: A single person, answer, or position that is an option for a specific contest.
      • For example, Jane Doe, or Yes, or write-in's.
    • Contest: A contest in an Election. This is often tied to an Office, except for questions/ballot measures. It should, though not needed, be tied to a Boundary Version. A Contest can also be a "sub-contest"; for example the results for a contest for each county in a state.
      • For example, 2018 election for Hennepin County Commissioner 3.
      • A sub contest may be precinct results for that contest.
    • Result: The numbers for a Candidate in a Contest.
      • For example, Muhammad Doe got 123 votes.


A set of tools around election results, candidates, districts, and related data.






No releases published


No packages published