API docs by Redocly

Democracy Works API (2.0)

Download OpenAPI specification:

Introduction

The Democracy Works Elections API provides your application with comprehensive elections data and voting guidance, surfacing our unparalleled coverage of upcoming local, state, and federal elections. Power your platforms, apps, reminders, outreach campaigns, and much more.

Join the community of developers in our Google Group for updates about our data and elections.

Authentication

Access to the Democracy Works Elections API requires authentication. To access the DW API, include an x-api-key header with each API request. The key of that header should be lowercase. The value of that header should be your API key. For example:

curl "https://api.democracy.works/v2/elections" \
    --header "x-api-key: <YOUR API KEY>"

For pricing information and to obtain a test key, please contact us.

Base URL

The base URL for all API endpoints is: https://api.democracy.works/v2

Support

If you have any further questions or issues, please contact us at partnerships@democracy.works.

Data

Data is captured in two entities, an Election and an Authority. The Election has election-specific dates and deadlines, URLs for voters to get more information and take action, and detailed guidance in both English and Spanish. The Authority includes statewide evergreen information and instructions on how to register and vote for each state, as well as election office contact information.

Open Civic Data IDs (OCD-IDs)

We use Open Civic Data IDs (OCD-IDs) throughout the API to describe entities and filter results.

OCD-IDs start with what is being identified, and in our case it is always ocd-division.

Since all authorities are, or are contained within, a state and all elections are run by some authority, almost every OCD-ID in our system starts with ocd-division/country:us/state:__, where __ is a two-letter state postal code.

The only exception to this is for the District of Columbia, which has the OCD-ID ocd-division/country:us/district:dc.

OCD-ID on the Authority

The OCD-ID associated with an authority describes the political district covered by an authority. Authorities are uniquely identifiable by the associated OCD-ID.

For example:

  • The OCD-ID ocd-division/country:us/state:ak/place:anderson is associated with the authority for Anderson, Alaska.
  • The OCD-ID ocd-division/country:us/state:ny/county:albany/council_district:2 is not associated with an authority because Albany's 2nd Ward is a legislative ward which does not run its own elections.

OCD-ID on the Election

The OCD-ID associated with an election describes the highest-level district in which all voters have something to vote for on the ballot on Election Day. Elections always have an associated OCD-ID, but are not uniquely identifiable by the associated OCD-ID.

For example:

  • If there is a mayoral race in Philadelphia as well as a state-wide measure contest in Pennsylvania on a given day, there will be one election entity with OCD-ID ocd-division/country:us/state:pa.
  • If there is only a mayoral race in Pittsburgh in Allegheny County on a given day, there will be an election entity with OCD-ID ocd-division/country:us/state:pa/county:allegheny.

Standard Parameters

Functionality shared between API endpoints is noted here. Each endpoint will specify whether it supports the following functionality.

Pagination

Any endpoint that returns multiple results supports pagination. An endpoint that supports pagination accepts two related query parameters:

  • pageSize
    • Specifies the number of results requested. Defaults to 10 if not specified. The maximum value is 100.
    • Example: pageSize=15
  • page
    • Specifies the page to return, based on pageSize. Defaults to 1 if not specified.
    • Example: page=2

You can send none, one, or both of these parameters. Each endpoint that supports pagination will have a pagination field in the response, which details what page of information is returned, what page size was used for the request, and the total number of results found.

Localization

Some endpoints support localization. An endpoint that supports localization accepts a header parameter:

  • Accept-Language
    • Specifies the language tag for localization. Accepted values are en, en-US, es, and es-US.
    • Example: Accept-Language: es

Not all fields on the response of a localized endpoint are localized. Each field that supports localization will have a Localized tag on its field description.

If no localization in the requested language is found, localized fields will return null.

Content Formatting

Some endpoints support content formatting. An endpoint that supports formatting accepts a query parameter:

  • contentFormatType
    • Specifies the format of certain fields in the response. Accepted values are html and json. Defaults to html if not specified.
    • Example: contentFormatType=json

Not all fields on the response of a formatted endpoint are formatted. Formatting is generally supported on prose-like fields, including Question and Answer content and most instruction fields. Each field that supports formatting will have a Formatted tag on its field description.

The json-formatted content is the content represented as an AST.

Fields

Some endpoints support field masking to specify a list of fields to include in the API response. This helps to avoid unnecessary computation and improve performance. An endpoint that supports field masking accepts a query parameter:

  • fields
    • Specifies the symbolic field paths to include in the response, provided as comma-separated list. See more about Field Masks.
    • Example: fields="ocdId,date,contact.email"

