Delphi’s COVIDcast API

This is the documentation for accessing the Delphi’s COVID-19 Surveillance Streams (covidcast) endpoint of Delphi’s epidemiological data API. This API provides data on the spread and impact of the COVID-19 pandemic across the United States, most of which is available at the county level and updated daily. This data powers our public COVIDcast map, and includes testing, cases, and death data, as well as unique healthcare and survey data Delphi acquires through its partners. The API allows users to select specific signals and download data for selected geographical areas—counties, states, metropolitan statistical areas, and other divisions.

This data is freely available under our licensing terms; we encourage academic users to cite the data if they use it in any publications. Further documentation on Delphi’s APIs is available in the API overview.

Accessing the API

Several API clients are available for common programming languages, so you do not need to construct API calls yourself. Once you install the appropriate client for your programming language, accessing data is as easy as, in R:

library(covidcast)

data <- covidcast_signal("fb-survey", "smoothed_cli", start_day = "2020-05-01",
                         end_day = "2020-05-07")

or, in Python:

import covidcast
from datetime import date

data = covidcast.signal("fb-survey", "smoothed_cli", date(2020, 5, 1), date(2020, 5, 7),
                        "county")

The API clients have extensive documentation providing further examples.

Alternately, to construct URLs and parse responses to access data manually, see below for details.

Data Sources and Signals

The API provides multiple data sources, each with several signals. Each source represents one provider of data, such as a medical testing provider or a symptom survey, and each signal represents one quantity computed from data provided by that source. Our sources provide detailed data about COVID-related topics, including confirmed cases, symptom-related search queries, hospitalizations, outpatient doctor’s visits, and other sources. Many of these are publicly available only through the COVIDcast API.

The signals documentation describes all available sources and signals. Furthermore, our COVIDcast site provides an interactive visualization of a select set of these data signals.

Constructing API Queries

The COVIDcast API is based on HTTP GET queries and returns data in JSON form. The base URL is https://api.covidcast.cmu.edu/epidata/api.php. The covidcast endpoint is https://api.covidcast.cmu.edu/epidata/api.php?source=covidcast.

See this documentation for details on specifying epiweeks, dates, and lists.

Parameters

Required

The current set of signals available for each data source is returned by the covidcast_meta endpoint.

Optional

Estimates for a specific time_value and geo_value are sometimes updated after they are first published. Many of our data sources issue corrections or backfill estimates as data arrives; see the documentation for each source for details.

The default API behavior is to return the most recently issued value for each time_value selected.

We also provide access to previous versions of data using the optional query parameters below.

Use cases:

• To pretend like you queried the API on June 1, such that the returned results do not include any updates that became available after June 1, use as_of=20200601.
• To retrieve only data that was published or updated on June 1, and exclude records whose most recent update occured earlier than June 1, use issues=20200601.
• To retrieve all data that was published between May 1 and June 1, and exclude records whose most recent update occured earlier than May 1, use issues=20200501-20200601. The results will include all matching issues for each time_value, not just the most recent.
• To retrieve only data that was published or updated exactly 3 days after the underlying events occurred, use lag=3.

You should specify only one of these three parameters in any given query.

Note: Each issue in the versioning system contains only the records that were added or updated during that time unit; we exclude records whose values remain the same as a previous issue. If you have a research problem that would require knowing when an unchanged value was last confirmed, please get in touch.

Response

Note: result code 2, “too many results”, means that the number of results you requested was greater than the API’s maximum results limit. Results will be returned, but not all of the results you requested. API clients should check the results code, and should consider breaking up their requests across multiple API calls, such as by breaking a request for a large time interval into multiple requests for smaller time intervals.

Example URLs

Facebook Survey CLI on 2020-04-06 to 2010-04-10 (county 06001)

https://api.covidcast.cmu.edu/epidata/api.php?source=covidcast&data_source=fb-survey&signal=raw_cli&time_type=day&geo_type=county&time_values=20200406-20200410&geo_value=06001

{
  "result": 1,
  "epidata": [
    {
      "geo_value": "06001",
      "time_value": 20200407,
      "direction": null,
      "value": 1.1293550689064,
      "stderr": 0.53185454111042,
      "sample_size": 281.0245
    },
    ...
  ],
  "message": "success"
}

Facebook Survey CLI on 2020-04-06 (all counties)

https://api.covidcast.cmu.edu/epidata/api.php?source=covidcast&data_source=fb-survey&signal=raw_cli&time_type=day&geo_type=county&time_values=20200406&geo_value=*

{
  "result": 1,
  "epidata": [
    {
      "geo_value": "01000",
      "time_value": 20200406,
      "direction": null,
      "value": 1.1693378,
      "stderr": 0.1909232,
      "sample_size": 1451.0327
    },
    ...
  ],
  "message": "success"
}

Table of contents

• API Clients
• Data Sources and Signals
• Signal Changelog
• Geographic Coding
• Metadata
• Inactive Signals