Skip to content
A set of tools around election results, candidates, districts, and related data.
JavaScript
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin
config
examples
exporters/core
importers
lib
models
tests/lib
.editorconfig
.eslintrc
.gitattributes
.gitignore
README.md
index.js
package-lock.json
package.json

README.md

Civix

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

Install

The long term goal is: npm install civix -g

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

Install dependencies:

Configuration

  • CIVIC_LOGS: Path to where logs, defaults to .logs in the current working directory.
  • CIVIX_DEBUG: Turn on debugging
    • DEBUG=civix:*: Specific debugging
  • CIVIX_DATABASE_URI: Database URI
  • 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 Postgres.app 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.

Usage

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.
You can’t perform that action at this time.