Democracy Works Exports API

openapi: 3.0.2
info:
  title: Democracy Works Exports 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: Exports
paths:
  /exports:
    get:
      operationId: getExports
      summary: Exports
      description: '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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html).

        '
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Exports fetched by query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/export'
              examples:
                sampleExportsRespose:
                  $ref: '#/components/examples/exports'
      tags:
      - Exports
components:
  examples:
    exports:
      summary: Sample exports response
      description: 'This is **fictional** data to provide examples of fields values.

        '
      value:
        exportName: /example/path/to/export<client_name>_supplemental_data.json
        exportPath: https://example_presigned_url.s3.us-west-2.amazonaws.com/file.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=temporary_credential&X-Amz-Date=20180210T171315Z&X-Amz-Expires=3600&X-Amz-Signature=abc123&X-Amz-SignedHeaders=host
  schemas:
    export:
      description: A representation of an export.
      type: object
      properties:
        exportName:
          type: string
          description: Provides the name of the export file.
        exportPath:
          type: string
          description: Provides a presigned URL to a file in AWS s3 containing data in JSON format.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key