NEWS

---

epidatr 1.4.1

Changes

• 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).

Documentation

• fill_method values are "source", "ave", and "zero" (previously documented as "fill_ave" and "fill_zero").

Patches

• fetch_args_list(disable_data_frame_parsing = TRUE) now actually disables data frame parsing again.

epidatr 1.4.0 (2026-09-21)

Deprecations

• The V4 Epidata API is deprecated and stopped receiving new data on September 22, 2026. Legacy pub_* and pvt_* endpoints continue to serve historical data for unmigrated sources, while all active datasets are now served by V5 endpoints (epidata_snapshot(), epidata_archive(), epidata_aux(), and epidata_meta()). Updated the pub_*/pvt_* V4 warnings, function documentation, README, and vignette("migration-guide") to reflect the completed transition.
• Endpoints that were previously deprecated and remain available for historical reference (pvt_cdc(), pub_covid_hosp_facility_lookup(), pub_covid_hosp_facility(), pub_covid_hosp_state_timeseries(), pub_delphi(), pub_dengue_nowcast(), pvt_dengue_sensors(), pub_ecdc_ili(), pub_gft(), pvt_ght(), pub_kcdc_ili(), pvt_meta_norostat(), pub_nidss_dengue(), pub_nidss_flu(), pvt_norostat(), pub_nowcast(), pub_paho_dengue(), pvt_sensors(), pvt_twitter(), and pub_wiki()) now inherit a corresponding deprecation description with a deprecation badge in their documentation.

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.
• 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 (2026-08-28)

Deprecations

• pub_covidcast(), pub_covidcast_meta(), pub_fluview(), pub_fluview_clinical(), pub_fluview_meta(), pub_flusurv(), pub_meta(), and pvt_quidel() now warn that they use the V4 Epidata API. Starting in October 2026, it is tentatively deprecated in favor of the V5 API. See vignette("migration-guide") for the V5 replacements.
• The remaining V4 endpoints whose data sources are no longer updated (pvt_cdc(), pub_covid_hosp_facility_lookup(), pub_covid_hosp_facility(), pub_covid_hosp_state_timeseries(), pub_delphi(), pub_dengue_nowcast(), pvt_dengue_sensors(), pub_ecdc_ili(), pub_gft(), pvt_ght(), pub_kcdc_ili(), pvt_meta_norostat(), pub_nidss_dengue(), pub_nidss_flu(), pvt_norostat(), pub_nowcast(), pub_paho_dengue(), pvt_sensors(), pvt_twitter(), and pub_wiki()) now emit a quieter informational note (not a warning) explaining that they are frozen rather than deprecated. They are not moving to V5 and will keep working, but will not receive new data. See the "Endpoints kept for historical reference" section of vignette("migration-guide") for the full list.

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 (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 (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 (2025-03-20)

Patches

• Fix so that covidcast_epidata() will still print if fields are missing.

epidatr 1.2.0 (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 (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 (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 (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.