Election Contacts

This repo collects information by locale (county or town) from critical swing states for MailMyBallot.org. Code for each state is under the state's name.

Getting Started

To get started, run the make create-install command. There are other useful commands there.

The real work is done by PyInvoke, a simple task runner which was installed by the previous command.

Data Format

Data is saved in the /public folder by state (e.g. florida.json). Each file is a json array of all election-official contacts for locale. The format of the contacts depends on the state but supports (at a minimum) the following typescript interface

interface Contact {
  // each contact should have a locale and either a county or city
  // it should also have either an email or fax and preferably the county official's name.
  locale: string            // locale name, unique within state
  county?: string           // county name
  city?: string             // city or township name
  official?: string         // name of election's official
  emails?: string[]         // array of emails
  faxes?: string[]          // list of fax numbers

  // optional fields
  phones?: string[]         // list of phone numbers
  url?: string              // url for locale's election information
  address?: string          // mailing address data
  physicalAddress?: string  // physical address 
  party?: string            // party affiliation of official
}

NB:, fields with a question mark (e.g. county?) indicate that the value may possibly be empty, i.e. no such key exists. If no values are provided by the state, this is how it is indicated.

Adding a New State

Each state's crawler is put under it's own folder (e.g. states/new_york/main.py) with potentially other files in the folder.

• We use cache_request to reqeust webpages so that the results are saved to a local cache for faster development.

• You can invoke the file using PyInvoke, i.e.

  inv collect new_york

• The results are then saved in the above json format.

• Once you have the data, verify that it works by runnin tests:

  make test

• Also, rerun the Jupyter notebook analysis/Analysis.ipynb from scratch to update the analytics. You can see how many fields you were able to parse. To start the jupyter notebook, run make jupyter. Run the notebook. Make sure that you have all the values you need. Do not commit the notebook changes. Jsut throw them away. They just block rebase merging.

Notes on Submitting Code

Please submit code via pull requests, ideally from this repo if you have access or from your own fork if you do not.

• We strive to only use rebase merges
• Please don't save changes to the Jupyter notebook analysis/Analysis.ipynb (it will break your rebase merge).

Notes on Deploying

To update a version, tag the commit with a bumped semvar version and push the tag. Admittedly we are a little loose on the definition of a "minor" vs "patch" increment. For example, if the previous version was 1.4.0 and we chose to increment to 1.5.0, we would deploy using:

git tag v1.5.0
git push origin v1.5.0

To see a list of all tags, run

git fetch
git tag --list

DO NOT DELETE TAGS ONCE THEY ARE PUBLISHED! Just increment the minor version and republish if you made a mistake. We rely on stable tags for production.

Some State-Specific Information

Florida

• Vote by Mail
• County Supervisors

Maine

• Vote by Mail
• Municipal Clerks (with a link to download them as a CSV)

Michigan

• They seem to accept email applications Election Official's Manual
• "Michigan residents who live in unincorporated places register to vote with their township clerk": MI SOS
• The City-type matters: there is a St. Joseph Township and City, both in Berrien County. They share a zipcode (Wikipedia Township, City)
• The following Address is in Olive Township, not West Olive: "12220 Fillmore Street, Room 130 West Olive, MI 49460".
• There is both a Sheridan Chatter Township as well as a Sheridan Township, which are quite far apart. Similarly for Caledonia, Shelby, Lincoln, Lake, and Benton.

Georgia

• Contact info for county board of registrars offices website.

Virginia

• Contact info available here

Wisconsin

• Municipal Clerk Lookup (API)
• Municipal Clerk List (PDF)
• County Clerk List (PDF)

Usage

• To get started, look at the Makefile. You can install files, startup Jupyter, etc ...
• To run tasks, we use PyInvoke. Look at tasks.py file

About Us

This repository is for MailMyBallot.org, a National Vote at Home Institute project.

Contributors

• tianhuil
• twagner000
• Luca409