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
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
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.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
withdropbox_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
, andabsentee_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.