Centers for Disease Control and Prevention SODA v3 API

openapi: 3.2.0
info:
  title: CDC Socrata Open Data API (data.cdc.gov) SODA v2.1 SODA v3 API
  description: 'REST/JSON access to hundreds of CDC datasets published on data.cdc.gov via

    the Socrata SODA (Socrata Open Data API) platform. Each dataset is

    addressed by an eight-character dataset identifier and supports filtering,

    aggregation, and pagination through SoQL query parameters. Anonymous use

    is allowed at throttled rates; an application token (passed via the

    X-App-Token header or $$app_token query parameter) raises limits. SODA v3

    additionally supports authenticated user requests for non-public datasets.

    Generated as a best-effort spec from public Socrata documentation; verify

    against https://dev.socrata.com/docs/endpoints.html before production use.

    '
  version: '2.1'
  contact:
    name: CDC Open Data
    url: https://data.cdc.gov/
  license:
    name: CC0 Public Domain (most CDC datasets)
    url: https://creativecommons.org/publicdomain/zero/1.0/
servers:
- url: https://data.cdc.gov
  description: CDC Open Data portal (Socrata SODA).
- url: https://chronicdata.cdc.gov
  description: CDC Chronic Data portal (PLACES, BRFSS, 500 Cities).
security:
- appToken: []
- {}
tags:
- name: SODA v3
  description: Next-generation query and export endpoints.
paths:
  /api/v3/views/{dataset_id}/query.json:
    get:
      tags:
      - SODA v3
      summary: Query a dataset (SODA v3, GET)
      description: Query endpoint with v3 options and machine-readable response.
      operationId: queryDatasetV3Get
      parameters:
      - $ref: '#/components/parameters/DatasetId'
      - $ref: '#/components/parameters/Query'
      - $ref: '#/components/parameters/AppTokenQuery'
      responses:
        '200':
          description: Query result rows.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
    post:
      tags:
      - SODA v3
      summary: Query a dataset (SODA v3, POST)
      description: Preferred method for longer queries. Body is SoQL/$query payload.
      operationId: queryDatasetV3Post
      parameters:
      - $ref: '#/components/parameters/DatasetId'
      - $ref: '#/components/parameters/AppTokenQuery'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  description: SoQL query.
                includeSynthetic:
                  type: boolean
        description: SoQL query payload.
      responses:
        '200':
          description: Query result rows.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
  /api/v3/views/{dataset_id}/export.{format}:
    get:
      tags:
      - SODA v3
      summary: Export a dataset (human-readable)
      operationId: exportDatasetV3
      parameters:
      - $ref: '#/components/parameters/DatasetId'
      - in: path
        name: format
        required: true
        schema:
          type: string
          enum:
          - json
          - csv
          - geojson
          - xml
      - $ref: '#/components/parameters/AppTokenQuery'
      responses:
        '200':
          description: Exported dataset.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
            text/csv:
              schema:
                type: string
            application/vnd.geo+json:
              schema:
                type: object
        '404':
          $ref: '#/components/responses/Error'
components:
  parameters:
    AppTokenQuery:
      in: query
      name: $$app_token
      schema:
        type: string
      description: Socrata application token (alternative to X-App-Token header).
    Query:
      in: query
      name: $query
      schema:
        type: string
      description: Full SoQL query, overriding individual $select/$where/etc.
    DatasetId:
      in: path
      name: dataset_id
      required: true
      schema:
        type: string
        pattern: ^[a-z0-9]{4}-[a-z0-9]{4}$
        example: vbim-akqf
      description: Eight-character dataset identifier (four-four with a dash).
  responses:
    Error:
      description: Error response.
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: string
              error:
                type: boolean
              message:
                type: string
              data:
                type: object
  securitySchemes:
    appToken:
      type: apiKey
      in: header
      name: X-App-Token
      description: 'Socrata application token. Anonymous use is allowed at throttled rates;

        an app token raises rate limits. May also be supplied as the

        $$app_token query parameter.

        '