openapi: 3.2.0
info:
  title: Delphi Epidata Covidcast API
  version: 4.1.44
  description: 'Public, anonymously accessible HTTP/JSON API operated by the Delphi research group at Carnegie Mellon University, serving real-time and historical epidemiological surveillance data. Delphi is a CMU research group (Machine Learning Department / Herbert A. Simon building, delphi.cmu.edu) and a former CDC Center of Excellence for Influenza Forecasting. The API is a single-host, query-parameter-driven surface: every endpoint is a GET under /epidata/, every response is a JSON envelope of {epidata, result, message}, and `result` carries Delphi''s own status convention (1 = success, -2 = no results, -1 = bad request) rather than relying on the HTTP status code alone. CMU publishes no OpenAPI, GraphQL schema or machine-readable contract for this API; this document was derived from live probes and from the prose documentation at cmu-delphi.github.io/delphi-epidata.'
  termsOfService: https://cmu-delphi.github.io/delphi-epidata/
  contact:
    name: Carnegie Mellon University — Delphi Research Group
    url: https://delphi.cmu.edu/
  license:
    name: See Delphi Epidata data-source licensing
    url: https://cmu-delphi.github.io/delphi-epidata/api/covidcast_licensing.html
  x-operator: institution
  x-operator-evidence: 'servers[] api.delphi.cmu.edu is a host under Carnegie Mellon University''s own registrable domain, cmu.edu. The API''s landing page at https://api.delphi.cmu.edu/epidata/ titles itself "DELPHI Epidata API" and links to github.com/cmu-delphi/delphi-epidata; the cmu-delphi GitHub organization is named "Delphi" with blog https://delphi.cmu.edu/. No vendor host, vendor contact or vendor terms appear anywhere on the surface. Probed 2026-08-19: /epidata/version 200 application/json {"version":"4.1.44"}; /epidata/covidcast_meta/ 200; /epidata/fluview/?regions=nat&epiweeks=202001 200; /epidata/covidcast/ with a full parameter set 200; /epidata/delphi/?system=ec&epiweek=201501 200.'
  x-provenance:
    generated: '2026-08-19'
    method: derived
    source: Live probes of https://api.delphi.cmu.edu/epidata/ on 2026-08-19 (five endpoints, real payloads captured into examples/), reconciled against the prose documentation at https://cmu-delphi.github.io/delphi-epidata/ and https://cmu-delphi.github.io/delphi-epidata/api/covidcast.html.
    authorship: Written by API Evangelist, not published by Carnegie Mellon University. CMU ships no machine-readable contract for this API — /epidata/openapi.json, /epidata/openapi.yaml, /epidata/openapi and /epidata/swagger.json all returned 404 on 2026-08-19, and no openapi.yaml exists in the cmu-delphi/delphi-epidata repository.
    coverage: Five of the roughly forty Delphi Epidata endpoints are modelled here — the ones actually probed. The signal-source endpoints (nowcast, flusurv, dengue_nowcast, wiki, ght, quidel, sensors, nidss_*, ecdc_ili, kcdc_ili, paho_dengue, norostat and the rest) share the same envelope and parameter idiom but were not individually probed and are deliberately absent rather than assumed.
servers:
- url: https://api.delphi.cmu.edu/epidata
  description: Production — Delphi Epidata API, operated by Carnegie Mellon University
tags:
- name: covidcast
  description: COVIDcast real-time indicator signals across geographies.
paths:
  /covidcast_meta/:
    get:
      tags:
      - covidcast
      operationId: getCovidcastMeta
      summary: List every available COVIDcast signal and its coverage
      description: Returns one record per (data_source, signal, time_type, geo_type) combination available through the COVIDcast endpoint, with the date range, number of locations and summary statistics for each. This is the catalog a client reads before calling /covidcast/.
      responses:
        '200':
          description: Signal catalog.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EpidataEnvelope'
  /covidcast/:
    get:
      tags:
      - covidcast
      operationId: getCovidcast
      summary: Query a COVIDcast signal for a geography and time range
      description: Returns observations of one signal from one data source, for one geographic resolution and a set of time values. All five parameters are required; omitting any of them returns HTTP 200 with result -1 and a "missing parameter" message.
      parameters:
      - name: data_source
        in: query
        required: true
        description: Signal source identifier, e.g. `jhu-csse`, `fb-survey`, `doctor-visits`.
        schema:
          type: string
        example: jhu-csse
      - name: signal
        in: query
        required: true
        description: Signal name within the data source.
        schema:
          type: string
        example: confirmed_incidence_num
      - name: time_type
        in: query
        required: true
        schema:
          type: string
          enum:
          - day
          - week
        example: day
      - name: geo_type
        in: query
        required: true
        description: Geographic resolution.
        schema:
          type: string
          enum:
          - county
          - hrr
          - msa
          - dma
          - state
          - hhs
          - nation
        example: state
      - name: time_values
        in: query
        required: true
        description: One or more dates as YYYYMMDD (day) or YYYYWW (week); ranges use `start-end`, lists use commas.
        schema:
          type: string
        example: '20200601'
      - name: geo_value
        in: query
        required: true
        description: Geographic identifier at the requested resolution, or `*` for all.
        schema:
          type: string
        example: pa
      responses:
        '200':
          description: Signal observations, or an envelope carrying result -1/-2.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EpidataEnvelope'
              examples:
                observations:
                  $ref: '#/components/examples/CovidcastObservation'
components:
  schemas:
    EpidataEnvelope:
      type: object
      description: The response envelope every Delphi Epidata endpoint except /version uses. Note that errors are returned with HTTP 200 and signalled in `result` — a client keying only on the HTTP status will read a failed request as a success.
      required:
      - epidata
      - result
      - message
      properties:
        epidata:
          type: array
          description: The result rows; shape varies by endpoint. Empty on error or no-match.
          items:
            type: object
            additionalProperties: true
        result:
          type: integer
          description: Delphi status code. 1 = success, -2 = no results matched, -1 = bad or missing parameters. Not an HTTP status.
          enum:
          - 1
          - -1
          - -2
        message:
          type: string
          description: '`success`, `no results`, or a human-readable parameter error.'
          example: success
  examples:
    CovidcastObservation:
      summary: JHU-CSSE confirmed incidence, Pennsylvania, 2020-06-01 (probed 2026-08-19)
      value:
        epidata:
        - geo_value: pa
          signal: confirmed_incidence_num
          source: jhu-csse
          geo_type: state
          time_type: day
        result: 1
        message: success