Democracy Works API (1.0.0)

Download OpenAPI specification:Download

Overview

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.

Getting Started

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.

Open Civic Data IDs (OCD IDs)

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.

OCD-IDs on the Election

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.

OCD-IDs on the Authority

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.

State Authorities

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:

  • Contact information (address, phone, homepage URL, etc.)
  • voter-registration-status-url so voters can look up there registration status
  • local-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.

Dates as Timestamps

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.

Instructions

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..."}}

QA Status

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.

State authority URLs

curl -H "Accept: application/json" \
  -H "Authorization: apikey $YOUR_API_KEY" \
  "https://api.democracy.works/election-authorities/state-urls/ny"

URLs are not required, and their availability depends on the state. The Authority lookup URLs may be the same, depending on the state.

path Parameters
stateAbbreviation
required
string
Example: ny

The lowercase abbreviation of the state you want to retrieve information for.

Responses

Response samples

Content type
application/json
{}

All state authorities (contact information)

curl -H "Accept: application/json" \
  -H "Authorization: apikey $YOUR_API_KEY" \
  "https://api.democracy.works/election-authorities/states"

The response will be an object with a list of Authorities. Each Authority will have a district-division, but we recommend that you disregard and get that information from the Election. As a reminder, the Election will have voter-registration-methods and the voting-methods copied from the State and Local Authorities for the methods offered in that particular Election, along with dates and deadlines. The only thing the district-division has that the Election does not is the voter-registration-status-url, which would be simpler to obtain from the “State URLs” resource.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Upcoming elections

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:

  1. all at once
  2. one (or more) OCD-ID(s) at a time

Be sure to include the Accept header because the default Content-Type is the lesser known EDN (application/edn). The two Content-Types supported are application/json and application/edn.

All Upcoming Elections

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

Upcoming Elections by OCD-ID

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"
query Parameters
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 (en) and Spanish (es). Use this parameter to receive instructions in a single language.

You may also use all to receive instructions in both English and Spanish. Note that this changes the structure of the response; any field which supports localized instructions will be an object keyed by all supported languages, exemplified by the following JSON fragment:

{"instructions": {"en": "...", "es": "..."}}
qa-status
string
Default: "complete"
Enum: "incomplete" "complete" "all"

See QA Status for a more in-depth discussion of the meaning of this parameter.

header Parameters
Accept
string
Enum: "application/json" "application/edn"
Authorization
string
Example: apikey $YOUR_API_KEY

Responses

Response samples

Content type
application/json
[
  • {
    }
]