Paths are validated against all possible fields, and providing an invalid path will result in a 400 response.

State authorities

This endpoint includes statewide evergreen information and instructions on how to register and vote for each state (and Washington, D.C.). It includes contact information for state election authorities, registration methods, voting methods, state-specific URLs to authoritative government websites, and more.

Authorities do not contain election-specific information such as dates, and while we closely monitor this data for changes and update when needed, Authorities information generally does not change from election to election.

Authorities are returned sorted alphabetically by OCD-ID.

Supports standard the following parameters: see Pagination, Localization, and Content Formatting.

Authorizations:
ApiKeyAuth
path Parameters
stateCode
string
Example: ny

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

If no value is provided, it will request all top-level authorities (51 total). If a value is provided, at most one authority will be returned.

query Parameters
includeQuestionAndAnswer
boolean
Example: includeQuestionAndAnswer=true

Whether Question and Answer content should be included for each returned election. Defaults to false if not specified. Response fields are formattable with the content formatting standard parameter.

Responses

Response samples

Content type
application/json

This is fictional data to provide examples of fields values.

The first authority has all fields populated for demonstration purposes.

The second authority is a more realistic example which shows that not all fields are applicable to every authority.

{
  • "data": {
    },
  • "pagination": {
    }
}

All authorities

This endpoint includes all statewide and local authorities that correspond to a given address or state parameter.

The statewide authorities include evergreen information and guidance on how to register and vote in that state, as well as contact information for state election authorities. Local authorities provide contact information for the local election office.

Authorities do not contain election-specific information such as dates, and while we closely monitor this data for changes and update when needed, Authorities information generally does not change from election to election.

Authorities are returned sorted alphabetically by OCD-ID.

Supports the following standard parameters: see Pagination, Localization, and Content Formatting.

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

includeQuestionAndAnswer
boolean
Example: includeQuestionAndAnswer=true

Whether Question and Answer content should be included for each returned election. Defaults to false if not specified. Response fields are formattable with the content formatting standard parameter.

Responses

Response samples

Content type
application/json

This is fictional data to provide examples of fields values.

The first authority is a state authority with all fields populated for demonstration purposes.

The second authority is a local authority.

Note that state and local authorities will both be returned by this endpoint; local authorities will only return required fields, plus an extra isRegistrationContact field that is not returned on state authorities.

{
  • "data": {
    },
  • "pagination": {
    }
}

Local authorities

This endpoint provides contact information for over 8,500 local election offices at the county and municipal levels.

Authorities are returned sorted alphabetically by OCD-ID.

Supports the following standard parameters: see Pagination and Localization.

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

Responses

Response samples

Content type
application/json

This is fictional data to provide examples of fields values.

{
  • "data": {
    },
  • "pagination": {
    }
}

Elections

This endpoint has election-specific dates and deadlines, URLs for voters to get more information and take action, and detailed guidance in both English and Spanish. 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 state authority. The default is to return all elections, though you can limit the response to upcoming elections through the use of the start date parameter. Elections are returned sorted chronologically by election date.

After an election is confirmed to be occurring, Democracy Works surfaces information about an election as details become available. An election’s guidance phase describes the state of the currently available guidance.

A past election is an election whose election date is in the past. A known election is an upcoming election for which key details and deadlines have yet to be released. An active election is an upcoming election for which details have been vetted and confirmed by the Democracy Works team.

Elections are returned sorted chronologically by election date.

Supports the following standard parameters: see Pagination, Localization, Content Formatting, and Fields.

Ballot Measure Information

In 2025, information about measures on the ballot will include::

  • All federal ballot measures
  • All statewide ballot measures
  • Local ballot measures in the top 100 cities by population

Ballot measure information is not included in the default response for an election. For ballot measure information to be included with the response, include the includeBallotData parameter with a value of true.

Ballot data is sourced from Ballotpedia.

Candidate and Contest Information

In 2025, information about contests and candidates on the ballot will include:

  • All federal contests and candidates, including senate and house of representatives
  • All state contests and candidates, including governor, treasurer, secretary of state, state legislative seats, state supreme court, district court, and court of appeals
  • Local contests and candidates including mayor, county judge, county clerk, commissioners, and city councils in the top 100 cities by population, plus school board elections in 475 districts
    • Note that local coverage may be limited by mapping constraints.

Ballot data is sourced from Ballotpedia.

Authorizations:
ApiKeyAuth
query Parameters
address
string
Example: address=813%20Howard%20Street%20Oswego%20NY%2013126

