Skip to contents

Changelog

Source: NEWS.md

epidatr (development version)

Changes

  • The minimum supported R version is now 4.1.0, matching the requirements of our dependencies (e.g. httr2, glue, purrr, readr).

  • epidata_snapshot(), epidata_archive(), and epidata() now filter geo_values and reference_time server-side via the cast-API geo_value and reference_times parameters (cmu-delphi/cast-api#110).

  • epidata_aux() now warns when some rows have no matching aux row (their aux columns are NA), and hints that limit also caps the aux request.

  • epidata_snapshot(), epidata_archive(), and epidata_aux() results are now cached (when the cache is enabled) for fixed past versions: a snapshot_date at least two days ago (UTC), or a report_time range or "<date" whose end is at least two days ago. “Latest” snapshots, open-ended archives (including a report_time vector with any open-ended condition), and calls with a row limit are not cached. Previously no V5 query was ever cached.

  • epidata_aux(snapshot_date = "latest") now uses today’s UTC date, so it no longer misses releases made after midnight UTC in time zones behind UTC.

  • The cache now stores the unparsed API response and parses it on every read, so reference_week_day and disable_date_parsing no longer need to be part of the cache key and calls with fields can now be cached. Existing cache entries are ignored and re-fetched.

  • The epidatr version is now part of the cache key, so cache entries written by a different epidatr version are never read back.

  • A rate limit error (HTTP 429) on a request made without an API key now points to ?save_api_key for registering one (#294).

  • print.epidata_call() now shows auth=<redacted> instead of the restricted endpoint key (#386).

  • fetch_args_list(return_empty = TRUE) no longer turns truncated responses and generic API errors into a warning that returned (and cached) partial data. They now always raise an error (#384).

  • fetch_args_list() now rejects a reference_week_day that isn’t an integer from 1 to 7.

  • cache_info() now also reports enabled, n_entries and size_mb, works when the cache is off (inspecting the default directory), and prints a hint about clear_cache().

  • pub_paho_dengue() now errors when both issues and lag are given, like the other endpoints that take both (#397).

  • pub_ecdc_ili(), pub_flusurv(), pub_fluview_clinical(), and pub_kcdc_ili() no longer error on an explicit issues = NULL together with lag (or vice versa); NULL now means “not requested” everywhere (#398).

  • Timeset arguments now error when a vector mixes day (YYYYMMDD) and week (YYYYWW) values, and pvt_twitter() and pub_wiki() error when time_values doesn’t match time_type (#400).

  • The 414 (URI too long) fallback to POST now works: it strips the query from the URL and sends the parameters in the form body only (#393).

  • Unknown values in categorical fields now warn (class epidatr__unknown_category) and are kept as extra factor levels instead of silently becoming NA (#392).

  • A 200 response with a missing or non-scalar result or message, or with result 1 or 2 but no epidata, now raises epidatr__malformed_envelope; a non-JSON body raises epidatr__unparseable_response with the request URL (#389, #390).

  • Classic (V4) endpoints now warn (class epidatr__dropped_meta_fields) when the response lacks a column the endpoint promises. fields and disable_missing_meta_warning suppress it (#391).

  • Endpoints whose epiweeks or issues parameter only takes weeks (e.g. pub_flusurv(), pub_fluview()) now error when given dates, instead of returning an empty result (#278).

  • The issues/lag/as_of exclusivity check is now shared by all endpoints, and its error has class epidatr__exclusive_args (#222).

  • Argument errors that were plain stop() calls (timeset parsing, mismatched epirange() ends, and others) are now cli errors with condition classes, e.g. epidatr__invalid_timeset and epidatr__epirange_format_mismatch (#206).

  • The cache now stores the unparsed API response and parses it on every read, so reference_week_day and disable_date_parsing no longer need to be part of the cache key and calls with fields can now be cached. Existing cache entries are ignored and re-fetched.

Documentation

  • ?set_cache now names the EPIDATR_CACHE_DIR environment variable and cache_dir argument correctly (#394); the ?epidata_call example no longer makes a live request (#406); help pages no longer show “See also” twice.
  • fill_method values are "source", "ave", and "zero" (previously documented as "fill_ave" and "fill_zero").
  • Vignettes: the reporting-lag example now converts report_time with as.Date() before subtracting reference_time (since 1.4.0 the direct subtraction gave a meaningless value and lag filters returned no rows); metadata output is no longer truncated to 4 sources; the pub_dengue_nowcast() example uses dates that have data; the revision-history plot now shows the full series as known on each release date (the archive only lists changed values); vignettes and README re-rendered with 1.4.x output, each vignette in a fresh R session.
  • ?timeset now has examples (#203).
  • ?set_cache now has a table of the cache environment variables (#198).
  • Every endpoint’s @return now says what a row of the result represents (#204).
  • The reference page describes the configuration, caching and private-endpoint groups in more detail (#238).
  • ?timeset no longer says a list of ranges is accepted; the validator never accepted one (#399).

Patches

  • Requests no longer hang for up to two hours while the API is under maintenance. The API asks clients to retry an hour later while a data table is being rebuilt, and epidatr waited that long, twice, before giving up. Now a request asked to wait longer than the new epidatr.max_retry_wait option (default 60 seconds) fails right away with the API’s message, and HTTP errors say when the server suggests retrying. Shorter waits are still honoured, and 500, 502, 503 and 504 errors are still retried. A 429 (rate limit) is retried only if the API says when to come back, since the anonymous rate limits are per minute or per hour and every retry counts against them.
  • Caching fixes:
    • set_cache() now rejects a max age or size that isn’t a positive number. Previously EPIDATR_CACHE_MAX_AGE_DAYS=3/24 became NA and made every cached fetch fail (#396). An invalid setting at load time turns the cache off with a message rather than stopping the package from loading.
    • Loading the package with EPIDATR_USE_CACHE=TRUE creates a missing cache directory instead of prompting, and set_cache() no longer prompts in non-interactive sessions. When the cache can’t be set, the message now says so instead of claiming the cache is in use (#401).
    • The warning about caching recent data versions (class cache_recent_data) can now fire; it previously never did (#385).
    • refresh_cache = TRUE no longer writes entries that a default fetch would read back with different parsing, and a non-default reference_week_day gets its own cache entry. An API error response that return_empty = TRUE turned into an empty result is no longer cached, so a later default call still raises the error (#388).
  • fetch_args_list(disable_data_frame_parsing = TRUE) now actually disables data frame parsing again.
  • report_time values the API returns as a bare date (YYYY-MM-DD) are now parsed as a Date instead of NA. UTC timestamps are still parsed as POSIXct.
  • epidata_snapshot(), epidata_archive(), and epidata() now trim whitespace around comma-joined signals and geo_type values, so "sig1, sig2" works the same as "sig1,sig2" (#407).

epidatr 1.4.0

CRAN release: 2026-09-21

Deprecations

Documentation

  • Updated vignettes (epidatr, signal-discovery, and versioned-data) to focus on V5 API workflows. Remove and redirect v5-api-demo vignette.

Patches

  • API errors now surface the server’s actual message for both the V4 (classic) and V5 (cast) APIs.

Changes

  • epidata_snapshot() and epidata_archive() now send multiple signals comma-joined in a single request per geo_type, instead of issuing a separate request per signal (cmu-delphi/cast-api#103).

Breaking changes

  • epidata_archive() and epidata_aux(): passing a bare date or the "=" operator to report_time now errors. Use a comparison operator (e.g. "<2025-01-01") or an epirange() instead.
  • The cast-API’s report_time column and the report_time_range in epidata_meta() are now UTC timestamps (e.g. 2025-10-16T13:45:00Z) rather than dates, so report_time now parses to a POSIXct. report_time and snapshot_date filters also accept a UTC timestamp string (with a trailing Z) or a POSIXt, in addition to a bare date, for exact-instant filtering (cmu-delphi/cast-api#123).

New features

  • epidata_aux() gains a snapshot_date argument (date, "latest", or NULL) for retrieving auxiliary data as it appeared on a specific date. Mutually exclusive with report_time.
  • epidata_archive() and epidata_aux(): epirange() values for report_time are now filtered server-side using the cast-API’s inclusive range syntax; the local lower-bound filter has been removed.
  • fetch_args_list() gains a limit argument, capping the number of rows the cast-API returns for epidata_snapshot(), epidata_archive(), epidata_aux(), and epidata(). Defaults to NULL (no limit); -1 has the same effect. The underlying query has no stable sort order, so limit does not guarantee the same rows (or count) across repeated calls. Use it only to preview or debug a query, not as a real filter.

epidatr 1.3.0

CRAN release: 2026-08-28

Deprecations

Patches

  • epidata_snapshot() and epidata_archive() now issue one request per signal instead of joining signals with a comma, which the cast-API server silently matched against nothing (#354).
  • epidata_archive(report_time = ...) now sends the report_time_query API parameter; the server renamed it from version_query, which it now rejects.
  • Add a migration guide vignette (vignette("migration-guide")) mapping pub_covidcast arguments and columns to the new epidata_snapshot/epidata_archive functions, and update the README and pkgdown reference to lead with the new API.
  • Parse ci_lower and ci_upper data columns for some signals.
  • Improve CSV parsing performance by reading bytes directly.
  • save_api_key() no longer errors when called outside a project; it falls back to the user .Renviron (#339).
  • Text fields are now always parsed as character; previously an all-NA column (e.g. geocoded_state in the covid_hosp endpoints) came back as logical.

epidatr 1.2.4

CRAN release: 2026-06-02

Changes

  • Added epidata_aux() to fetch V5-API auxiliary data, either directly by source or by merging it onto epidata_snapshot()/epidata_archive() output via a version-aware left join. When no key filters are supplied, it infers them from the base to keep the pull small.
  • epidata_aux(), epidata_snapshot(), and epidata_archive() now accept per-key filters as named ... arguments. Each key takes one or more values, sent server-side to shrink the download.
  • Improve documentation, including descriptions for save_api_key() and endpoint parameters, and standardize parameter information (#324 and #334).
  • Modernize internal API architecture by migrating from httr to httr2.
  • Introduce a centralized validation system in R/check.R using checkmate to standardize input checking, date parsing, and API parameter formatting.
  • Refactor epidata_call and do_request to use httr2 request objects, implement automatic GET-to-POST fallback, and add robust retry logic.
  • Improve file-level documentation by adding summary descriptors at the top of all R source files.
  • Deprecate debug and format_type arguments in fetch_args_list().

Features

  • Added new epidata, epidata_meta, epidata_snapshot, and epidata_archive for accessing the Delphi V5 API.
  • pub_covidcast_meta() gained signals, time_type, and geo_type arguments for server-side filtering of the metadata results.

Patches

  • last_update in pub_covidcast_meta is now returned as a POSIXct object instead of an integer.
  • Improved efficiency of date parsing for API responses.
  • Migrate HTTP requests from httr to httr2.
  • Update endpoint examples to skip execution when required API keys or internet connectivity are unavailable, ensuring cleaner R CMD check results.
  • Add lifecycle to DESCRIPTION to properly manage function deprecations.
  • Extend check_is_recent to support numeric date formats (#320).

epidatr 1.2.2

CRAN release: 2025-11-17

Changes

  • Add reference_week_day argument to fetch_args_list and fetch functions.

Patches

  • Validate that time_type is one of “day” or “week” in pub_covidcast.
  • Validate that time_type is “week” when source is “nssp” in pub_covidcast.
  • Allow hsa_nci as a geo_type in pub_covidcast.
  • Allow hsa_nci as a geo_type in pub_covidcast_meta.
  • pub_covidcast_meta now returns min_time, max_time, max_issue as integers rather than Dates. Because these fields can mix YYYYMMDD and YYYYWW values, we recommend you parse them yourself.
  • add new fields for flusurv endpoint.

epidatr 1.2.1

CRAN release: 2025-03-20

Patches

epidatr 1.2.0

CRAN release: 2024-06-20

Changes

  • Improve handling of the EPIDATR_USE_CACHE environment variable, allowing it to be any value convertable by as.logical() and handle the case when it can’t be converted.
  • Support more date formats in function to convert dates to epiweeks. Use parse_api_date since it already supports both common formats. #276
  • EPIDATR_USE_CACHE only supported exactly “TRUE” before. Now it supports all logical values and includes a warning when any value that can’t be converted to logical is provided. #273
  • missing doesn’t count default values as non-missing. If a user doesn’t pass geo_values or time_values (both of which default to "*" in pub_covidcast), or dates (in pub_covid_hosp_state_timeseries), the missing check fails. To avoid this, just don’t check missingness of those two arguments.
  • fetch_args_list now has an refresh_cache argument, which is FALSE by default.

epidatr 1.1.1

CRAN release: 2024-03-04

Changes

Features

Patches

  • Fix failure when passing as_of values in Date format to pub_covidcast while caching is enabled (#259).
  • For pub_covidcast data source nchs-mortality, parse dates as epiweek and expect epiweek inputs from user (#260).
  • Fix failure in pub_covidcast when user doesn’t pass geo_values or time_values, even though those arguments have defaults (#268).

epidatr 1.1.0

CRAN release: 2024-02-29

Changes

  • pub_covid_hosp_state_timeseries now supports use of the as_of parameter (#209).
  • release_date and latest_update fields are now parsed as Date, rather than as text. This change impacts several endpoints.
  • get_auth_key renamed to get_api_key (#181).
  • get_api_key no longer reads from R options and only uses environment variables (#217).
  • pvt_twitter and pub_wiki now use time_type and time_values args instead of mutually exclusive dates and epiweeks (#236). This matches the interface of the pub_covidcast endpoint.
  • Updated the default timeout_seconds to 15 minutes to allow large queries by default.

Features

  • Function reference now displays commonly-used functions first (#205).
  • Support Date objects passed to version arguments as_of and issues in endpoints (#192, #194).
  • clear_cache now handles positional arguments just like set_cache (#197).
  • set_api_key now available to help persist API key environment variables (#181, #217).
  • All endpoints now support the use of “*” as a wildcard to fetch all dates or epiweeks (#234).

Patches

  • Endpoints now fail when passed misspelled arguments (#187, #201).
  • pub_fluview_meta fixed to fetch the response automatically.
  • pub_covid_hosp_state_timeseries now correctly parses the issue field, instead of returning a missing value (#202).
  • In pub_fluview_meta, latest_issue field is now parsed as epiweek, rather than being parsed as Date and returning a missing value.
  • set_cache cache size no longer runs into integer overflow (#189).
  • Improve line-wrapping of warning messages (#191).
  • Fix documentation related to CRAN submission.
  • Fix some errors from passing “” as a key.
  • Fixed bug with NAs when parsing ints (#243).

epidatr 1.0.0

CRAN release: 2023-09-19

  • Add set_cache and other caching functions.
  • Prefix all non-private endpoints with pub_.
  • Update printing of avail_endpoints to be more readable.
  • Update printing of covidcast_epidata() to be more readable.
  • Update landing docs to be more friendly, add plots.

epidatr 0.9.0

  • Major interface change: all endpoints now fetch by default.
  • Make all fetch function internal.
  • Change fetch and fetch_* function interfaces now rely on fetch_args_list.
  • Added fetch_args_list which returns a list of arguments to be passed to fetch.

epidatr 0.8.0

  • Fix source name duplication bug in covidcast_epidata.
  • Mark covidcast_epidata as experimental and do not export it.
  • Change covidcast arg data_source to source.
  • Make covidcast args issues, lag, and as_of mutually exclusive.
  • Make covid_hosp_facility_lookup args state, ccn, city, zip, and fips_code mutually exclusive.
  • Update documentation to only refer to character or strings (not character vectors or character strings).

epidatr 0.7.1

  • Update README.md for better onboarding.
  • Consolidate the vignettes into one. Clean up the code, do not eval most examples.

epidatr 0.7.0

  • Remove temporary code for API key transition.
  • Add timeout_seconds and return_empty arguments to fetch().

epidatr 0.6.0

  • The fetch_{tbl,classic,df,json,csv} functions have been replaced by the fetch() function, which almost always returns a tibble, except when used with a limited number of older endpoints (such as delphi() and meta()), where it will output a nested list structure.

epidatr 0.5.0

  • The package that this installs is being renamed from delphi.epidata to epidatr. To migrate, run the installation command above, followed by remove.packages("delphi.epidata"), and adjust all references to the package name accordingly.