Fetch V5 auxiliary data

Fetch auxiliary data associated with a cast signal.

You can pass a source string to fetch the auxiliary data directly. Alternatively, you can pass the output of epidata_snapshot() or epidata_archive(). In this case, epidata_aux automatically retrieves the source from the object, fetches the matching auxiliary data, and performs a version-aware left join onto the base data.

For the auxiliary key columns and their allowed values, see the source's API docs, e.g. NWSS: https://cmu-delphi.github.io/delphi-epidata/api/v5-signals/nwss.html.

Usage

epidata_aux(source, ...)

# Default S3 method
epidata_aux(
  source,
  ...,
  reference_time = "*",
  time_values = lifecycle::deprecated(),
  snapshot_date = NULL,
  report_time = "*",
  issues = lifecycle::deprecated(),
  columns = NULL,
  fetch_args = fetch_args_list()
)

# S3 method for class 'data.frame'
epidata_aux(source, ..., columns = NULL, fetch_args = fetch_args_list())

Arguments

source

A source string to retrieve auxiliary data directly, or a tibble returned by epidata_snapshot() or epidata_archive() to merge the data onto (its source is recovered automatically).

...

Named filters on the auxiliary key columns, such as pcr_target = "sars-cov-2" or geo_value = c("ca", "ny"). Each key accepts one or more values (matched as OR); they are serialized as repeated key:value terms server-side to keep the aux pull small. Passing more than 10 values for a key warns, since the request URL may get too long. When source is a tibble and no filters are given, they are inferred from the base: each key it narrows to at most 10 distinct values is filtered to those.

reference_time

timeset. Reference time to return (filters on the reference_time column). Supports individual dates or epirange(). Only used when source is a string.

time_values

Use reference_time instead.

snapshot_date

Date, POSIXt, UTC timestamp string (e.g. "2025-10-16T13:45:00Z"), "latest", or NULL. Return auxiliary data as it appeared at this date or instant (one row per key, the most recent version active then). "latest" uses today's date. Use NULL (default) to return the full version history filtered by report_time. Mutually exclusive with report_time. Only used when source is a string.

report_time

String or epirange() specifying the version of the auxiliary data to retrieve. 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. Mutually exclusive with snapshot_date. Only used when source is a string.

issues

Use report_time instead.

columns

A character vector of columns to return. By default, all columns are returned.

fetch_args

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

Value

A tibble::tibble.

See also

epidata_snapshot(), epidata_archive(), epidata_meta()