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:

• 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.

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.