The Delphi Epidata API provides real-time access to epidemiological surveillance data for influenza, COVID-19, and other diseases from both official government sources such as the Centers for Disease Control and Prevention (CDC), private partners such as Facebook (now Meta) and Change Healthcare, and other public datasets like Google Trends. 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 API stores a historical record of all data, including corrections and updates, which is particularly useful for accurately backtesting forecasting models. We also provide packages for downstream data processing (epiprocess) and modeling (epipredict).
library(epidatr)
# Discover what a source offers: signals, geo types, and date ranges
meta <- epidata_meta(source = "nssp")
meta$nssp$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,353 × 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,343 more rowsThe Delphi Epidata API has three generations of endpoints, and this package has client functions for all of them:
epidata_snapshot(),
epidata_archive(), and epidata_meta(). Start
here; sources are moving to v5 one at a time.pub_covidcast(). Still
carries the sources that have not moved to v5 yet.pub_*
functions (e.g. pub_fluview(), pub_gft()), one
per dataset. Most of these datasets are static or no longer updated;
they remain available for historical work.If you have existing pub_covidcast() code, see
vignette("migration-guide") for the argument and column
mapping to the v5 functions.
Installing the package is straightforward.
# 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, the private endpoints (i.e. those
prefixed with pvt) will require a separate key that needs
to be passed as an argument.
The covidcast package is deprecated and will no longer
be updated. The epidatr package is a complete rewrite of
the covidcast
package, with a focus on speed, reliability, and ease of use. It
also supports more endpoints and data sources than
covidcast. When migrating from that package, you will need
to use the pub_covidcast
function in epidatr.
You should consider subscribing to the API mailing list to be notified of package updates, new data sources, corrections, and other updates.
We request that if you use the epidatr package in your
work, or use any of the data provided by the Delphi Epidata API through
non-covidcast endpoints, that you cite us using the
citation given by citation("epidatr").
If you use any of the data from the covidcast endpoint,
please use the COVIDcast
citation as well. See the COVIDcast
licensing documentation and the licensing
documentation for other endpoints for information about citing the
datasets provided by the API.
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.