Main Epidata API

This endpoint was previously known as COVIDcast.

This is the documentation for accessing Delphi’s COVID-19 indicators via the 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 which 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.

Get updates: Delphi operates a mailing list for users of the COVIDcast API. We will use the list to announce API changes, corrections to data, and new features; API users may also use the mailing list to ask general questions about its use. If you use the API, we strongly encourage you to subscribe.

Table of contents

  1. Main Epidata API
    1. Licensing
    2. Accessing the Data
    3. Data Sources and Signals
      1. COVIDcast Dashboard Signals
      2. All Available Sources and Signals

Licensing

Like all other Delphi Epidata datasets, our COVIDcast data is freely available to the public. However, our COVID-19 indicators include data from many different sources, with data licensing handled separately for each source. For a summary of the licenses used and a list of the indicators each license applies to, we suggest users visit our COVIDcast licensing page. Licensing information is also summarized on each indicator’s details page. We encourage academic users to cite the data if they use it in any publications. Our data ingestion code and API server code is open-source, and contributions are welcome. Further documentation on Delphi’s APIs is available in the API overview.

Accessing the Data

Our COVIDcast site provides an interactive visualization of a select set of the data signals available in the COVIDcast API, and provides a data export feature to download any data range as a CSV file.

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

from epidatpy import EpiDataContext, EpiRange

epidata = EpiDataContext()
apicall = epidata.pub_covidcast(
    data_source="fb-survey",
    signals="smoothed_cli",
    geo_type="county",
    time_type="day",
    geo_values="*",
    time_values=EpiRange(20200501, 20200507),
)
data = apicall.df()

library(epidatr)

data <- pub_covidcast('fb-survey', 'smoothed_cli', 'county', 'day', geo_values = '06001',
                     time_values = c(20200401, 20200405:20200414))

The API clients have extensive documentation providing further examples.

Alternatively, to manually construct URLs and parse responses to access data, refer to this section.

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.

Delphi’s COVID-19 indicators data includes the following data sources. Data from most of these sources is typically updated daily. You can use the covidcast_meta endpoint to get summary information about the ranges of the different attributes for the different data sources.

The API for retrieving data from these sources is described in the COVIDcast endpoint documentation. Changes and corrections to data from this endpoint are listed in the changelog.

To obtain many of these signals and update them daily, Delphi has written extensive software to obtain data from various sources, aggregate the data, calculate statistical estimates, and format the data to be shared through the COVIDcast endpoint of the Delphi Epidata API. This code is open source and available on GitHub, and contributions are welcome.

COVIDcast Dashboard Signals

The following signals are currently displayed on the public COVIDcast dashboard:

Kind Name Source Signal
Public Behavior People Wearing Masks fb-survey smoothed_wwearing_mask_7d
Public Behavior Vaccine Acceptance fb-survey smoothed_wcovid_vaccinated_appointment_or_accept
Public Behavior COVID Symptom Searches on Google google-symptoms sum_anosmia_ageusia_smoothed_search
Early Indicators COVID-Like Symptoms fb-survey smoothed_wcli
Early Indicators COVID-Like Symptoms in Community fb-survey smoothed_whh_cmnty_cli
Early Indicators COVID-Related Doctor Visits doctor-visits smoothed_adj_cli
Cases and Testing COVID Cases jhu-csse confirmed_7dav_incidence_prop
Late Indicators COVID Hospital Admissions hhs confirmed_admissions_covid_1d_prop_7dav
Late Indicators Deaths jhu-csse deaths_7dav_incidence_prop

All Available Sources and Signals

Beyond the signals available on the COVIDcast dashboard, numerous other signals are available through our data export tool or directly through the API.

Table of contents