cast_api_queries: cast-API snapshot and archive queries

In epidatr: Client for Delphi's 'Epidata' API

cast-API snapshot and archive queries

Description

• 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. All signals are sent comma-joined in a single request per geo type (the cast-API only accepts one geo type 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, POSIXt, UTC timestamp string (e.g. "2025-10-16T13:45:00Z"), or NULL. The point in time to snapshot: returns the version of the data that was current then. 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	String or epirange(). A filter on the report_time column. Accepts comparison operators (e.g., "<2025-10-16", ">=2025-10-16", or "<=2025-10-16T13:45:00Z" for a UTC timestamp bound) or an epirange() for an inclusive date range. Bare dates and the "=" operator are not accepted: use snapshot_date for point-in-time data. 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.

See also

For example queries showing how to discover signals and build calls, see vignette("signal-discovery", package = "epidatr").

See Also

epidata_meta(), epirange()

epidatr documentation built on Sept. 21, 2026, 5:08 p.m.