Michigan Elections API

APIs to check voter registration status and view sample ballots for elections in Michigan.

Quick Links

• Browse the source: https://github.com/citizenlabsgr/elections-api/
• Report an issue: https://github.com/citizenlabsgr/elections-api/issues/
• Contact the maintainers: https://citizenlabs.org/#contact

Sample Projects

Website	Purpose	Status
https://share.michiganelections.io	Ballot previews	Deployed
https://app.michiganelections.io	Ballot tracker	Deployed
https://vote.citizenlabs.org	Registration chat bot	Deployed
https://github.com/MI-Vote/mivote-android	Mobile voter app	Development
https://github.com/MI-Vote/mivote-ios	Mobile voter app	Development
https://explore.michiganelections.io	Election advocacy	Discovery

---

Overview

These examples use HTTPie for brevity, but the interactive documentation below shows how to do the same using raw curl requests.

Registration Status

Check your registration status and fetch your voting precinct with an API call like this:

http GET https://michiganelections.io/api/registrations/ \
  "Accept: application/json; version=3" \
  first_name==Rosalynn last_name==Bliss birth_date==1975-08-03 zip_code==49503

If you are registered to vote, this will return your voting precinct:

"precinct": {
    "county": "Kent",
    "jurisdiction": "City of Grand Rapids",
    "ward": "2",
    "number": "30", ...
}

as well as a unique ID that identifies your precinct:

"precinct": {
    "id": 1173,
    ...
}

Using either of these pieces of information, you can fetch the details of your specific ballot.

Voting Locations

The registrations payload also includes your polling location:

"polling_location": [
    "Mayfair Christian Reformed Church",
    "1736 Lyon NE",
    "Grand Rapids, Michigan 49503"
]

And the address where you can drop off your signed absentee ballot:

"dropbox_locations": [
    {
      "address: [
        "300 Ottawa Ave NW",
        "Grand Rapids, MI 49503"
      ],
      "hours: [
        "M-F 8am-5pm"
      ]
    },
    ...
]

Absentee Information

The registrations payload also includes fields indicating the voter's absentee status and progress of their ballot:

Field	Description
registered	Voter is registered to vote in future elections
absentee	Voter has requested to vote by mail for all elections
absentee_application_received	Date (YYYY-MM-DD) clerk received absentee application
ballot	Voter will have a ballot for the the upcoming election
absentee_ballot_sent	Date (YYYY-MM-DD) clerk mailed your absentee ballot
absentee_ballot_received	Date (YYYY-MM-DD) clear recorded your absentee vote

Ballot dates reset after each election. Absentee status resets each year.

Sample Ballots

Get a link to the official sample ballot for upcoming elections, by precinct ID with an API call like this:

http GET https://michiganelections.io/api/ballots/ \
  "Accept: application/json; version=3" \
  precinct_id==1173

or by precinct name with an API call like this:

http GET https://michiganelections.io/api/ballots/ \
  "Accept: application/json; version=3" \
  precinct_county==Kent precinct_jurisdiction=="City of Grand Rapids" \
  precinct_ward==2 precinct_number==30

Ballot Details: Positions

Get more information about the specific positions and candidates on your ballot, by precinct ID with an API call like this:

http GET https://michiganelections.io/api/positions/ \
  "Accept: application/json; version=3" \
  precinct_id==1173

or by precinct name with an API call like this:

http GET https://michiganelections.io/api/positions/ \
  "Accept: application/json; version=3" \
  precinct_county==Kent precinct_jurisdiction=="City of Grand Rapids" \
  precinct_ward==2 precinct_number==30

Results can be filtered by name, description, election name, and district name using a q query parameter. Prefix a search term with - to exclude it from results.

Ballot Details: Proposals

Get more information about the specific proposals on your ballot, by precinct ID with an API call like this:

http GET https://michiganelections.io/api/proposals/ \
  "Accept: application/json; version=3" \
  precinct_id=1173

or by precinct name with an API call like this:

http GET https://michiganelections.io/api/proposals/ \
  "Accept: application/json; version=3" \
  precinct_county==Kent precinct_jurisdiction=="City of Grand Rapids" \
  precinct_ward==2 precinct_number==30

Results can be filtered by name, description, election name, and district name using a q query parameter. Prefix a search term with - to exclude it from results.

Documentation

The browsable API powered by Django REST Framework can be found here: https://michiganelections.io/api/

Interactive API documentation powered by Swagger UI, can be found here: https://michiganelections.io/docs/

Versions of the API are requested through content negotiation. Your client will receive the highest compatible version for the major version you request.

Zapier Integration

Get notified about upcoming elections and changes to your registration status using the official Zapier integration: https://app.michiganelections.io/zapier/

Contributing

If you would like to contribute to this project, fork this repository or ask for commit access rights during one of our "Hack Night" events.

Once you have access rights or a fork, please read the CONTRIBUTING.md file to set up your local environment. Create a branch for every issue you work on and make a pull request to main with the corresponding issue attached.

You can also contribute content changes by editing these files directly on GitHub. If you would like to know more about us, please check out our welcome kit.

History

Version 3.5

• Added party nomination attribute for nonpartisan judgeships.

Version 3.4

• Added ?q= text search to /api/proposals/ and /api/positions/.

Version 3.3

• Added proposals_count and positions_count to elections API responses.

Version 3.2

• Added items count to the ballot portion of status API responses.

Version 3.1

• Added ballots to registration API responses.
• Added ballot to status API responses.

Version 3.0

• Removed unused description field from election responses.
• Removed support for legacy (1.x) dropbox_location field in registration API responses.

Version 2.0

• Replaced dropbox_location with dropbox_locations in registrations API responses to include multiple locations and hours.

Version 1.11

• Added ballot to registration and status API responses.

Version 1.10.1

• Updated /api/status/ to return a 202 when the Michigan Secretary of State website is unavailable.

Version 1.10

• Added /api/status/ to enable triggering when a voter's registration status changes for an upcoming election.

Version 1.9

• Added dropbox_location to registrations API responses.

Version 1.8

• Added absentee_application_received, absentee_ballot_sent, and absentee_ballot_received dates to the registrations API responses to track the progress of each voter's absentee ballot.

Version 1.7

• Added section to ballot positions API responses to filter primary ballot selection.

Version 1.6

• Added recently_moved to registrations API responses to indicate that precinct information may not currently be accurate.

Version 1.5

• Added date_humanized field to elections API responses.

Version 1.4

• Added absentee to the registrations API responses to indicate that a voter has absentee status.

Version 1.3

• Added description_edit_url to responses for elections, district categories, parties, and positions.

Version 1.2

• Added a glossary API to display descriptions for elections, district categories, parties, and positions.

Version 1.1

• Added polling_location to the registrations API.
• Added description to the district category, election, and party APIs.

Version 1.0

• Initial public release.