Download OpenAPI specification:Download
Democracy Works collects data about elections that happen in the US.
We record this data in two entities, one called an Election, and one called an Authority.
The Election has election-specific dates and deadlines, URLs to get more information and take actions, and detailed instructions. The information included reflects the voter registration and voting methods available in the state for that election, such as online, in-person, and by-mail registration as well as by-mail, in-person, and early voting. The Election also contains some information from the related Authority, or Authorities in some cases.
The Authority includes contact information, available registration methods, available voting methods, state-specific URLs, and more. Authorities do not contain election-specific information such as dates, and Authority information generally does not change from election to election.
Election and Authority data is based on Open Civic Data IDs (OCD-IDs), so you should familiarize yourself with how they work before jumping into the rest of this document.
Both Authorities and Elections are identified using an Open Civic Data ID (OCD-ID).
OCD-IDs start with what is being identified, and in our case it is always
ocd-division
.
Then there is a tree-like structure of strings where the longer the
identifier gets, the more specific or fine-grained the identifier becomes.
In our case, there is always country:us
, because we only cover US
Elections. We cover all 50 States, and the District of Columbia.
Since all local Elections are contained within States, every OCD-ID in our
system (except one) starts with ocd-division/country:us/state:__
, where
__
is a two-letter state code.
The only exception to this is for the District of Columbia, which has the
OCD-ID ocd-division/country:us/district:dc
.
After the state, the OCD-ID gets more specific by getting longer and using various legal jurisdiction labels to indicate what area an Election or Authority is covering. Some examples are
county:___
, place:___
(generally means municipality), parish:__
(for Louisiana), borough:__
(for Alaska), sd:__
(for School District),etc.
Here are some examples:
ocd-division/country:us/state:wi/county:ashland/place:agenda
ocd-division/country:us/state:wi/county:ashland
ocd-division/country:us/state:wi
ocd-division/country:us/state:ma/place:agawam_town
Sometimes a place is nested under a county, and sometimes it is not. This could indicate that the municipality is in multiple counties or that there are multiple unique municipalities in the state with the same name but in different counties, but not necessarily.
If a request is made like this:
curl -H "Accept: application/json" -H "x-api-key: $YOUR_API_KEY" \
"https://api.democracy.works/v2/elections?ocdId=ocd-division/country:us/state:ok/county:kiowa"
The response will contain an OCD-ID here:
{
"elections": [
{
"ocdId": "ocd-division/country:us/state:ok/county:kiowa",
...
If a request is made like this:
curl -H "Accept: application/json" -H "x-api-key: $YOUR_API_KEY" \
"https://api.democracy.works/v2/authorities?ocdId=ocd-division/country:us/state:co/county:montrose"
The response will contain an OCD-ID here:
{
"authorities": [
{
"ocdId": "ocd-division/country:us/state:co/county:montrose",
...
The response contains a list of authorities
, and the OCD-ID is the first
item in the object under ocdId
.
Gets authorities within the given state (or DC).
stateCode required | string Example: ny The 2-letter postal code of the state to get authorities for. DC is accepted as well. |
{- "data": {
- "ocdId": "string",
- "officeName": "string",
- "officialTitle": "string",
- "homepageUrl": "string",
- "pollingLocationUrl": "string",
- "partyInstructions": "string",
- "updatedAt": "string",
- "timezone": "string",
- "secondaryTimezone": "string",
- "localElectionAuthorityOfficeAlias": "string",
- "separateRegistrationAndElectionAuthorities": true,
- "localElectionAuthorityName": "string",
- "localRegistrationAuthorityName": "string",
- "localRegistrationAuthorityLookupUrl": "string",
- "localElectionAuthorityLookupUrl": "string",
- "registrationAuthorityLevel": "string",
- "electionAuthorityLevel": "string",
- "contact": {
- "phone": "string",
- "email": "string",
- "physicalAddress": {
- "street": "string",
- "city": "string",
- "state": "string",
- "zip": "string"
}, - "mailingAddress": {
- "street": "string",
- "city": "string",
- "state": "string",
- "zip": "string"
}
}, - "voting": {
- "inPersonVotingAvailable": true,
- "mailBallotsSentAutomatically": true,
- "inPerson": {
- "idInstructions": "string"
}, - "early": {
- "supported": true,
- "excuseRequired": true
}, - "byMail": {
- "ballotApplicationOnline": "string",
- "returnByMailUrl": "string",
- "eligibilityUrl": "string",
- "returnInPersonUrl": "string",
- "excuseRequired": true,
- "excuses": "string",
- "ballotTrackingUrl": "string",
- "ballotApplicationDownload": "string",
- "idInstructions": "string",
- "alias": "string"
}
}, - "registration": {
- "statusUrl": "string",
- "formUrl": "string",
- "noRegistrationRequiredInstructions": "string",
- "methods": [ ],
- "byMail": {
- "supported": true,
- "url": "string",
- "forms": "string",
- "raceFieldRequired": true,
- "raceFieldInstructions": "string",
- "idInstructions": "string",
- "signatureInstructions": "string",
- "citizenInstructions": "string",
- "newVoterInstructions": "string"
}, - "online": {
- "supported": true,
- "instructions": "string",
- "url": "string"
}, - "inPerson": {
- "supported": true,
- "electionDayInstructions": "string",
- "advanceUrl": "string"
}
}, - "youthRegistration": {
- "url": "string",
- "formUrl": "string",
- "supported": "string",
- "methods": "string",
- "onlineInstructions": "string",
- "inPersonInstructions": "string",
- "byMailInstructions": "string",
- "eligibilityAge": "string",
- "statusAvailability": "string"
}
}
}
Gets authorities based on the provided filter. At most one of ocdId
, address
, or stateCode
can be provided.
ocdId | string Example: ocdId=ocd-division/country:us/state:nj The OCD-ID get authorities for. Will return all authorities including and within the given OCD-ID. |
address | string Example: address=1101 Biscayne Blvd, Miami, FL 33132 The address get authorities for. |
stateCode | string Example: stateCode=CA The 2-letter postal code to get authorities within a respective state. DC is accepted as well. A special character, |
pageSize | number Example: pageSize=15 The number of authorities requested. Defaults to 10 if not specified. The maximum value is 100. |
page | number Example: page=2 The page of authorities to return, based on pageSize. Defaults to 1 if not specified. |
{- "data": {
- "authorities": [
- {
- "ocdId": "string",
- "officeName": "string",
- "officialTitle": "string",
- "homepageUrl": "string",
- "pollingLocationUrl": "string",
- "partyInstructions": "string",
- "updatedAt": "string",
- "timezone": "string",
- "secondaryTimezone": "string",
- "localElectionAuthorityOfficeAlias": "string",
- "separateRegistrationAndElectionAuthorities": true,
- "localElectionAuthorityName": "string",
- "localRegistrationAuthorityName": "string",
- "localRegistrationAuthorityLookupUrl": "string",
- "localElectionAuthorityLookupUrl": "string",
- "registrationAuthorityLevel": "string",
- "electionAuthorityLevel": "string",
- "contact": {
- "phone": "string",
- "email": "string",
- "physicalAddress": {
- "street": "string",
- "city": "string",
- "state": "string",
- "zip": "string"
}, - "mailingAddress": {
- "street": "string",
- "city": "string",
- "state": "string",
- "zip": "string"
}
}, - "voting": {
- "inPersonVotingAvailable": true,
- "mailBallotsSentAutomatically": true,
- "inPerson": {
- "idInstructions": "string"
}, - "early": {
- "supported": true,
- "excuseRequired": true
}, - "byMail": {
- "ballotApplicationOnline": "string",
- "returnByMailUrl": "string",
- "eligibilityUrl": "string",
- "returnInPersonUrl": "string",
- "excuseRequired": true,
- "excuses": "string",
- "ballotTrackingUrl": "string",
- "ballotApplicationDownload": "string",
- "idInstructions": "string",
- "alias": "string"
}
}, - "registration": {
- "statusUrl": "string",
- "formUrl": "string",
- "noRegistrationRequiredInstructions": "string",
- "methods": [ ],
- "byMail": {
- "supported": true,
- "url": "string",
- "forms": "string",
- "raceFieldRequired": true,
- "raceFieldInstructions": "string",
- "idInstructions": "string",
- "signatureInstructions": "string",
- "citizenInstructions": "string",
- "newVoterInstructions": "string"
}, - "online": {
- "supported": true,
- "instructions": "string",
- "url": "string"
}, - "inPerson": {
- "supported": true,
- "electionDayInstructions": "string",
- "advanceUrl": "string"
}
}, - "youthRegistration": {
- "url": "string",
- "formUrl": "string",
- "supported": "string",
- "methods": "string",
- "onlineInstructions": "string",
- "inPersonInstructions": "string",
- "byMailInstructions": "string",
- "eligibilityAge": "string",
- "statusAvailability": "string"
}
}
]
}, - "pagination": {
- "totalRecordCount": 0,
- "currentPage": 0,
- "pageSize": 0
}
}
Gets elections based on provided filters. Providing more than one query parameter will join them with AND logic.
address | string Example: address=813%20Howard%20Street%20Oswego%20NY%2013126 The street, city, state, and zip code of an address to get elections for. |
stateCode | string Example: stateCode=CA The 2-letter postal code to get elections within a respective state. DC is accepted as well. |
ocdId | string Example: ocdId=ocd-division%2Fcountry%3Aus%2Fstate%3Any%2Fcounty%3Akings The OCD-ID of a political division to get elections within. |
startDate | date Example: startDate=2023-01-01 The earliest date to get elections for, inclusive, in UTC ISO 8601 format. |
endDate | date Example: endDate=2023-01-02 The latest date to get elections for, inclusive, in UTC ISO 8601 format. |
pageSize | number Example: pageSize=15 The number of elections requested. Defaults to 10 if not specified. The maximum value is 100. |
page | number Example: page=2 The page of elections to return, based on pageSize. Defaults to 1 if not specified. |
Accept-Language | string Example: es The language tag for localization. Accepted values are |
{- "data": {
- "elections": [
- {
- "ocdId": "string",
- "createdAt": "string",
- "updatedAt": "string",
- "date": "string",
- "description": "string",
- "type": "congressional",
- "pollingLocationUrl": "string",
- "canonicalUrl": "string",
- "website": "string",
- "guidancePhase": "past",
- "population": "string",
- "voting": {
- "inPersonVotingAvailable": true,
- "mailBallotsSentAutomatically": true,
- "early": {
- "url": "string",
- "startDate": "string",
- "endDate": "string",
- "varies": true
}, - "byMail": {
- "explainerUrl": "string",
- "allMail": {
- "ballotInfoUrl": "string",
- "ballotSendStartDate": "string",
- "ballotSendEndDate": "string",
- "ballotReceiveExpectedStartDate": "string",
- "ballotReceiveExpectedEndDate": "string"
}, - "deadline": {
- "postmarkedOrReceived": "string",
- "receivedNoLaterThan": {
- "date": "string",
- "timestamp": "string",
- "description": "string"
}, - "returnInPerson": {
- "date": "string",
- "timestamp": "string",
- "description": "string"
}, - "returnByMail": {
- "date": "string",
- "timestamp": "string",
- "description": "string"
}, - "ballotRequest": {
- "postmarkedOrReceived": "string",
- "date": "string",
- "timestamp": "string",
- "description": "string"
}
}
}, - "inPerson": {
- "electionDay": {
- "closing": {
- "timestamp": "string",
- "description": "string"
}
}
}
}, - "registration": {
- "explainerUrl": "string",
- "inPerson": {
- "atPollingPlaceOnElectionDay": true,
- "localSamedayRegistrationAuthorityLookupUrl": "string",
- "deadline": {
- "date": "string",
- "timestamp": "string",
- "description": "string"
}
}, - "online": {
- "url": "string",
- "instructions": "string",
- "deadline": {
- "date": "string",
- "timestamp": "string",
- "description": "string"
}
}, - "byMail": {
- "idInstructions": "string",
- "signatureInstructions": "string",
- "newVoterInstructions": "string",
- "deadline": {
- "date": "string",
- "timestamp": "string",
- "description": "string",
- "postmarkedOrReceived": "string"
}
}
}
}
]
}, - "pagination": {
- "totalRecordCount": 0,
- "currentPage": 0,
- "pageSize": 0
}
}