openapi: 3.2.0
info:
  title: Democracy Works Ballot Measures 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 key of that header should be lowercase. 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: Ballot Measures
paths:
  /ballot-measures:
    get:
      operationId: getBallotMeasure
      summary: Ballot Measure
      description: 'Information on the ballot measures on the ballot, including a summary and the full text of the ballot measure.

        '
      security:
      - ApiKeyAuth: []
      parameters:
      - name: id
        in: path
        schema:
          type: string
          description: Hash identifier of the ballot measure to get.
          example: bm_b2897f4f799485eaba40901bc0ed38310dc8211a
        required: true
      responses:
        '200':
          description: Ballot measure fetched by query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ballotMeasure'
              examples:
                sampleBallotMeasureResponse:
                  $ref: '#/components/examples/ballotMeasures'
        '400':
          $ref: '#/components/responses/badRequestError'
        '404':
          description: Not Found Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors'
              example:
                status: 404
                message:
                - Ballot Measure not found.
        '429':
          $ref: '#/components/responses/tooManyRequestsError'
        '500':
          $ref: '#/components/responses/internalServerError'
      tags:
      - Ballot Measures
components:
  examples:
    ballotMeasures:
      summary: Sample ballotMeasure response
      description: 'This is **fictional** data to provide examples of fields values.

        '
      value:
        data:
          ballotMeasures:
            id: bm_b2897f4f799485eaba40901bc0ed38310dc8211a
            name: Yreka, California, Measure V, Sales Tax Measure (November 2024)
            shortName: Measure V
            streamlinedName: Yreka, California, Measure V, Sales Tax Measure
            districtName: Yreka
            districtType: cityTown
            type: Referral
            topics:
            - Local electoral systems
            - Local elections and campaigns
            topicAreas:
            - Law Enforcement
            - Taxes
            summary: Authorize an additional sales tax of 1% with revenue dedicated to public safety services
            yesVote: <p>A “yes” vote supported authorizing an additional sales tax of 1% with revenue dedicated to public safety services.</p>
            yesVoteTotal: 1655
            noVote: <p>A “no” vote opposed authorizing an additional sales tax of 1% with revenue dedicated to public safety services.</p>
            noVoteTotal: 1458
            ballotQuestion: I<p>MEASURE V</p><p>To maintain and improve essential city services, including local firefighting and emergency medical response; hire and train firefighters; upgrade/replace aging firefighting safety equipment, life-saving tools and an outdated fire station, shall an ordinance be adopted to impose a one percent sales tax providing approximately 2.4 million dollars annually for general government use, until ended by the voters, with independent audits and all funds staying local</p><p>YES_________ NO__________</p>"
            ocdId: ocd-division/country:us/state:ca/place:yreka
            status: approved
            endorsementYesCount: 1
            endorsementNoCount: 0
  responses:
    badRequestError:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errors'
          example:
            status: 400
            message:
            - Something has gone wrong parsing your request. 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.
    internalServerError:
      description: InternalServerError
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errors'
          example:
            status: 500
            message:
            - Something went wrong.
    tooManyRequestsError:
      description: TooManyRequestsError
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/gatewayErrors'
          example:
            message: Too Many Requests
  schemas:
    ballotMeasure:
      description: Information on the ballot measures on the ballot, including a summary and the full text of the ballot measure.
      type: object
      required:
      - id
      - name
      - shortName
      - districtName
      - districtType
      - type
      - topics
      - summary
      - yesVote
      - noVote
      - ocdId
      properties:
        id:
          type: string
          description: The ID of the ballot measure.
        name:
          type: string
          description: The name of the ballot measure.
        shortName:
          type: string
          description: The concise name of the ballot measure.
        streamlinedName:
          type: string
          description: The ballot measure name without reference to the state name or year.
        districtName:
          type: string
          description: The name of the district covered by the ballot measure.
        districtType:
          type: string
          description: The type of district relevant to the ballot measure.
          enum:
          - cityTown
          - cityTownSubdivision
          - congress
          - county
          - countySubdivision
          - judicialDistrict
          - judicialDistrictSubdivision
          - schoolDistrict
          - schoolDistrictSubdivision
          - specialDistrict
          - specialDistrictSubdivision
          - state
          - stateLegislativeLower
          - stateLegislativeUpper
          - stateSubdivision
          - township
        type:
          type: string
          description: The type of ballot measure.
        topics:
          type: array
          items:
            type: string
          description: An array of topics covered by a ballot measure.
        topicAreas:
          type: array
          items:
            type: string
          description: 'An array of topic areas covered by a ballot measure.


            `Localized`

            '
        summary:
          type: string
          description: Describes a summary of the ballot measure.
        yesVote:
          type: string
          description: Describes what a vote supporting the ballot measure means.
        noVote:
          type: string
          description: Describes what a vote opposed to the ballot measure means.
        yesVotesTotal:
          type: number
          description: The number of YES votes this ballot measure received.
        noVotesTotal:
          type: number
          description: The number of NO votes this ballot measure received.
        ballotQuestion:
          type: string
          description: The full text of the ballot measure.
        ocdId:
          type: string
          description: The OCD-ID associated with the jurisidiction covered by the ballot measure.
        status:
          type: string
        endorsementYesCount:
          type: number
          description: The number of "support" endorsements for this ballot measure.
        endorsementNoCount:
          type: number
          description: The number of "oppose" endorsements for this ballot measure
    errors:
      type: object
      properties:
        status:
          type: integer
        message:
          type: array
      required:
      - status
      - message
    gatewayErrors:
      type: object
      properties:
        message:
          type: string
      required:
      - message
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY