Skip to contents

Various COVID and flu signals via the COVIDcast endpoint

Source: R/endpoints.R
pub_covidcast.Rd

[Deprecated]

This is a V3/V4 endpoint. As of September 22, 2026, the V3 and V4 APIs no longer receive new data. They still serve the historical data they already have, but current data is only added to the V5 API, accessed via the epidata_snapshot(), epidata_archive(), and epidata_meta() functions. For more details on the changes, refer to vignette("migration-guide"), and visit the V5 signals documentation to see which sources are currently available.

API docs: https://cmu-delphi.github.io/delphi-epidata/api/covidcast_signals.html

Despite its name, this was Delphi's primary endpoint for much more than COVID-19 data: it also served influenza, wastewater, hospitalization, survey, and other signals from a wide variety of sources. See the API documentation link above for more. Delphi's COVIDcast public dashboard is powered by this endpoint. Use covidcast_epidata() to list the sources and signals it holds, and vignette("migration-guide") to find their V5 equivalents.

Usage

pub_covidcast(
  source,
  signals,
  geo_type,
  time_type,
  geo_values = "*",
  time_values = "*",
  ...,
  as_of = NULL,
  issues = NULL,
  lag = NULL,
  fetch_args = fetch_args_list()
)

Arguments

source

string. The data source to query (see: https://cmu-delphi.github.io/delphi-epidata/api/covidcast_signals.html).

signals

string. The signals to query from a specific source (see: https://cmu-delphi.github.io/delphi-epidata/api/covidcast_signals.html).

geo_type

string. The geographic resolution of the data (see: https://cmu-delphi.github.io/delphi-epidata/api/covidcast_geography.html).

time_type

string. The temporal resolution of the data (either "day" or "week", depending on signal).

geo_values

character. The geographies to return. Defaults to all ("*") geographies within requested geographic resolution (see: https://cmu-delphi.github.io/delphi-epidata/api/covidcast_geography.html.).

time_values

timeset. Dates or epiweeks to fetch. Supports epirange() and defaults to all ("*") dates.

...

not used for values, forces later arguments to bind by name

as_of

Date. Optionally, the as-of date for the issues to fetch. See the "Data Versioning" section for details.

issues

timeset. Optionally, the issue(s) of the data to fetch. See the "Data Versioning" section for details.

lag

integer. Optionally, the lag of the issues to fetch. See the "Data Versioning" section for details.

fetch_args

fetch_args_list(). Additional arguments to pass to fetch(). See fetch_args_list() for details.

Value

A tibble::tibble with one row per observation: one location at one time (and, for versioned data, one issue). The columns are the fields the endpoint returns; the API documentation linked at the top of the page describes what each one contains. The fetch_args argument controls the parsing, e.g. fields restricts the columns.

Data Versioning

Several endpoints support retrieving historical versions of the data. The following parameters control this and are mutually exclusive (only one can be provided at a time).

  • as_of: (Date) Retrieve the data as it was on this date.

  • issues: timeset Retrieve data from a specific issue date or range of dates.

  • lag: (integer) Retrieve data with a specific lag from its issue date.

If none of these is specified, the most recent version of the data is returned.

See vignette("versioned-data") for details and more ways to specify versioned data.

See also

pub_covidcast_meta(), covidcast_epidata(), epirange(), vignette("signal-discovery")

Examples


pub_covidcast(
  source = "jhu-csse",
  signals = "confirmed_7dav_incidence_prop",
  geo_type = "state",
  time_type = "day",
  geo_values = c("ca", "fl"),
  time_values = epirange(20200601, 20200801)
)
#> Warning: `pub_covidcast()` uses the V4 Epidata API.
#> ℹ As of September 22, 2026, V4 no longer receives new data. It still serves the
#>   historical data it already has, but for current data you must use the V5
#>   endpoints (`epidata_snapshot()`, `epidata_archive()`, `epidata_meta()`) with
#>   an up-to-date epidatr (and epiprocess, if you use it).
#> ℹ See `vignette("migration-guide")` (or
#>   <https://cmu-delphi.github.io/epidatr/articles/migration-guide.html>) for the
#>   endpoint, argument, and column mapping.
#> This warning is displayed once every 8 hours.
#> # A tibble: 124 × 15
#>    geo_value signal    source geo_type time_type time_value direction issue     
#>    <chr>     <chr>     <chr>  <fct>    <fct>     <date>         <dbl> <date>    
#>  1 ca        confirme… jhu-c… state    day       2020-06-01        NA 2023-03-10
#>  2 fl        confirme… jhu-c… state    day       2020-06-01        NA 2023-03-03
#>  3 ca        confirme… jhu-c… state    day       2020-06-02        NA 2023-03-10
#>  4 fl        confirme… jhu-c… state    day       2020-06-02        NA 2023-03-03
#>  5 ca        confirme… jhu-c… state    day       2020-06-03        NA 2023-03-10
#>  6 fl        confirme… jhu-c… state    day       2020-06-03        NA 2023-03-03
#>  7 ca        confirme… jhu-c… state    day       2020-06-04        NA 2023-03-10
#>  8 fl        confirme… jhu-c… state    day       2020-06-04        NA 2023-03-03
#>  9 ca        confirme… jhu-c… state    day       2020-06-05        NA 2023-03-10
#> 10 fl        confirme… jhu-c… state    day       2020-06-05        NA 2023-03-03
#> # ℹ 114 more rows
#> # ℹ 7 more variables: lag <dbl>, missing_value <dbl>, missing_stderr <dbl>,
#> #   missing_sample_size <dbl>, value <dbl>, stderr <dbl>, sample_size <dbl>
pub_covidcast(
  source = "jhu-csse",
  signals = "confirmed_7dav_incidence_prop",
  geo_type = "state",
  time_type = "day",
  geo_values = "*",
  time_values = epirange(20200601, 20200801)
)
#> # A tibble: 3,472 × 15
#>    geo_value signal    source geo_type time_type time_value direction issue     
#>    <chr>     <chr>     <chr>  <fct>    <fct>     <date>         <dbl> <date>    
#>  1 ak        confirme… jhu-c… state    day       2020-06-01        NA 2023-03-03
#>  2 al        confirme… jhu-c… state    day       2020-06-01        NA 2023-03-03
#>  3 ar        confirme… jhu-c… state    day       2020-06-01        NA 2023-03-03
#>  4 as        confirme… jhu-c… state    day       2020-06-01        NA 2023-03-03
#>  5 az        confirme… jhu-c… state    day       2020-06-01        NA 2023-03-03
#>  6 ca        confirme… jhu-c… state    day       2020-06-01        NA 2023-03-10
#>  7 co        confirme… jhu-c… state    day       2020-06-01        NA 2023-03-03
#>  8 ct        confirme… jhu-c… state    day       2020-06-01        NA 2023-03-03
#>  9 dc        confirme… jhu-c… state    day       2020-06-01        NA 2023-03-03
#> 10 de        confirme… jhu-c… state    day       2020-06-01        NA 2023-03-03
#> # ℹ 3,462 more rows
#> # ℹ 7 more variables: lag <dbl>, missing_value <dbl>, missing_stderr <dbl>,
#> #   missing_sample_size <dbl>, value <dbl>, stderr <dbl>, sample_size <dbl>