The Delphi Epidata API provides real-time access to epidemiological surveillance data for influenza, COVID-19, and other diseases from official government sources such as the Centers for Disease Control and Prevention (CDC) and Google Trends, and private partners such as Meta and Change Healthcare. To learn more about the Meta partnership, check out this article. It is built and maintained by the Carnegie Mellon University Delphi Research Group.
This package is designed to streamline the downloading and usage of data
from the Delphi Epidata API. It provides a simple R interface to the
API, including functions for downloading data, parsing the results, and
converting the data into a tidy format. The package can also fetch the
full historical record of a signal, including corrections and updates,
which is particularly useful for accurately backtesting forecasting
models. It can also fetch accessory data associated with a signal, such
as source-specific metadata, via epidata_aux(). We also provide
packages for downstream data processing
(epiprocess) and modeling
(epipredict).
# Install the CRAN version
pak::pkg_install("epidatr")
# Install the development version from the GitHub dev branch
pak::pkg_install("cmu-delphi/epidatr@dev")
Our CRAN listing is here.
The Delphi API requires a (free) API key for full functionality. To
generate your key, register for a pseudo-anonymous account
here and
see more discussion on the general API
website.
The epidatr client will automatically look for this key in the
environment variable DELPHI_EPIDATA_KEY. We recommend storing your key
in your .Renviron file, which R will read by default.
Note that for the time being, any private endpoints (i.e. those prefixed
with pvt) will require a separate key that needs to be passed as an
argument.
To get started with epidatr, see vignette("epidatr") or the Getting
Started
guide.
library(epidatr)
# Discover what a source offers: signals, geo types, and date ranges
meta <- epidata_meta(source = "nssp")
meta$signals
#> [1] "pct_ed_visits_ari" "pct_ed_visits_combined"
#> [3] "pct_ed_visits_covid" "pct_ed_visits_influenza"
#> [5] "pct_ed_visits_rsv" "smoothed_pct_ed_visits_combined"
#> [7] "smoothed_pct_ed_visits_covid" "smoothed_pct_ed_visits_influenza"
#> [9] "smoothed_pct_ed_visits_rsv"
# Fetch the latest snapshot of NSSP influenza ED visit percentages by state
flu <- epidata_snapshot(
source = "nssp",
signals = "pct_ed_visits_influenza",
geo_type = "state"
)
flu
#> # A tibble: 10,557 × 7
#> signal report_time geo_type geo_value fill_method reference_time value
#> <chr> <date> <chr> <chr> <chr> <date> <dbl>
#> 1 pct_ed_visit… 2026-06-26 state ak source 2022-10-01 0.140
#> 2 pct_ed_visit… 2026-06-26 state ak source 2022-10-08 0.240
#> 3 pct_ed_visit… 2026-06-26 state ak source 2022-10-15 0.320
#> 4 pct_ed_visit… 2026-06-26 state ak source 2022-10-22 0.760
#> 5 pct_ed_visit… 2026-06-26 state ak source 2022-10-29 1.16
#> 6 pct_ed_visit… 2026-06-26 state ak source 2022-11-05 1.94
#> 7 pct_ed_visit… 2026-06-26 state ak source 2022-11-12 3.73
#> 8 pct_ed_visit… 2026-06-26 state ak source 2022-11-19 6.82
#> 9 pct_ed_visit… 2026-06-26 state ak source 2022-11-26 8.67
#> 10 pct_ed_visit… 2026-06-26 state ak source 2022-12-03 9.85
#> # ℹ 10,547 more rows
This is just a glimpse of what epidatr can do. See the
Articles for
walkthroughs of specific tasks (finding signals, understanding versioned
data, migrating from pub_covidcast()), and the
Reference for the
full list of functions and their arguments.
The Delphi Epidata API provides access through three generations of endpoints:
epidata_snapshot(), epidata_archive(), and epidata_meta().pub_covidcast() is deprecated and stopped receiving
new data on September 22, 2026. It remains available to query
historical data ingested before that date.pub_fluview(), pub_gft(), and
pub_wiki()) cover specific datasets that are static or no longer
updated. Some stopped receiving new data on September 22, 2026 when
active sources moved to V5, while others stopped updating earlier.If you have existing pub_covidcast() code, see
vignette("migration-guide") for the argument and column mapping to the
V5 functions.
If you are migrating existing workflows, there are two transitions to keep in mind:
covidcast package to epidatr. The standalone covidcast
package is
deprecated and superseded by epidatr, which is a complete rewrite
offering better speed, reliability, and broader endpoint support.epidatr,
pub_covidcast() and other V3/V4 endpoints are deprecated as of
September 22, 2026. See the migration
guide
(or vignette("migration-guide")). New code should use the current V5
functions (epidata_snapshot(), epidata_archive(), and
epidata_meta()).You should consider subscribing to the API mailing list to be notified of package updates, new data sources, corrections, and more.
If you use epidatr or data from the Delphi Epidata API in your work,
please cite the package using
citation("epidatr").
If you use data that originated from the COVIDcast project (whether
accessed via V5 endpoints or pub_covidcast()), please include the
COVIDcast
citation
as well.
Certain data sources have specific attribution and licensing terms. See the Epidata data licensing documentation and the COVIDcast licensing documentation for information about citing specific datasets.
Warning: If you use data from the Epidata API to power a product, dashboard, app, or other service, please download the data you need and store it centrally rather than making API requests for every user. Our server resources are limited and cannot support high-volume interactive use.
See also the Terms of Use, noting that the data is a research product and not warranted for a particular purpose.