openapi: 3.0.2
info:
title: Democracy Works Elections API
version: '2.0'
description: "# Introduction\n\nThe 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.\n\nJoin the community of developers in our [Google Group](https://groups.google.com/a/democracy.works/g/democracy-works-data)\nfor updates about our data and elections.\n\n## Authentication\nAccess to the Democracy Works Elections API requires authentication. To access the DW API, include an X-API-Key header with each API request. The value of that header should be your API key. For example:\n\n```sh\ncurl \"https://api.democracy.works/v2/elections\" \\\n --header \"X-API-KEY: <YOUR API KEY>\"\n```\n\nFor pricing information and to obtain a test key, please [contact us](https://data.democracy.works/api-signup).\n\n## Base URL\nThe base URL for all API endpoints is: https://api.democracy.works/v2\n\n## Support\nIf you have any further questions or issues, please contact us at partnerships@democracy.works.\n\n## Data\n\nData 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. \n\n# Open Civic Data IDs (OCD-IDs)\n\nWe use Open Civic Data IDs [(OCD-IDs)](https://opencivicdata.info/en/latest/ocdids.html) \nthroughout the API to describe entities and filter results. \n\nOCD-IDs start with what is being identified, and in our case it is always \n`ocd-division`.\n\nSince all authorities are, or are contained within, a state and all elections \nare run by some authority, almost every OCD-ID in our system starts with \n`ocd-division/country:us/state:__`, where `__` is a two-letter state postal code.\n\nThe only exception to this is for the District of Columbia, which has the OCD-ID \n`ocd-division/country:us/district:dc`.\n\n## OCD-ID on the Authority\nThe OCD-ID associated with an authority describes the political district covered\nby an authority. Authorities are uniquely identifiable by the associated OCD-ID.\n\nFor example:\n- The OCD-ID `ocd-division/country:us/state:ak/place:anderson` is associated \n with the authority for Anderson, Alaska.\n- The OCD-ID `ocd-division/country:us/state:ny/county:albany/council_district:2` \n is not associated with an authority because Albany's 2nd Ward is a legislative \n ward which does not run its own elections.\n\n## OCD-ID on the Election\nThe OCD-ID associated with an election describes the highest-level district \nin which all voters have something to vote for on the ballot on Election Day. \nElections always have an associated OCD-ID, but are not uniquely\nidentifiable by the associated OCD-ID.\n\nFor example:\n- If there is a mayoral race in Philadelphia as well as a state-wide \nmeasure contest in Pennsylvania on a given day, there will be one election \nentity with OCD-ID `ocd-division/country:us/state:pa`.\n- If there is only a mayoral race in Pittsburgh in Allegheny County on a given \nday, there will be an election entity with OCD-ID \n`ocd-division/country:us/state:pa/county:allegheny`.\n\n# Standard Parameters\nFunctionality shared between API endpoints is noted here. Each endpoint will\nspecify whether it supports the following functionality.\n\n## Pagination\nAny endpoint that returns multiple results supports pagination. An endpoint that \nsupports pagination accepts two related query parameters:\n- `pageSize`\n - Specifies the number of results requested. Defaults to 10 if not specified. The maximum value is 100.\n - Example: `pageSize=15`\n- `page`\n - Specifies the page to return, based on `pageSize`. Defaults to 1 if not specified.\n - Example: `page=2`\n\nYou can send none, one, or both of these parameters. Each endpoint that supports\npagination will have a `pagination` field in the response, which details what\npage of information is returned, what page size was used for the request, and the\ntotal number of results found. \n\n## Localization\nSome endpoints support localization. An endpoint that supports localization accepts a\nheader parameter:\n- `Accept-Language`\n - Specifies the language tag for localization. Accepted values are `en`, `en-US`, `es`, and `es-US`.\n - Example: `Accept-Language: es`\n\nNot all fields on the response of a localized endpoint are localized. Each field that supports localization\nwill have a `Localized` tag on its field description.\n\nIf no localization in the requested language is found,\nlocalized fields will return `null`.\n\n## Content Formatting\nSome endpoints support content formatting. An endpoint that supports formatting accepts a\nquery parameter:\n- `contentFormatType`\n - Specifies the format of certain fields in the response.\n Accepted values are `html` and `json`. Defaults to `html` if not specified.\n - Example: `contentFormatType=json`\n\nNot all fields on the response of a formatted endpoint are formatted. \nFormatting is generally supported on prose-like fields, including Question and Answer content and most instruction fields.\nEach field that supports formatting will have a `Formatted` tag on its field description.\n\nThe `json`-formatted content is the content represented as an [AST](https://en.wikipedia.org/wiki/Abstract_syntax_tree).\n\n## Fields\nSome 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\nquery parameter:\n- `fields`\n - Specifies the symbolic field paths to include in the response, provided as comma-separated list. See more about [Field Masks](https://protobuf.dev/reference/protobuf/google.protobuf/#field-mask).\n - Example: `fields=\"ocdId,date,contact.email\"`\n\nPaths are validated against all possible fields, and providing an invalid path will result in a 400 response.\n"
servers:
- url: https://api.democracy.works/v2
tags:
- name: Elections
paths:
/elections:
get:
operationId: getElections
summary: Elections
description: "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. \n\nAfter an election is confirmed to be occurring, Democracy Works surfaces information about an election as details become available. An elections guidance phase describes the state of the currently available guidance.\n\nA `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.\n\nElections are returned sorted chronologically by election date. \n\nSupports the following standard parameters: see __[Pagination](#section/Standard-Parameters/Pagination)__, __[Localization](#section/Standard-Parameters/Localization)__, __[Content Formatting](#section/Standard-Parameters/Content-Formatting)__, and __[Fields](#section/Standard-Parameters/Fields)__.\n\n### Ballot Measure Information\n\nInformation about measures on the ballot are available for the following elections:\n- All federal elections\n- All statewide elections\n\nBallot 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`.\n\nBallot data is sourced from [Ballotpedia](https://ballotpedia.org/).\n\n### Candidate and Contest Information\n\nFor the November 5, 2024 elections, our ballot information will include the following:\n- All federal contests and candidates, including president, vice president, senate, and house of representatives\n- All state contests and candidates, including governor, treasurer, secretary of state, state legislative seats, state supreme court, district court, and court of appeals\n- Local candidates and contests including mayor, county judge, county clerk, commissioners, and city councils in the top 100 cities by population, plus state capitals and school board elections in 475 districts\n - Local coverage may be limited by mapping constraints and in states where primaries have not yet been held.\n\nBallot data is sourced from [Ballotpedia](https://ballotpedia.org/).\n"
security:
- ApiKeyAuth: []
parameters:
- name: address
in: query
schema:
type: string
description: 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.
example: 813%20Howard%20Street%20Oswego%20NY%2013126
required: false
- name: addressStreet
in: query
schema:
type: string
description: The street to get elections for in conjunction with other required address parameters. Include Apt numbers or other additional information.
example: 813%20Howard%20Street
required: false
- name: addressCity
in: query
schema:
type: string
description: The city to get elections for in conjunction with other required address parameters.
example: Oswego
required: false
- name: addressStateCode
in: query
schema:
type: string
description: The 2 letter postal code to get elections for in conjunction with other required address parameters. DC is also accepted.
example: NY
required: false
- name: addressZip
in: query
schema:
type: string
description: The zip code to get elections for in conjunction with other required address parameters.
example: '13126'
required: false
- name: addressZip4
in: query
schema:
type: string
description: OPTIONAL. The zip plus 4 to get elections for in conjunction with other required address parameters.
example: '9029'
required: false
- name: stateCode
in: query
schema:
type: string
description: The 2-letter postal code to get elections within a respective state. DC is accepted as well.
example: CA
required: false
- name: ocdId
in: query
schema:
type: string
description: 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.
example: ocd-division%2Fcountry%3Aus%2Fstate%3Any%2Fcounty%3Akings
required: false
- name: startDate
in: query
schema:
type: date
description: The earliest date to get elections for, inclusive, in UTC ISO 8601 format.
example: '2023-01-01'
required: false
- name: endDate
in: query
schema:
type: date
description: The latest date to get elections for, inclusive, in UTC ISO 8601 format.
example: '2023-01-02'
required: false
- name: includeQuestionAndAnswer
in: query
schema:
type: boolean
description: 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](#section/Standard-Parameters/Content-Formatting)__ standard parameter.
example: true
required: false
- name: includeBallotData
in: query
schema:
type: boolean
description: Whether ballot data (ballot measures, candidates, and contests) should be included for each returned election. Defaults to false if not specified.
example: true
required: false
responses:
'200':
description: Elections fetched by query.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
elections:
type: array
items:
$ref: '#/components/schemas/election'
statewideOnly:
type: boolean
description: Unable to determine elections more granular than the state level. Only state level elections returned.
pagination:
$ref: '#/components/schemas/pagination'
examples:
sampleElectionsResponse:
$ref: '#/components/examples/elections'
'400':
$ref: '#/components/responses/badRequestError'
'429':
$ref: '#/components/responses/tooManyRequestsError'
'500':
$ref: '#/components/responses/internalServerError'
tags:
- Elections
components:
responses:
tooManyRequestsError:
description: TooManyRequestsError
content:
application/json:
schema:
$ref: '#/components/schemas/gatewayErrors'
example:
message: Too Many Requests
internalServerError:
description: InternalServerError
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
example:
status: 500
message:
- Something went wrong.
badRequestError:
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
example:
status: 400
message:
- Something has gone wrong parsing your query string. Please refer to our documentation at https://developers.democracy.works/api/v2 to confirm all required fields are present and all fields are formatted correctly.
schemas:
candidate:
description: A representation of a candidate.
type: object
required:
- id
- fullName
- firstName
- lastName
- partyAffiliation
- isWriteIn
properties:
id:
type: string
description: The ID of the candidate.
fullName:
type: string
description: The full name of the candidate.
firstName:
type: string
description: The first name of the candidate.
lastName:
type: string
description: The last name of the candidate.
partyAffiliation:
type: array
description: Describes the party affiliation of the candidate.
items:
type: string
ballotpediaUrl:
type: string
status:
type: string
isWriteIn:
type: boolean
description: Indicates whether a candidate is a write-in candidate.
runningMateFullName:
type: string
runningMateTitle:
type: string
contact:
type: object
properties:
campaign:
type: object
properties:
email:
type: string
description: The candidates campaign email address.
website:
type: string
description: The candidates campaign website.
facebook:
type: string
description: The candidates campaign Facebook.
twitter:
type: string
description: The candidates campaign Twitter.
instagram:
type: string
description: The candidates campaign Instagram.
youtube:
type: string
description: The candidates campaign YouTube.
mailingAddress:
type: string
description: The candidates campaign mailing address.
phone:
type: string
description: The candidates campaign phone number.
personal:
type: object
properties:
website:
type: string
description: The candidates personal website.
facebook:
type: string
description: The candidates personal Facebook.
twitter:
type: string
description: The candidates personal Twitter.
instagram:
type: string
description: The candidates personal Instagram.
youtube:
type: string
description: The candidates personal YouTube.
linkedIn:
type: string
description: The candidates personal LinkedIn.
pagination:
type: object
properties:
totalRecordCount:
type: number
description: Total records found for the given query.
currentPage:
type: number
description: The page of records returned.
pageSize:
type: number
description: The number of records returned.
election:
description: A representation of an election.
type: object
required:
- description
- date
- ocdId
properties:
ocdId:
type: string
description: Provides the [OCD-ID](https://opencivicdata.info/en/latest/ocdids.html) associated with the office.
createdAt:
type: string
description: ISO 8601 timestamp of when the election was first created in Democracy Works' internal database.
updatedAt:
type: string
description: ISO 8601 timestamp of when the election was last updated in Democracy Works' internal database.
date:
type: string
description: Date of the election in YYYY-MM-DD format.
description:
type: string
description: 'The election name which includes the jurisdiction affected by the election and a descriptor of the election type.
`Localized`
'
type:
type: string
description: Provides the election type.
enum:
- congressional
- county
- municipal
- presidentialPrimary
- school
- state
- stateHouse
- stateSenate
- subMunicipal
pollingLocationUrl:
type: string
description: Lookup URL for voting location information. If an election is all-mail, this URL will link to information for election-specific dropbox locations.
canonicalUrl:
type: string
description: 'Provides a URL to the Democracy Works data source for attribution purposes. Attribution allows voters to assess the reliability and provenance of election data and guidance.
`Localized`
'
website:
type: string
description: 'Provides a URL for voters to access additional information on the upcoming election, when available.
`Localized`
'
guidancePhase:
type: string
description: 'After an election is confirmed to be occurring, Democracy Works surfaces information about an election as details become available. An elections 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 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.
'
enum:
- past
- known
- active
population:
type: string
description: Provides the affected population number for the given election using Census data or government data. This field will be null if the population is less than 5,000.
voting:
type: object
properties:
inPersonVotingAvailable:
type: boolean
description: Indicates whether an election has options to vote in person.
mailBallotsSentAutomatically:
type: boolean
description: Indicates whether ballots are sent to eligible registered voters automatically in an election without voters having to request ballots themselves.
early:
type: object
properties:
url:
type: string
description: Provides website for voters to find out more about when and where to vote early in a specific election or provides general information about the early voting process if available.
startDate:
type: string
description: Provides the date when early voting or absentee in person voting begins for the election in YYYY-MM-DD format if early voting or absentee in person voting is available in the election. If in person absentee voting starts as ballots are available, as opposed to a specific start date, this field will be blank and only voting.early.endDate will be returned.
endDate:
type: string
description: Provides the date when early voting or absentee in person voting ends for the election in YYYY-MM-DD format if early voting or absentee in person voting is available in the election.
varies:
type: boolean
description: Indicates whether early voting dates are consistent across locations and whether early voting is available every day between when early voting starts and when early voting ends.
byMail:
type: object
properties:
idInstructions:
type: string
description: Provides election-specific instructions for voters who choose to vote by mail.
explainerUrl:
type: string
description: 'Provides a URL where voters can learn more about voting by mail.
`Localized`
'
allMail:
type: object
properties:
ballotInfoUrl:
type: string
description: Provides a URL where voters can learn more about their ballot in an all mail election.
ballotSendStartDate:
type: string
description: Provides the date in which a state will start to send mail ballots to all registered voters in an all mail election. Not collected for most all mail elections.
ballotSendEndDate:
type: string
description: Provides the date in which a state will finish sending mail ballots to all registered voters in an all mail election. Not collected for most all mail elections.
ballotReceiveExpectedStartDate:
type: string
description: Provides the date in which states expect voters to start receiving their mail ballots in an all mail election. Not collected for most all mail elections.
ballotReceiveExpectedEndDate:
type: string
description: Provides the date in which states expect voters to have received their mail ballots in an all mail election. Not collected for most all mail elections.
deadline:
type: object
properties:
postmarkedOrReceived:
type: string
description: Provides the deadline type for whether the the voted ballot needs to be postmarked by or received by the ballot return deadline. Only collected for specific elections.
receivedNoLaterThan:
type: object
properties:
date:
type: string
description: Provides the last date that the election office can receive a voted ballot in the mail if the return deadline has a "must be postmarked by YYYY-MM-DD if received by YYYY-MM-DD" deadline. Only collected for specific elections.
timestamp:
type: string
description: Provides the ISO timestamp deadline for the last day for the election office to receive a voted ballot in the mail if the return deadline has a "must be postmarked by YYYY-MM-DD if received by YYYY-MM-DD" deadline. Only collected for specific elections.
description:
type: string
description: Provides the time deadline on the last day the election office can receive a voted ballot in the mail if the return deadline is expressed in a "must be postmarked by YYYY-MM-DD if received by YYYY-MM-DD" format if the time deadline is expressed in a phrase instead of an ISO timestamp. Examples could include "close of business" or "close of polls". Only collected for specific elections.
returnInPerson:
type: object
properties:
date:
type: string
description: Provides the date deadline to return a voted ballot in person. Only collected for specific elections.
timestamp:
type: string
description: Provides the ISO timestamp deadline to return a voted ballot in person. Not collected for most elections.
description:
type: string
description: 'Provides the time deadline to return a voted ballot in person if the deadline is expressed in a phrase instead of an ISO timestamp. Examples include "close of business" or "close of polls". Not collected for most elections.
`Localized`
'
returnByMail:
type: object
properties:
date:
type: string
description: Provides the deadline date to return a voted ballot in the mail. Only collected for specific elections.
timestamp:
type: string
description: Provides the ISO timestamp deadline to return a voted ballot in the mail on the last day to return a voted ballot. Not collected for most elections.
description:
type: string
description: 'Provides the time deadline to return a voted ballot in the mail on the last day to return a voted ballot if the deadline is expressed in a phrase and not in an ISO timestamp. Examples include "close of business" or "close of polls". Only collected for specific elections.
`Localized`
'
ballotRequest:
type: object
properties:
postmarkedOrReceived:
type: string
description: Provides the deadline type for the deadline to request a ballot by mail. Types include postmarked or received. Only collected for specific elections.
date:
type: string
description: Provides the last date to request a ballot by mail for the election. If there are different deadlines for submitting an application in-person and by-mail, this is the by-mail application request deadline. All mail elections in which all voters receive a ballot in the mail will not have a ballot request deadline.
timestamp:
type: string
description: Provides the ISO timestamp deadline date to request a ballot by mail for the election on the last day voters are able to do so. This time deadline is not collected for most elections.
description:
type: string
description: 'Provides the time deadline to request a ballot by mail if the deadline is described by a phrase and not by an ISO timestamp. Examples include "close of business" or "close of polls". Only collected for specific elections.
`Localized`
'
inPerson:
type: object
properties:
idRequiredAllVoters:
type: boolean
description: Indicates whether an ID is required for all voters.
idInstructions:
type: string
description: Provides the election-specific instructions to vote in person including what identification voters may need to show at the voting location for states that have a voting.predominantMethod of byMail.
electionDay:
type: object
properties:
closing:
type: object
properties:
timestamp:
type: string
description: Provides the ISO timestamp that in person voting closes on Election Day. Only collected for specific elections.
description:
type: string
description: 'Provides time of day deadline that indicates when in person voting closes on Election Day when the deadline is expressed in a phrase as opposed to an ISO timestamp. Examples include "close of business" or "close of polls". Only collected for specific elections.
`Localized`
'
registration:
type: object
properties:
explainerUrl:
type: string
description: 'Provides a URL where voters can learn more about registering to vote.
`Localized`
'
inPerson:
type: object
properties:
atPollingPlaceOnElectionDay:
type: boolean
description: Defines whether election day registration is available for the election at all voting locations. If election day registration takes place at a location other than the voting location, this field will be "false".
localSamedayRegistrationAuthorityLookupUrl:
type: string
description: Provides a URL where voters can look up the authority with which they can register to vote on election day.
deadline:
type: object
properties:
date:
type: string
description: Provides the deadline date to register in-person at the local election office for the election.
timestamp:
type: string
# --- truncated at 32 KB (94 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/democracy-works/refs/heads/main/openapi/democracy-works-elections-api-openapi.yml