If sending an address as a single string, the street, city, state, and zip code of an address to get elections for. Using separate parameters for each address element (as shown below) is preferred.

addressStreet
string
Example: addressStreet=813%20Howard%20Street

The street to get elections for in conjunction with other required address parameters. Include Apt numbers or other additional information.

addressCity
string
Example: addressCity=Oswego

The city to get elections for in conjunction with other required address parameters.

addressStateCode
string
Example: addressStateCode=NY

The 2 letter postal code to get elections for in conjunction with other required address parameters. DC is also accepted.

addressZip
string
Example: addressZip=13126

The zip code to get elections for in conjunction with other required address parameters.

addressZip4
string
Example: addressZip4=9029

OPTIONAL. The zip plus 4 to get elections for in conjunction with other required address parameters.

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(s) of a political division; elections that apply to a voter in this political division will be returned. This parameter may be provided multiple times to return all elections with any of the OCD IDs provided.

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.

electionTypes
string

The election types (options are presidentialPrimary, state, stateSenate, stateHouse, congressional, senate, county, subCounty, municipal, subMunicipal, school, and special). Comma-separated list.

includeQuestionAndAnswer
boolean
Example: includeQuestionAndAnswer=true

Whether Question and Answer content should be included for each returned election. Defaults to false if not specified. Response fields are formattable with the content formatting standard parameter.

includeBallotData
boolean
Example: includeBallotData=true

Whether ballot data (ballot measures, candidates, and contests) should be included for each returned election. Defaults to false if not specified.

Responses

Response samples

Content type
application/json

This is fictional data to provide examples of fields values.

The first election has all fields populated for demonstration purposes.

The second election is a more realistic example which shows that not all fields are applicable to every election.

{
  • "data": {
    },
  • "pagination": {
    }
}

Ballot Measure

Information on the ballot measures on the ballot, including a summary and the full text of the ballot measure.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Example: bm_b2897f4f799485eaba40901bc0ed38310dc8211a

Hash identifier of the ballot measure to get.

Responses

Response samples

Content type
application/json

This is fictional data to provide examples of fields values.

{
  • "data": {
    }
}

Candidate

This endpoint gets one candidate by id.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Example: can_6669354db52bcd7c83d732ffa7e006a81aabba0e

Hash identifier of the candidate to get.

Responses

Response samples

Content type
application/json

This is fictional data to provide examples of fields values.

{}

Contest

This endpoint gets one contest by id.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Example: co_682d473ab8a590c2f1ed2d4fd8dd11c49a44b62f

Hash identifier of the contest to get.

Responses

Response samples

Content type
application/json

This is fictional data to provide examples of fields values.

{
  • "data": {
    }
}

Endorsement

This endpoint gets one endorsement by endorsement id.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Example: ben_682d473ab8a590c2f1ed2d4fd8dd11c49a44b62f

Hash identifier of the endorsement to get.

Responses

Response samples

Content type
application/json
Example

This is fictional data to provide examples of fields values.

{
  • "id": "ben_92800009b57ea6d51a701ebaec4ce10be78494f3",
  • "type": "Organization",
  • "name": "Name of the Organization",
  • "source": "website",
  • "position": "yes"
}

Endorsement Bulk

This endpoint a list of endorsements by ballot measure or candidate id.

You may not provide an ballot measure and candidate id at the same time. No endorsement is associated with both a ballot measure & candidate.

Supports the following standard parameters: see Pagination.

Authorizations:
ApiKeyAuth
query Parameters
candidateId
string
Example: candidateId=can_682d473ab8a590c2f1ed2d4fd8dd11c49a44b62f

Hash identifier of a candidate, returns all endorsements associated with this candidate.

ballotMeasureId
string
Example: ballotMeasureId=bm_682d473ab8a590c2f1ed2d4fd8dd11c49a44b62f

Hash identifier of a ballot measure, returns all endorsements associated with this allot measure.

Responses

Response samples

Content type
application/json
Example

This is fictional data to provide examples of fields values.

{
  • "data": [
    ],
  • "pagination": {
    }
}

Exports

This endpoint serves presigned URLs to flat files on AWS S3. It supports no parameters.

To set up a bulk data export, contact partnerships@democracy.works.

Presigned URLs are temporary and expire after one hour. Download the file promptly after requesting a URL. If a URL expires before you can download your file, request a new one from this endpoint.

Presigned URLs grant access to your data. Do not share these URLs with any party that should have access to this data.

Learn more about Working with presigned URLs on AWS.

Authorizations:
ApiKeyAuth

Responses

Response samples