Delphi Epidata API

openapi: 3.0.3
info:
  title: Delphi Epidata 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: meta
  description: Service metadata and version.
- name: covidcast
  description: COVIDcast real-time indicator signals across geographies.
- name: fluview
  description: US ILINet influenza-like-illness surveillance (CDC FluView).
- name: forecasts
  description: Delphi's own nowcasts and forecasts.
paths:
  /version:
    get:
      tags: [meta]
      operationId: getVersion
      summary: Get the running Epidata API version
      description: >-
        Returns the deployed version of the Delphi Epidata service as a bare JSON object.
        This is the only endpoint that does NOT use the {epidata, result, message} envelope.
      responses:
        '200':
          description: Version of the running service.
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    type: string
                    example: 4.1.44
              example:
                version: 4.1.44
  /covidcast_meta/:
    get:
      tags: [covidcast, meta]
      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'
  /fluview/:
    get:
      tags: [fluview]
      operationId: getFluview
      summary: Query CDC FluView influenza-like-illness surveillance
      description: >-
        Returns ILINet outpatient influenza-like-illness records for the requested regions and
        epiweeks, including revision history via `issues`/`lag`. Both `regions` and `epiweeks`
        are required.
      parameters:
      - name: regions
        in: query
        required: true
        description: Comma-separated region identifiers, e.g. `nat`, `hhs1`, `pa`.
        schema: {type: string}
        example: nat
      - name: epiweeks
        in: query
        required: true
        description: Comma-separated epiweeks (YYYYWW) or ranges (`YYYYWW-YYYYWW`).
        schema: {type: string}
        example: '202001'
      - name: issues
        in: query
        required: false
        description: Restrict to specific report issues (epiweeks), for revision-aware analysis.
        schema: {type: string}
      - name: lag
        in: query
        required: false
        description: Return only the report published this many weeks after each epiweek.
        schema: {type: integer}
      responses:
        '200':
          description: ILI surveillance records, or an envelope carrying result -1/-2.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EpidataEnvelope'
              examples:
                nationalWeek202001:
                  $ref: '#/components/examples/FluviewRecord'
                missingParameter:
                  $ref: '#/components/examples/MissingParameter'
  /delphi/:
    get:
      tags: [forecasts]
      operationId: getDelphiForecast
      summary: Retrieve a Delphi in-house influenza forecast
      description: >-
        Returns the forecast produced by one of Delphi's own forecasting systems for a given
        epiweek. `system` selects the forecaster (e.g. `ec` for the Empirical Bayes / Epicast
        system); the forecast payload is a nested object of baselines and probability
        distributions per region.
      parameters:
      - name: system
        in: query
        required: true
        schema: {type: string}
        example: ec
      - name: epiweek
        in: query
        required: true
        schema: {type: integer}
        example: 201501
      responses:
        '200':
          description: Forecast envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EpidataEnvelope'
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
    FluviewRow:
      type: object
      description: One ILINet surveillance record as returned by /fluview/.
      properties:
        release_date: {type: string, format: date}
        region: {type: string}
        issue: {type: integer, description: Epiweek in which this revision was published.}
        epiweek: {type: integer}
        lag: {type: integer}
        num_ili: {type: integer}
        num_patients: {type: integer}
        num_providers: {type: integer}
        num_age_0: {type: integer}
        num_age_1: {type: integer}
        num_age_2: {type: integer}
        num_age_3: {type: integer}
        num_age_4: {type: integer}
        num_age_5: {type: integer}
        wili: {type: number, description: Weighted ILI percentage.}
        ili: {type: number, description: Unweighted ILI percentage.}
    CovidcastRow:
      type: object
      description: One COVIDcast observation as returned by /covidcast/.
      properties:
        geo_value: {type: string}
        signal: {type: string}
        source: {type: string}
        geo_type: {type: string}
        time_type: {type: string}
        time_value: {type: integer}
        direction: {type: integer, nullable: true}
        issue: {type: integer}
        lag: {type: integer}
        missing_value: {type: integer}
        missing_stderr: {type: integer}
        missing_sample_size: {type: integer}
        value: {type: number}
        stderr: {type: number, nullable: true}
        sample_size: {type: number, nullable: true}
  examples:
    FluviewRecord:
      summary: National ILI, epiweek 202001 (probed 2026-08-19)
      value:
        epidata:
        - release_date: '2021-10-08'
          region: nat
          issue: 202139
          epiweek: 202001
          lag: 91
          num_ili: 88731
          num_patients: 2394018
        result: 1
        message: success
    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
    MissingParameter:
      summary: Error returned with HTTP 200 (probed 2026-08-19)
      value:
        epidata: []
        message: 'missing parameter: need [epiweeks, regions]'
        result: -1