Changelog#
Unreleased#
Breaking changes#
Python 3.11 or newer is required (it was 3.9). CI tests 3.11 through 3.14.
New features#
.df(),.classic(), and calling an endpoint acceptrefresh_cache=Trueto skip the cache read and replace the cached entry with a fresh response.Classic responses with a categorical value outside the field’s declared categories now warn (
UnknownCategoryWarning) and keep the value as an extra category instead of silently turning it into a missing value.epidata_snapshot(),epidata_archive(), andepidata()sendgeo_valuesandreference_timeto the server as thegeo_valueandreference_timesfilters instead of filtering the response locally.reference_timealso accepts comparison strings such as">=2025-01-01".limitnow caps the rows that match these filters; before, it capped the rows first and the local filters could leave fewer, or none.Failed requests raise
EpiDataHTTPError, arequests.HTTPErrorsubclass, so existing handlers keep working. It exposes the server’s message as.message, plus.status_codeand.url.epidata_snapshot(),epidata_archive(), andepidata()accept named filters on the source’s extra key columns as keyword arguments (e.g.pcr_target="sars-cov-2"), sent server-side asextra_keys.When a cast query returns nothing, the
EmptyResultWarningalso gives the source’sreference_timerange.Cast snapshot/archive responses with columns the client doesn’t declare warn, like epidatr; those columns are kept as strings.
Fixes#
.df()keeps adate_or_epiweekcolumn as strings when any value is an epiweek (#38). Before,pub_covidcast_meta()returnedmin_timeas strings butmax_timeas half-parsed dates, andpub_flusurv()’sissuewas misparsed or warned.epidata_snapshot()andepidata_archive()no longer warn that every signal and geo type came back empty when.df(fields=...)leaves outsignalorgeo_type. The check now reads the full response beforefieldstrims it, and no longer makes an extra metadata request for it.Classic endpoints now raise
InvalidArgumentExceptionwhen a timeset mixes day (YYYYMMDD) and week (YYYYWW) values, when a week-only parameter such asepiweeksorissuesofpub_fluview()gets dates (before, it returned an empty result), and whenpub_wiki()orpvt_twitter()gettime_valuesthat don’t matchtime_type.epidata_aux()merged onto a snapshot or archive now warns withUnmatchedAuxWarningwhen some rows have no matching aux row, whose aux columns are then missing values.The missing-API-key warning states the anonymous V5 rate limits.
Requests are retried (3 tries in all) after a connection failure, a 500, 502, 503 or 504, or a 429 that comes with a
Retry-After, and now time out after 15 minutes of silence instead of never. ARetry-Afterlonger thanEPIDATPY_MAX_RETRY_WAITseconds (default 60) is never waited on: the call fails at once with the server’s message, which now also says when the server suggests retrying. This replaces thetenacitydependency.Classic (V4) endpoints no longer turn a bad response into an empty frame.
.df()raisesEpiDataAPIErrorfor an error envelope (e.g.result-1), and both.df()and.classic()raiseMalformedResponseErrorfor a body that is not JSON or lacksresult,message, orepidata. A non-successmessage(a truncated result, “no results”) warns withEpiDataWarning, and columns the endpoint promises but the response lacks warn withDroppedMetaFieldsWarningand are filled with missing values.The POST fallback for a 414 (URI too long) response now sends the parameters in the form body; before, it repeated them in the URL and failed the same way.
The cache now keeps only cast results for a fixed past version: a
snapshot_date, or areport_timeof the form"<date"or anEpiRange, ending at least two days ago (UTC). “Latest” and open-ended queries and calls with a rowlimitare not cached, so they no longer go stale for days. It stores the raw response and parses it on every read (so a cache hit is filtered and checked like a fresh result), and the cache key now includes the epidatpy version and the server URL. Existing cast cache entries are ignored.fieldson the cast endpoints no longer makes the request fail with a 422; the columns are selected locally, and calls with differentfieldsshare one cache entry.
Documentation#
The
fill_methodvalues are"source","ave", and"zero"; the docs said"fill_ave"and"fill_zero", which the server rejects.
0.7.0#
Breaking changes#
epidata_archive()andepidata(): passing a bare date or the=operator toreport_timenow raisesInvalidArgumentException. Use a comparison operator (e.g."<2025-01-01") or anEpiRangeinstead, orsnapshot_datefor point-in-time data.EpiRangevalues forreport_timeare now sent to the server as an inclusivefrom:torange; the local lower-bound filter is gone.The
report_timecolumn is now a UTC timestamp (a timezone-awaredatetime64column) rather than a date, matching the server, which now reports publication instants (e.g.2025-10-16T13:45:00Z).epidata_meta(source=...)returns that source’s entry directly instead of a one-key dict.pub_covidcast_meta()returnslast_updateas a UTC datetime instead of an integer.
New features#
snapshot_dateandreport_timebounds accept adatetimeor a UTC timestamp string with a trailingZ, in addition to dates.Failed requests raise
requests.HTTPErrorwith the server’s own error message appended (JSONmessage/detail, or the text of an HTML error page).epidata_snapshot(),epidata_archive(), andepidata()gainlimit, a cap on the rows the server returns.Noneor-1means no limit. The query has no stable sort order, so use it only to preview or debug a query.epidata_meta()with nosourcereturns the metadata for every source.geo_typeaccepts several values (a sequence or comma-joined string); the call issues one request per geo type and concatenates the results.Empty or partially empty cast results warn with
EmptyResultWarning, naming the signals and geo types that returned nothing. When nothing comes back at all and the source’s metadata says a requested signal or geo type does not exist, the call raisesInvalidArgumentExceptioninstead, matching epidatr.return_empty=Truesilences this.Cast responses parse
ci_lowerandci_upperwhen present.epidata_aux()fetches a cast source’s auxiliary data (e.g. nwss sample-site descriptors) from/aux_data/, with key filters passed as keyword arguments. Passing it a DataFrame fromepidata_snapshot()orepidata_archive()instead merges the auxiliary data onto each row, as of that row’s version.pub_covidcast_meta()gainssignals,time_type, andgeo_typearguments for server-side filtering, and now returns thegeo_typecolumn.pub_covidcast()validatestime_type, requirestime_type="week"fornssp, and accepts thehsa_ncianddmageo types.
Documentation#
README and the getting-started, signal-discovery, and versioned-data guides now lead with the V5 API; the migration guide covers the V3 endpoints (FluView example) and the current
report_timerules.The reference page is grouped by API generation.
0.6.0#
Added deprecation warnings and documentation for the V4 endpoints ahead of the V5 transition.
Added the cast-API endpoints
epidata_meta(),epidata_snapshot(),epidata_archive(), andepidata().