cast-API snapshot and archive queries

epidata_snapshot fetches a snapshot of signals as they appeared at a specific date (or the latest available if snapshot_date is omitted).
epidata_archive fetches the full version history of signals across all available issues.
epidata is a wrapper that routes to one of the above based on which versioning argument is supplied.

For a source's signals, geo types, and extra key columns, see its API docs, e.g. NWSS: https://cmu-delphi.github.io/delphi-epidata/api/v5-signals/nwss.html.

Usage

epidata_snapshot(
  source,
  signals,
  geo_type,
  geo_values = "*",
  reference_time = "*",
  time_values = lifecycle::deprecated(),
  ...,
  fill_method = NULL,
  snapshot_date = NULL,
  as_of = lifecycle::deprecated(),
  fetch_args = fetch_args_list()
)

epidata_archive(
  source,
  signals,
  geo_type,
  geo_values = "*",
  reference_time = "*",
  time_values = lifecycle::deprecated(),
  ...,
  fill_method = NULL,
  report_time = "*",
  issues = lifecycle::deprecated(),
  fetch_args = fetch_args_list()
)

epidata(
  source,
  signals,
  geo_type,
  geo_values = "*",
  reference_time = "*",
  time_values = lifecycle::deprecated(),
  ...,
  fill_method = NULL,
  snapshot_date = NULL,
  as_of = lifecycle::deprecated(),
  report_time = NULL,
  issues = lifecycle::deprecated(),
  fetch_args = fetch_args_list()
)

Arguments

source: string. The data source to query (e.g., "nssp", "nhsn"). Use epidata_meta() to discover available sources.
signals: character vector. One or more signals to query for the given source; comma-joined strings (e.g., "sig1,sig2") are also accepted. Use epidata_meta() to discover available signals. A separate API request is made per signal and geo type (the cast-API only accepts one of each per request) and the results are combined.
geo_type: character vector. One or more geography types to query (e.g., "state", "nation", "county"); comma-joined strings are also accepted. Use epidata_meta() to discover available geo types for a given source and 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.).
reference_time: timeset. Reference time to return (filters on the reference_time column). Supports individual dates or epirange(). Defaults to all ("*"). Filtered locally after the API call.
time_values: Use reference_time instead.
...: Named filters on extra key columns beyond geo_value, such as pcr_target = "sars-cov-2" or sample_index = c("a", "b"). Each key accepts one or more values (matched as OR) and is sent server-side via the extra_keys API parameter to shrink the download. Passing more than 10 values for a key warns. Unlike
fill_method: string. Optional filter to an imputation method. The API provides alternatives of the same signal differing in how nulls were handled during geographic aggregation: "source" means no imputation or aggregation (raw source data), "fill_ave" fills nulls with the average of neighboring values, and "fill_zero" fills nulls with zero. NULL (default) returns all fill methods.
snapshot_date: Date or NULL. The snapshot date; NULL returns the latest available version.
as_of: Use snapshot_date instead.
fetch_args: fetch_args_list(). Additional arguments to pass to fetch(). See fetch_args_list() for details.
report_time: Date, string, or epirange(). A query on the report_time column for the archive endpoint. Supports exact dates (e.g., "2025-10-16"), operators (e.g., "<2025-10-16"), or an epirange(). Internally maps to the report_time_query API parameter.
issues: Use report_time instead.

Value

tibble::tibble

Data Versioning

epidata supports two mutually exclusive versioning arguments. Pass snapshot_date to retrieve data as it appeared on a specific date, or report_time to query the archive by when data was reported. If neither is supplied, epidata returns the latest available snapshot.

Empty results

An invalid geo_type or signals value for the given source raises an error (class epidatr__epidata__invalid_geo_type or epidatr__epidata__invalid_signals respectively), looked up via epidata_meta(). Otherwise, an empty result warns rather than failing silently: a warning of class epidatr__empty_signals if only some of the requested signals returned no data, or epidatr__empty_result if the whole query came back empty (whether because the server had no matching rows, or because the local geo_values/reference_time filters dropped everything the server returned). Pass fetch_args_list(return_empty = TRUE) to suppress these errors and warnings and get an empty tibble back instead.