API docs by Redocly

Democracy Works API (2.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 "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",
        ...

OCD-IDs on the Authority

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.

Get state authority.

Gets authorities within the given state (or DC).

Authorizations:
ApiKeyAuth
path Parameters
stateCode
required
string
Example: ny

The 2-letter postal code of the state to get authorities for. DC is accepted as well.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get authorities.

Gets authorities based on the provided filter. At most one of ocdId, address, or stateCode can be provided.

Authorizations:
ApiKeyAuth
query Parameters
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, *, can be passed as the value to request all state-level authorities and DC (51 total).

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.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "pagination": {
    }
}

Get elections.

Gets elections based on provided filters. Providing more than one query parameter will join them with AND logic.

Authorizations:
ApiKeyAuth
query Parameters
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.

header Parameters
Accept-Language
string
Example: es

The language tag for localization. Accepted values are en, en-US, es, and es-US.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "pagination": {
    }
}