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 "Authorization: apikey $YOUR_API_KEY" \
"https://api.democracy.works/elections/upcoming?district-divisions=ocd-division/country:us/state:il/place:chicago"
The response will contain an OCD-ID here:
[
{
"district-divisions": [
{
"ocd-id": "ocd-division/country:us/state:il/place:chicago",
...
Note: Technically there can be more than one district-division
because the
value type is a list, but in practice we only use one, so it is safe to
treat the first object in the list as the value.
If a request is made like this:
curl -H "Accept: application/json" -H "Authorization: apikey $YOUR_API_KEY" \
"https://api.democracy.works/election-authorities/states"
The response will contain an OCD-ID here:
{"authorities": [
{"ocd-division": ["ocd-division/country:us/state:il", ...
The response contains a list of authorities
, and the OCD-ID is the first
item in the list under ocd-division
.
There are two ways to get information on Election Authorities, and both are for the state level only.
Information from State and Local Authorities is copied over to Elections, so often there isn’t a need to make requests for Authorities at all. The only fields that are not on the Election are:
voter-registration-status-url
so voters can look up there registration
statuslocal-election-authority-lookup-url
so voters can look up who to contact
about registration or voting information at the local level.You can request these URLs with the State Authority URLs resource.
All dates, even when they have no logical time component (such as the date
of an election), are returned in ISO 8601 format and always include a
placeholder time value (e.g. T00:00:00Z
).
You should interpret dates that do not have logical timestamps but are
presented in this format by dropping the placeholder time value and then
interpreting the result as a date without a time zone. For example,
2023-05-06T00:00:00Z
should be transformed to 2023-05-06
and then
treated as a date in your language of choice (for example, in Java this
might be a java.time.LocalDate
).
We will call out instances where a date with a time part needs to be interpreted as a date, referencing this section throughout our documentation.
We are working on improvements to this format in a future version of this API.
Instruction strings can be long and may contain embedded HTML links. Line
breaks appear as \n
. Instruction strings only appear in Objects with
parents named instructions
.
For example:
{"instructions":
{"registration": "To register in Illinois you must: \nbe a citi..."}}
Sometimes we know about elections before we’ve gathered and QAed all the
data. These elections may be available in the API, and they are designated
with a qa-status
of incomplete
. When using the Upcoming Elections API,
you may request these elections by adding a query parameter qa-status=all
to receive both complete and incomplete, or qa-status=incomplete
to
receive only incomplete elections. The default value is complete
.
An “upcoming” Election is one that is in our system and the date is in the future, including the day that the request is made. Both statewide and local Elections are part of this data set. We define a statewide Election as any election where all voters in the state have something on the ballot or any federal congressional election. These generally end in a two-letter state code. All other elections are considered local.
There are two ways to request Upcoming Elections:
Be sure to include the Accept
header because the default
Content-Type
is the lesser known EDN (application/edn). The two
Content-Type
s supported are application/json
and application/edn
.
Returns a list of all upcoming elections.
An example response is available, and all field definitions are in the Upcoming Elections API Reference.
curl -H "Accept: application/json" \
-H "Authorization: apikey $YOUR_API_KEY" \
https://api.democracy.works/elections/upcoming
Returns a list of all upcoming elections for the provided OCD-ID(s). Same as the above, but filtered.
curl -H "Accept: application/json" \
-H "Authorization: apikey $YOUR_API_KEY" \
"https://api.democracy.works/elections/upcoming?district-divisions=ocd-division/country:us/state:il/place:chicago"
district-divisions | string A comma-separated list, supplied as a string, of OCD IDs that will return upcoming elections only for the OCD IDs provided. |
language | string Enum: "en" "es" "all" By default, responses include instructions in English. At this time we
support 2 languages: English ( You may also use
|
qa-status | string Default: "complete" Enum: "incomplete" "complete" "all" See QA Status for a more in-depth discussion of the meaning of this parameter. |
Accept | string Enum: "application/json" "application/edn" |
Authorization | string Example: apikey $YOUR_API_KEY |
[- {
- "description": "string",
- "date": "2022-11-08T00:00:00Z",
- "district-divisions": [
- {
- "ocd-id": "ocd-division/country:us/state:nc/sldl:1",
- "voter-registration-authority-level": "string",
- "election-authority-level": "string",
- "voting-methods": [
- {
- "type": "by-mail",
- "primary": true,
- "ballot-request-form-url": {
- "en": "string",
- "es": "string"
}, - "ballot-request-deadline-received": "2019-08-24T14:15:22Z",
- "ballot-return-deadline-postmarked": "2019-08-24T14:15:22Z",
- "ballot-return-deadline-received": "2019-08-24T14:15:22Z",
- "ballot-return-deadline-in-person": "2019-08-24T14:15:22Z",
- "vbm-alias": {
- "en": "string",
- "es": "string"
}, - "excuse-required": true,
- "acceptable-forms": [
- {
- "name": "string"
}
]
}
], - "voter-registration-methods": [
- {
- "type": "by-mail",
- "instructions": {
- "signature": {
- "en": "string",
- "es": "string"
}, - "idnumber": {
- "en": "string",
- "es": "string"
}
}, - "acceptable-forms": [
- {
- "name": "string"
}
], - "deadline-received": "2019-08-24T14:15:22Z",
- "deadline-postmarked": "2019-08-24T14:15:22Z",
- "deadline-in-person": "2019-08-24T14:15:22Z",
- "new-voter": "string"
}
], - "primary-voting-method-source": "string"
}
], - "type": "congressional",
- "source": {
- "type": "string",
- "notes": "string",
- "date": "2019-08-24T14:15:22Z"
}, - "qa-status": "complete",
- "id": "string",
- "population": 0,
}
]