https://github.com/citizenlabsgr/elections-api
API for voter registration status and sample ballots in Michigan.
https://github.com/citizenlabsgr/elections-api
api django django-rest-framework hacktoberfest markdown python web-scraping
Last synced: about 1 year ago
JSON representation
API for voter registration status and sample ballots in Michigan.
- Host: GitHub
- URL: https://github.com/citizenlabsgr/elections-api
- Owner: citizenlabsgr
- License: gpl-3.0
- Created: 2018-06-19T23:46:33.000Z (about 8 years ago)
- Default Branch: main
- Last Pushed: 2025-04-02T20:21:39.000Z (over 1 year ago)
- Last Synced: 2025-04-12T23:38:28.526Z (about 1 year ago)
- Topics: api, django, django-rest-framework, hacktoberfest, markdown, python, web-scraping
- Language: Python
- Homepage: https://michiganelections.io
- Size: 3.1 MB
- Stars: 11
- Watchers: 5
- Forks: 8
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Michigan Elections API
[](https://circleci.com/gh/citizenlabsgr/elections-api)
[](https://coveralls.io/github/citizenlabsgr/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://github.com/citizenlabsgr/ballotshare) |
| https://app.michiganelections.io | Ballot tracker | [Deployed](https://github.com/citizenlabsgr/ballotbuddies) |
| https://vote.citizenlabs.org | Registration chat bot | [Deployed](https://github.com/citizenlabsgr/mittens) |
| https://github.com/MI-Vote/mivote-android | Mobile voter app | [Development](https://github.com/MI-Vote/mivote-android) |
| https://github.com/MI-Vote/mivote-ios | Mobile voter app | [Development](https://github.com/MI-Vote/mivote-android) |
| https://explore.michiganelections.io | Election advocacy | [Discovery](https://github.com/citizenlabsgr/elections-app) |
---
## Overview
These examples use [HTTPie](https://httpie.org/) 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](https://michiganelections.io/api/registrations/?first_name=Rosalynn&last_name=Bliss&birth_date=1975-08-03&zip_code=49503) 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](https://michiganelections.io/api/ballots/?precinct_id=1173) 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](https://michiganelections.io/api/ballots/?precinct_county=Kent&precinct_jurisdiction=City%20of%20Grand%20Rapids&precinct_ward=2&precinct_number=30) 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](https://michiganelections.io/api/positions/?precinct_id=1173) 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](https://michiganelections.io/api/positions/?precinct_county=Kent&precinct_jurisdiction=City%20of%20Grand%20Rapids&precinct_ward=2&precinct_number=30) 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](https://michiganelections.io/api/proposals/?precinct_id=1173) 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](https://michiganelections.io/api/proposals/?precinct_county=Kent&precinct_jurisdiction=City%20of%20Grand%20Rapids&precinct_ward=2&precinct_number=30) 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](https://www.django-rest-framework.org) can be found here: https://michiganelections.io/api/
Interactive API documentation powered by [Swagger UI](https://swagger.io/tools/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](https://citizenlabs.org/join/).
Once you have access rights or a fork, please read the [CONTRIBUTING.md](https://github.com/citizenlabsgr/elections-api/blob/main/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](https://github.com/citizenlabsgr/elections-api/tree/main/content) directly on GitHub. If you would like to know more about us, please check out our [welcome kit](https://github.com/citizenlabsgr/read-first).
## 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.