epidatpy Reference

All endpoints are methods of EpiDataContext. Each returns an EpiDataCall describing the request; call .df() on it to fetch a pandas.DataFrame.

Query the new Epidata API (V5)

The current API. Sources are moving here from the covidcast endpoint; see the migration guide for how to update covidcast queries.

EpiDataContext.epidata_meta(source=None)

Fetch source-level metadata from the CAST API.

Each source’s entry lists its signals, geo_types, extra key columns, and its reference_time_range and report_time_range (the latter as UTC timestamps). With source=None (default) the result is a dict keyed by source name covering every available source; with a source it is that source’s entry alone.

Parameters:

source (str | None)

Return type:

Any

EpiDataContext.epidata_snapshot(source, signals, geo_type, geo_values='*', reference_time='*', fill_method=None, snapshot_date=None, limit=None, return_empty=False)

Fetch a snapshot of V5 signals as they appeared at snapshot_date.

API docs: <https://cmu-delphi.github.io/delphi-epidata/api/v5_signals.html>

Parameters:

  • source (str) – The data source to query (e.g. "nssp", "nhsn"). Use epidata_meta() to discover available sources.

  • signals (Union[str, Sequence[str]]) – One or more signals of the source, as a sequence or a comma-joined string. All signals are sent in a single request per geo type.

  • geo_type (Union[str, Sequence[str]]) – One or more geography types (e.g. "state", "hhs", "nation"). The server accepts one geo type per request, so the call issues one request per value and concatenates the results.

  • geo_values (Union[str, Sequence[str]]) – Locations to keep, as a sequence or a comma-joined string; "*" (default) keeps all. Filtered locally after the request.

  • reference_time (Union[int, str, EpiRange, EpiRangeDict, date, Week, Sequence[Union[int, str, EpiRange, EpiRangeDict, date, Week]]]) – Reference dates to keep: a date, a sequence of dates, or an EpiRange; "*" (default) keeps all. Filtered locally after the request.

  • fill_method (str | None) – Restrict to one imputation variant of the signal: "source" (raw source data), "fill_ave" (nulls filled with the average of neighboring values), or "fill_zero" (nulls filled with zero). None (default) returns all variants.

  • snapshot_date (str | date | datetime | int | None) – The instant the snapshot describes: a date (date, "YYYY-MM-DD", YYYYMMDD) or an instant (datetime or a UTC timestamp string such as "2025-10-16T13:45:00Z"). None (default) returns the latest available version.

  • limit (int | None) – Cap on the rows the server returns; None (default) or -1 means no limit. The query has no stable sort order, so limit does not guarantee the same rows (or count) across calls. Use it to preview or debug a query, not as a filter.

  • return_empty (bool) – Return an empty frame silently instead of diagnosing it.

Returns:

Columns: signal, report_time (UTC timestamp), geo_type, geo_value, fill_method, reference_time, value, plus ci_lower/ci_upper and source-specific key columns (e.g. age_group for pophive; nwss_source, sample_index, pcr_target for nwss) when the source provides them.

Return type:

EpiDataCall

Notes

An empty or partially empty result warns with EmptyResultWarning, naming the signals and geo types that returned nothing. When nothing came back at all and epidata_meta() says a requested signal or geo type does not exist for source, it raises InvalidArgumentException instead.

EpiDataContext.epidata_archive(source, signals, geo_type, geo_values='*', reference_time='*', fill_method=None, report_time='*', limit=None, return_empty=False)

Fetch the full revision history of V5 signals.

Every version of each value is returned, one row per report_time. See epidata_snapshot() for the shared arguments and the columns returned.

API docs: <https://cmu-delphi.github.io/delphi-epidata/api/v5_signals.html>

Parameters:

  • source (str) – The data source to query.

  • signals (Union[str, Sequence[str]]) – One or more signals of the source.

  • geo_type (Union[str, Sequence[str]]) – One or more geography types; one request is made per value.

  • geo_values (Union[str, Sequence[str]]) – Locations to keep; "*" (default) keeps all. Filtered locally.

  • reference_time (Union[int, str, EpiRange, EpiRangeDict, date, Week, Sequence[Union[int, str, EpiRange, EpiRangeDict, date, Week]]]) – Reference dates to keep; "*" (default) keeps all. Filtered locally.

  • fill_method (str | None) – Restrict to one imputation variant ("source", "fill_ave", or "fill_zero"); None (default) returns all.

  • report_time (str | EpiRange | None) – Filter on the report_time column, applied server-side. Either a comparison string (<, <=, >, or >= followed by a date or a UTC timestamp, e.g. "<2025-10-16" or "<=2025-10-16T13:45:00Z") or an EpiRange for an inclusive date range. Bare dates and = are rejected; use epidata_snapshot() for point-in-time data. "*" (default) returns all report times.

  • limit (int | None) – Cap on the rows the server returns; see epidata_snapshot().

  • return_empty (bool) – Return an empty frame silently instead of diagnosing it.

Return type:

EpiDataCall

EpiDataContext.epidata_aux(source, *, reference_time='*', report_time='*', snapshot_date=None, columns=None, limit=None, **key_filters)

Fetch V5 auxiliary data associated with a cast-API signal.

Auxiliary data is time-varying metadata attached to a cast source (e.g. nwss sample-site descriptors). Pass a source string for a direct pull from the /aux_data/ endpoint, or a DataFrame already fetched via epidata_snapshot() or epidata_archive() (i.e. its .df() result) to merge the matching auxiliary data onto it – the source is recovered automatically from the DataFrame.

For the auxiliary key columns and their allowed values, see the source’s API docs, e.g. NWSS.

Parameters:

  • source (str | DataFrame) – A source string to fetch auxiliary data directly, or a DataFrame returned by epidata_snapshot() or epidata_archive() to merge the data onto.

  • reference_time (Union[int, str, EpiRange, EpiRangeDict, date, Week, Sequence[Union[int, str, EpiRange, EpiRangeDict, date, Week]]]) – Reference time to return. Supports EpiRange and defaults to all (“*”). Base-pull mode only (when source is a string).

  • report_time (str | EpiRange | None) – Version of the auxiliary data to retrieve: a comparison operator string (e.g. "<2025-10-16", ">=2025-10-16T13:45:00Z") or an EpiRange for an inclusive date range. Bare dates and the "=" operator are rejected Base-pull mode only (when source is a string). Mutually exclusive with snapshot_date.

  • snapshot_date (str | date | datetime | int | None) – 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. None (default) returns the full version history filtered by report_time instead. Base-pull mode only (when source is a string). Mutually exclusive with report_time.

  • columns (Sequence[str] | None) – Columns to return. By default, all columns are returned.

  • limit (int | None) – Cap on the number of rows the server returns (direct pulls only; ignored when source is a DataFrame). None (default) or -1 means no limit. The underlying query has no stable sort order, so limit does not guarantee the same rows (or count) across calls. Use it to preview or debug a query, not as a filter.

  • **key_filters (str | date | Sequence[str | date]) – Named filters on the auxiliary key columns, such as pcr_target="sars-cov-2" or geo_value=["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. A date value serializes as YYYY-MM-DD. Passing more than 10 values for a key warns, since the request URL may get too long. In merge mode, when no filters are given, they are inferred from source: each key it narrows to at most 10 distinct values is filtered to those.

Returns:

A lazy EpiDataCall for a base pull, or the merged DataFrame when source is a DataFrame.

Return type:

EpiDataCall | DataFrame

See also

epidata_snapshot, epidata_archive, epidata_meta

EpiDataContext.epidata(source, signals, geo_type, geo_values='*', reference_time='*', fill_method=None, snapshot_date=None, report_time=None, limit=None, return_empty=False)

Fetch V5 signals, routing on the versioning argument supplied.

Dispatches to epidata_archive() when report_time is supplied or snapshot_date == "*", and otherwise to epidata_snapshot() (so with neither argument it returns the latest snapshot). report_time and snapshot_date are mutually exclusive. See those two methods for the argument details.

Parameters:

  • source (str)

  • signals (Union[str, Sequence[str]])

  • geo_type (Union[str, Sequence[str]])

  • geo_values (Union[str, Sequence[str]])

  • reference_time (Union[int, str, EpiRange, EpiRangeDict, date, Week, Sequence[Union[int, str, EpiRange, EpiRangeDict, date, Week]]])

  • fill_method (str | None)

  • snapshot_date (str | date | datetime | int | None)

  • report_time (str | EpiRange | None)

  • limit (int | None)

  • return_empty (bool)

Return type:

EpiDataCall

Query the covidcast endpoint (V4)

The previous main endpoint. It still carries the sources that have not moved to V5 yet, and warns on every call ahead of its October 2026 deprecation.

EpiDataContext.pub_covidcast(data_source, signals, geo_type, time_type, geo_values='*', time_values='*', as_of=None, issues=None, lag=None)

Fetch Delphi’s COVID-19 Surveillance Streams.

This is a V4 endpoint. Starting in October 2026, it is tentatively deprecated in favor of the V5 API. The new API can be accessed via the epidata_snapshot(), epidata_archive(), and epidata_meta() functions. For more details on the changes, refer to the migration guide, and visit the V5 signals documentation to see which sources are currently available.

API docs: <https://cmu-delphi.github.io/delphi-epidata/api/covidcast_signals.html>

The primary endpoint for fetching COVID-19 data, providing access to a wide variety of signals from a wide variety of sources. Delphi’s COVIDcast public dashboard is powered by this endpoint.

Parameters:

  • data_source (str) – The name of the data source to query. See Covidcast Signals.

  • signals (Union[str, Sequence[str]]) – The signals to query from a specific source. See Covidcast Signals.

  • geo_type (Literal['nation', 'msa', 'hrr', 'hhs', 'hsa_nci', 'dma', 'state', 'county']) – The geographic resolution of the data. See Covidcast Geography.

  • time_type (Literal['day', 'week']) – The temporal resolution of the data (either “day” or “week”).

  • geo_values (str | Sequence[str]) – The geographic locations to return. Supports a single string, a sequence of strings, or defaults to all locations (“*”). See Covidcast Geography.

  • time_values (Union[int, str, EpiRange, EpiRangeDict, date, Week, Sequence[Union[int, str, EpiRange, EpiRangeDict, date, Week]]]) – Temporal points to fetch. Supports EpiRange and defaults to all (“*”) dates/weeks. Format as epirange(start, end), where start and end are of the form YYYY-MM-DD or YYYYWW depending on the time_type.

  • as_of (None | str | int) – Fetch data as it was known as of this date. Mutually exclusive with issues and lag.

  • issues (Union[int, str, EpiRange, EpiRangeDict, date, Week, Sequence[Union[int, str, EpiRange, EpiRangeDict, date, Week]], None]) – Range or list of issue dates to fetch. Mutually exclusive with as_of and lag.

  • lag (int | None) – Number of days between the observation and its publication. Mutually exclusive with as_of and issues.

Return type:

EpiDataCall

EpiDataContext.pub_covidcast_meta(signals=None, time_type=None, geo_type=None)

Fetch COVIDcast surveillance stream metadata.

This is a V4 endpoint. Starting in October 2026, it is tentatively deprecated in favor of the V5 API. The new API can be accessed via the epidata_snapshot(), epidata_archive(), and epidata_meta() functions. For more details on the changes, refer to the migration guide, and visit the V5 signals documentation to see which sources are currently available.

API docs: <https://cmu-delphi.github.io/delphi-epidata/api/covidcast_meta.html>

Obtains a data frame of metadata describing all publicly available data streams from the COVIDcast API. See the data source and signals documentation for descriptions of the available sources.

Parameters:

  • signals (Union[str, Sequence[str], None]) – Restrict to these source:signal pairs (e.g. "jhu-csse:confirmed_cumulative_num"), filtered server-side. Defaults to all.

  • time_type (Optional[Literal['day', 'week']]) – Restrict to this temporal resolution (“day” or “week”). Defaults to all.

  • geo_type (Optional[Literal['nation', 'msa', 'hrr', 'hhs', 'hsa_nci', 'dma', 'state', 'county']]) – Restrict to this geographic level. Defaults to all.

Returns:

A EpiDataCall object containing the following information:

data_source

Data source name.

signal

Signal name.

time_type

Temporal resolution at which this signal is reported. “day”, for example, means the signal is reported daily.

geo_type

Geographic level for which this signal is available, such as county, state, msa, hss, hrr, or nation. Most signals are available at multiple geographic levels and will hence be listed in multiple rows with their own metadata.

min_time

First day for which this signal is available. For weekly signals, will be the first day of the epiweek.

max_time

Most recent day for which this signal is available. For weekly signals, will be the first day of the epiweek.

num_locations

Number of distinct geographic locations available for this signal. For example, if geo_type is county, the number of counties for which this signal has ever been reported.

min_value

The smallest value that has ever been reported.

max_value

The largest value that has ever been reported.

mean_value

The arithmetic mean of all reported values.

stdev_value

The sample standard deviation of all reported values.

last_update

The UTC datetime for when the signal value was last updated.

max_issue

Most recent date data was issued.

min_lag

Smallest lag from observation to issue, in days.

max_lag

Largest lag from observation to issue, in days.

Return type:

EpiDataCall

CovidcastEpidata(base_url='https://api.delphi.cmu.edu/epidata/', session=None, use_cache=None, cache_max_age_days=None)
Parameters:

  • base_url (str)

  • session (Session | None)

  • use_cache (bool | None)

  • cache_max_age_days (int | None)

Return type:

CovidcastDataSources

Query legacy endpoints (V3)

Older endpoints, each with its own dataset. Most are static or no longer updated; see the migration guide for which ones are kept for historical reference.

EpiDataContext.pub_covid_hosp_facility(hospital_pks, collection_weeks='*', publication_dates=None)

Fetch COVID hospitalizations by facility.

API docs: <https://cmu-delphi.github.io/delphi-epidata/api/covid_hosp_facility.html>

Obtains the COVID-19 reported patient impact and hospital capacity data by facility. This dataset is provided by the US Department of Health & Human Services. The companion function pub_covid_hosp_facility_lookup() can be used to look up facility identifiers in a variety of ways.

Starting October 1, 2022, some facilities are only required to report annually.

Parameters:

  • hospital_pks (Union[str, Sequence[str]]) – Unique identifiers for hospitals of interest. Supports a single string or a sequence of strings.

  • collection_weeks (Union[int, str, EpiRange, EpiRangeDict, date, Week, Sequence[Union[int, str, EpiRange, EpiRangeDict, date, Week]]]) – Weekly data collection periods to fetch. Supports EpiRange and defaults to all (“*”) weeks. Note: This parameter expects dates in YYYY-MM-DD or YYYYMMDD format. If provided as Week, they will be converted to the starting day of the week.

  • publication_dates (Union[int, str, EpiRange, EpiRangeDict, date, Week, Sequence[Union[int, str, EpiRange, EpiRangeDict, date, Week]], None]) – Publication dates to fetch. Supports EpiRange. Format as YYYY-MM-DD (string or numeric).

Return type:

EpiDataCall

EpiDataContext.pub_covid_hosp_facility_lookup(state=None, ccn=None, city=None, zip=None, fips_code=None)

Helper for finding COVID hospitalization facilities.

API docs: <https://cmu-delphi.github.io/delphi-epidata/api/covid_hosp_facility_lookup.html>

Obtains unique identifiers and other metadata for COVID hospitalization facilities of interest. This is a companion endpoint to the pub_covid_hosp_facility() endpoint.

Only one location argument needs to be specified. Combinations of the arguments are not currently supported.

Parameters:

  • state (str | None) – Two-letter state abbreviation.

  • ccn (str | None) – CMS Certification Number.

  • city (str | None) – City name.

  • zip (str | None) – 5-digit zip code.

  • fips_code (str | None) – A 5-digit FIPS county code, zero-padded.

Return type:

EpiDataCall

EpiDataContext.pub_covid_hosp_state_timeseries(states, dates='*', issues=None, as_of=None)

Fetch COVID hospitalizations by state.

API docs: <https://cmu-delphi.github.io/delphi-epidata/api/covid_hosp.html>

Obtains the COVID-19 reported patient impact and hospital capacity data by state. This dataset is provided by the US Department of Health & Human Services.

Starting October 1, 2022, some facilities are only required to report annually.

Parameters:

  • states (Union[str, Sequence[str]]) – Geographic locations to return, formatted as two-letter state abbreviations. Supports a single string or a sequence of strings.

  • dates (Union[int, str, EpiRange, EpiRangeDict, date, Week, Sequence[Union[int, str, EpiRange, EpiRangeDict, date, Week]]]) – Dates to fetch. Supports EpiRange and defaults to all (“*”) dates. Format as epirange(start, end), where start and end are of the form YYYYMMDD (string or numeric).

  • issues (Union[int, str, EpiRange, EpiRangeDict, date, Week, Sequence[Union[int, str, EpiRange, EpiRangeDict, date, Week]], None]) – Range or list of issue dates to fetch. Supports EpiRange. Format as YYYYMMDD. Mutually exclusive with as_of.

  • as_of (None | int | str) – Fetch data as it was known as of this date. Format as YYYYMMDD. Mutually exclusive with issues.

Return type:

EpiDataCall

EpiDataContext.pub_delphi(system, epiweek)

Fetch Delphi’s ILINet outpatient doctor visits forecasts.

API docs: <https://cmu-delphi.github.io/delphi-epidata/api/delphi.html>

Parameters:

  • system (str) – The name of the forecast system. See Forecasting Systems.

  • epiweek (int | str) – Epiweek to fetch. Does not support multiple dates. Make separate calls to fetch data for multiple epiweeks.

Return type:

EpiDataCall

EpiDataContext.pub_dengue_nowcast(locations, epiweeks='*')

Fetch Delphi’s PAHO dengue nowcasts (North and South America).

API docs: <https://cmu-delphi.github.io/delphi-epidata/api/dengue_nowcast.html>

Parameters:

  • locations (Union[str, Sequence[str]]) – Geographic locations to return. Supports a single string or a sequence of strings. See Countries and Territories in the Americas.

  • epiweeks (Union[int, str, EpiRange, EpiRangeDict, date, Week, Sequence[Union[int, str, EpiRange, EpiRangeDict, date, Week]]]) – Epiweeks to fetch. Supports EpiRange and defaults to all (“*”) weeks. Format as epirange(startweek, endweek), where startweek and endweek are of the form YYYYWW (string or numeric).

Return type:

EpiDataCall

EpiDataContext.pub_ecdc_ili(regions, epiweeks='*', issues=None, lag=None)

Fetch ECDC ILI incidence (Europe).

API docs: <https://cmu-delphi.github.io/delphi-epidata/api/ecdc_ili.html>

Obtain information on influenza-like-illness from the European Centre for Disease Prevention and Control.

Parameters:

  • regions (Union[str, Sequence[str]]) – List of European countries to fetch. See European Countries.

  • epiweeks (Union[int, str, EpiRange, EpiRangeDict, date, Week, Sequence[Union[int, str, EpiRange, EpiRangeDict, date, Week]]]) – Epiweeks to fetch. Supports EpiRange and defaults to all (“*”) weeks. Format as epirange(startweek, endweek), where startweek and endweek are of the form YYYYWW (string or numeric).

  • issues (Union[int, str, EpiRange, EpiRangeDict, date, Week, Sequence[Union[int, str, EpiRange, EpiRangeDict, date, Week]], None]) – Range or list of issue dates to fetch. Supports EpiRange. Mutually exclusive with lag.

  • lag (int | None) – Number of days between the observation and its publication. Mutually exclusive with issues.

Return type:

EpiDataCall

EpiDataContext.pub_flusurv(locations, epiweeks='*', issues=None, lag=None)

Fetch CDC FluSurv flu hospitalizations.

This is a V4 endpoint. Starting in October 2026, it is tentatively deprecated in favor of the V5 API. The new API can be accessed via the epidata_snapshot(), epidata_archive(), and epidata_meta() functions. For more details on the changes, refer to the migration guide, and visit the V5 signals documentation to see which sources are currently available.

API docs: <https://cmu-delphi.github.io/delphi-epidata/api/flusurv.html>

Obtain information on influenza hospitalization rates from the Center of Disease Control.

See also <https://gis.cdc.gov/GRASP/Fluview/FluHospRates.html>.

Parameters:

  • locations (Union[str, Sequence[str]]) – List of locations to fetch. See FluSurv Locations.

  • epiweeks (Union[int, str, EpiRange, EpiRangeDict, date, Week, Sequence[Union[int, str, EpiRange, EpiRangeDict, date, Week]]]) – Epiweeks to fetch. Supports EpiRange and defaults to all (“*”) weeks. Format as epirange(startweek, endweek), where startweek and endweek are of the form YYYYWW (string or numeric).

  • issues (Union[int, str, EpiRange, EpiRangeDict, date, Week, Sequence[Union[int, str, EpiRange, EpiRangeDict, date, Week]], None]) – Range or list of issue dates to fetch. Supports epirange(). Mutually exclusive with lag.

  • lag (int | None) – Number of days between the observation and its publication. Mutually exclusive with issues.

Return type:

EpiDataCall

EpiDataContext.pub_fluview(regions, epiweeks='*', issues=None, lag=None, auth=None)

Fetch CDC FluView ILINet outpatient doctor visits.

This is a V4 endpoint. Starting in October 2026, it is tentatively deprecated in favor of the V5 API. The new API can be accessed via the epidata_snapshot(), epidata_archive(), and epidata_meta() functions. For more details on the changes, refer to the migration guide, and visit the V5 signals documentation to see which sources are currently available.

API docs: <https://cmu-delphi.github.io/delphi-epidata/api/fluview.html>

Obtains information on outpatient inluenza-like-illness (ILI) from U.S. Outpatient Influenza-like Illness Surveillance Network (ILINet).

See also <https://gis.cdc.gov/grasp/fluview/fluportaldashboard.html>.

Parameters:

  • regions (Union[str, Sequence[str]]) – List of regions to fetch. See US Regions and States and FluView Cities.

  • epiweeks (Union[int, str, EpiRange, EpiRangeDict, date, Week, Sequence[Union[int, str, EpiRange, EpiRangeDict, date, Week]]]) – Epiweeks to fetch. Supports EpiRange and defaults to all (“*”) weeks. Format as epirange(startweek, endweek), where startweek and endweek are of the form YYYYWW (string or numeric).

  • issues (Union[int, str, EpiRange, EpiRangeDict, date, Week, Sequence[Union[int, str, EpiRange, EpiRangeDict, date, Week]], None]) – Range or list of issue dates to fetch. Supports EpiRange. Mutually exclusive with lag.

  • lag (int | None) – Number of days between the observation and its publication. Mutually exclusive with issues.

  • auth (str | None) – Private API key.

Return type:

EpiDataCall

EpiDataContext.pub_fluview_clinical(regions, epiweeks='*', issues=None, lag=None)

Fetch CDC FluView flu tests from clinical labs.

This is a V4 endpoint. Starting in October 2026, it is tentatively deprecated in favor of the V5 API. The new API can be accessed via the epidata_snapshot(), epidata_archive(), and epidata_meta() functions. For more details on the changes, refer to the migration guide, and visit the V5 signals documentation to see which sources are currently available.

API docs: <https://cmu-delphi.github.io/delphi-epidata/api/fluview_clinical.html>

Parameters:

  • regions (Union[str, Sequence[str]]) – List of regions to fetch. See US Regions and States.

  • epiweeks (Union[int, str, EpiRange, EpiRangeDict, date, Week, Sequence[Union[int, str, EpiRange, EpiRangeDict, date, Week]]]) – Epiweeks to fetch. Supports EpiRange and defaults to all (“*”) weeks. Format as epirange(startweek, endweek), where startweek and endweek are of the form YYYYWW (string or numeric).

  • issues (Union[int, str, EpiRange, EpiRangeDict, date, Week, Sequence[Union[int, str, EpiRange, EpiRangeDict, date, Week]], None]) – Range or list of issue dates to fetch. Supports EpiRange. Mutually exclusive with lag.

  • lag (int | None) – Number of days between the observation and its publication. Mutually exclusive with issues.

Return type:

EpiDataCall

EpiDataContext.pub_fluview_meta()

Fetch Metadata for the FluView endpoint.

This is a V4 endpoint. Starting in October 2026, it is tentatively deprecated in favor of the V5 API. The new API can be accessed via the epidata_snapshot(), epidata_archive(), and epidata_meta() functions. For more details on the changes, refer to the migration guide, and visit the V5 signals documentation to see which sources are currently available.

API docs: <https://cmu-delphi.github.io/delphi-epidata/api/fluview_meta.html>

Return type:

EpiDataCall

EpiDataContext.pub_gft(locations, epiweeks='*')

Fetch Google Flu Trends flu search volume.

API docs: <https://cmu-delphi.github.io/delphi-epidata/api/gft.html>

Obtains estimates of inluenza activity based on volume of certain search queries from Google.

Google has discontinued Flu Trends and this is now a static endpoint.

Parameters:

  • locations (Union[str, Sequence[str]]) – List of locations to fetch. See Geographic Codes.

  • epiweeks (Union[int, str, EpiRange, EpiRangeDict, date, Week, Sequence[Union[int, str, EpiRange, EpiRangeDict, date, Week]]]) – Epiweeks to fetch. Supports EpiRange and defaults to all (“*”) weeks. Format as epirange(startweek, endweek), where startweek and endweek are of the form YYYYWW (string or numeric).

Return type:

EpiDataCall

EpiDataContext.pub_kcdc_ili(regions, epiweeks='*', issues=None, lag=None)

Fetch KCDC ILI incidence (Korea).

API docs: <https://cmu-delphi.github.io/delphi-epidata/api/kcdc_ili.html>

Obtain information on influenza-like-illness from the Korea Centers for Disease Control and Prevention (KCDC).

The list of location argument can be found in <https://github.com/cmu-delphi/delphi-epidata/blob/main/labels/kcdc_regions.txt>.

Parameters:

  • regions (Union[str, Sequence[str]]) – List of regions to fetch. See Republic of Korea.

  • epiweeks (Union[int, str, EpiRange, EpiRangeDict, date, Week, Sequence[Union[int, str, EpiRange, EpiRangeDict, date, Week]]]) – Epiweeks to fetch. Supports EpiRange and defaults to all (“*”) weeks. Format as epirange(startweek, endweek), where startweek and endweek are of the form YYYYWW (string or numeric).

  • issues (Union[int, str, EpiRange, EpiRangeDict, date, Week, Sequence[Union[int, str, EpiRange, EpiRangeDict, date, Week]], None]) – Range or list of issue dates to fetch. Supports epirange(). Mutually exclusive with lag.

  • lag (int | None) – Number of days between the observation and its publication. Mutually exclusive with issues.

Return type:

EpiDataCall

EpiDataContext.pub_meta()

Fetch API metadata.

This is a V4 endpoint. Starting in October 2026, it is tentatively deprecated in favor of the V5 API. The new API can be accessed via the epidata_snapshot(), epidata_archive(), and epidata_meta() functions. For more details on the changes, refer to the migration guide, and visit the V5 signals documentation to see which sources are currently available.

API docs: <https://cmu-delphi.github.io/delphi-epidata/api/meta.html>

Return type:

EpiDataCall

EpiDataContext.pub_nidss_dengue(locations, epiweeks='*')

Fetch NIDSS dengue data (Taiwan).

API docs: <https://cmu-delphi.github.io/delphi-epidata/api/nidss_dengue.html>

Parameters:

  • locations (Union[str, Sequence[str]]) – List of Taiwan locations to fetch. See Taiwan Locations.

  • epiweeks (Union[int, str, EpiRange, EpiRangeDict, date, Week, Sequence[Union[int, str, EpiRange, EpiRangeDict, date, Week]]]) – Epiweeks to fetch. Supports EpiRange and defaults to all (“*”) weeks. Format as epirange(startweek, endweek), where startweek and endweek are of the form YYYYWW (string or numeric).

Return type:

EpiDataCall

EpiDataContext.pub_nidss_flu(regions, epiweeks='*', issues=None, lag=None)

Fetch NIDSS flu data (Taiwan).

API docs: <https://cmu-delphi.github.io/delphi-epidata/api/nidss_flu.html>

Parameters:

  • regions (Union[str, Sequence[str]]) –

    List of Taiwan locations to fetch. See Taiwan Locations.

  • epiweeks (Union[int, str, EpiRange, EpiRangeDict, date, Week, Sequence[Union[int, str, EpiRange, EpiRangeDict, date, Week]]]) – Epiweeks to fetch. Supports EpiRange and defaults to all (“*”) weeks. Format as epirange(startweek, endweek), where startweek and endweek are of the form YYYYWW (string or numeric).

  • issues (Union[int, str, EpiRange, EpiRangeDict, date, Week, Sequence[Union[int, str, EpiRange, EpiRangeDict, date, Week]], None]) – Range or list of issue dates to fetch. Supports epirange(). Mutually exclusive with lag.

  • lag (int | None) – Number of days between the observation and its publication. Mutually exclusive with issues.

Return type:

EpiDataCall

EpiDataContext.pub_nowcast(locations, epiweeks='*')

Fetch Delphi’s wILI nowcast.

API docs: <https://cmu-delphi.github.io/delphi-epidata/api/ili_nearby_nowcast.html>

Parameters:

  • locations (Union[str, Sequence[str]]) – List of locations to fetch. See Geographic Codes.

  • epiweeks (Union[int, str, EpiRange, EpiRangeDict, date, Week, Sequence[Union[int, str, EpiRange, EpiRangeDict, date, Week]]]) – Epiweeks to fetch. Supports EpiRange and defaults to all (“*”) weeks. Format as epirange(startweek, endweek), where startweek and endweek are of the form YYYYWW (string or numeric).

Return type:

EpiDataCall

EpiDataContext.pub_paho_dengue(regions, epiweeks='*', issues=None, lag=None)

Fetch PAHO Dengue data.

API docs: <https://cmu-delphi.github.io/delphi-epidata/api/paho_dengue.html>

Parameters:

  • regions (Union[str, Sequence[str]]) – List of American countries and territories to fetch. See Countries and Territories in the Americas.

  • epiweeks (Union[int, str, EpiRange, EpiRangeDict, date, Week, Sequence[Union[int, str, EpiRange, EpiRangeDict, date, Week]]]) – Epiweeks to fetch. Supports EpiRange and defaults to all (“*”) weeks. Format as epirange(startweek, endweek), where startweek and endweek are of the form YYYYWW (string or numeric).

  • issues (Union[int, str, EpiRange, EpiRangeDict, date, Week, Sequence[Union[int, str, EpiRange, EpiRangeDict, date, Week]], None]) – Range or list of issue dates to fetch. Supports epirange(). Mutually exclusive with lag.

  • lag (int | None) – Number of days between the observation and its publication. Mutually exclusive with issues.

Return type:

EpiDataCall

EpiDataContext.pub_wiki(articles, time_type, time_values='*', hours=None, language='en')

Fetch Wikipedia access data.

API docs: <https://cmu-delphi.github.io/delphi-epidata/api/wiki.html>

Parameters:

  • articles (Union[str, Sequence[str]]) – The Wikipedia article(s) to fetch. Supports a single string or a sequence of strings. See Available Articles.

  • time_type (Literal['day', 'week']) – The temporal resolution to use (“day” or “week”).

  • time_values (Union[int, str, EpiRange, EpiRangeDict, date, Week, Sequence[Union[int, str, EpiRange, EpiRangeDict, date, Week]]]) – Temporal points to fetch. Supports EpiRange and defaults to all (“*”) dates/weeks. Format as epirange(start, end), where start and end are of the form YYYY-MM-DD or YYYYWW depending on the time_type.

  • hours (Union[int, Sequence[int], None]) – A list of hours to include.

  • language (str) – Two-letter language code.

Return type:

EpiDataCall

Make requests to private API endpoints

These endpoints require additional authorization to use.

EpiDataContext.pvt_cdc(auth, locations, epiweeks='*')

Fetch CDC total and by topic webpage visits.

API docs: <https://cmu-delphi.github.io/delphi-epidata/api/cdc.html>

Parameters:

  • auth (str) – Private API key.

  • locations (Union[str, Sequence[str]]) – Geographic locations to return. Supports a single string or a sequence of strings. See Geographic Codes.

  • epiweeks (Union[int, str, EpiRange, EpiRangeDict, date, Week, Sequence[Union[int, str, EpiRange, EpiRangeDict, date, Week]]]) – Epiweeks to fetch. Supports EpiRange and defaults to all (“*”) weeks. Format as epirange(startweek, endweek), where startweek and endweek are of the form YYYYWW (string or numeric).

Return type:

EpiDataCall

EpiDataContext.pvt_dengue_sensors(auth, names, locations, epiweeks='*')

Fetch PAHO dengue digital surveillance sensors (North and South America).

API docs: <https://cmu-delphi.github.io/delphi-epidata/api/dengue_sensors.html>

Parameters:

  • auth (str) – Private API key.

  • names (Union[str, Sequence[str]]) – Sensor names to fetch. See Dengue Sensors Indicators.

  • locations (Union[str, Sequence[str]]) – List of countries in the Americas to fetch. See Countries and Territories in the Americas.

  • epiweeks (Union[int, str, EpiRange, EpiRangeDict, date, Week, Sequence[Union[int, str, EpiRange, EpiRangeDict, date, Week]]]) – Epiweeks to fetch. Supports EpiRange and defaults to all (“*”) weeks. Format as epirange(startweek, endweek), where startweek and endweek are of the form YYYYWW (string or numeric).

Return type:

EpiDataCall

EpiDataContext.pvt_ght(auth, locations, epiweeks='*', query='')

Fetch Google Health Trends data.

API docs: <https://cmu-delphi.github.io/delphi-epidata/api/ght.html>

Requires a private API key.

Parameters:

  • auth (str) – Private API key.

  • locations (Union[str, Sequence[str]]) – List of locations to fetch. See Geographic Codes.

  • epiweeks (Union[int, str, EpiRange, EpiRangeDict, date, Week, Sequence[Union[int, str, EpiRange, EpiRangeDict, date, Week]]]) – Epiweeks to fetch. Supports EpiRange and defaults to all (“*”) weeks. Format as epirange(startweek, endweek), where startweek and endweek are of the form YYYYWW (string or numeric).

  • query (str) – GHT search query. See Valid Queries.

Return type:

EpiDataCall

EpiDataContext.pvt_meta_norostat(auth)

Fetch NoroSTAT metadata.

API docs: <https://cmu-delphi.github.io/delphi-epidata/api/norostat_meta.html>

Requires a private API key.

Parameters:

auth (str) – Private API key.

Return type:

EpiDataCall

EpiDataContext.pvt_norostat(auth, location, epiweeks='*')

Fetch NoroSTAT data (point data, no min/max).

API docs: <https://cmu-delphi.github.io/delphi-epidata/api/norostat.html>

Requires a private API key.

Parameters:

  • auth (str) – Private API key.

  • location (str) – Locations to fetch. Only a specific list of full state names are permitted. See the locations column in the output of pvt_meta_norostat() for the allowed values.

  • epiweeks (Union[int, str, EpiRange, EpiRangeDict, date, Week, Sequence[Union[int, str, EpiRange, EpiRangeDict, date, Week]]]) – Epiweeks to fetch. Supports EpiRange and defaults to all (“*”) weeks. Format as epirange(startweek, endweek), where startweek and endweek are of the form YYYYWW (string or numeric).

Return type:

EpiDataCall

EpiDataContext.pvt_quidel(auth, locations, epiweeks='*')

Fetch Quidel data.

This is a V4 endpoint. Starting in October 2026, it is tentatively deprecated in favor of the V5 API. The new API can be accessed via the epidata_snapshot(), epidata_archive(), and epidata_meta() functions. For more details on the changes, refer to the migration guide, and visit the V5 signals documentation to see which sources are currently available.

API docs: <https://cmu-delphi.github.io/delphi-epidata/api/quidel.html>

Requires a private API key.

Parameters:

  • auth (str) – Private API key.

  • locations (Union[str, Sequence[str]]) – List of locations to fetch. See Geographic Codes.

  • epiweeks (Union[int, str, EpiRange, EpiRangeDict, date, Week, Sequence[Union[int, str, EpiRange, EpiRangeDict, date, Week]]]) – Epiweeks to fetch. Supports EpiRange and defaults to all (“*”) weeks. Format as epirange(startweek, endweek), where startweek and endweek are of the form YYYYWW (string or numeric).

Return type:

EpiDataCall

EpiDataContext.pvt_sensors(auth, names, locations, epiweeks='*')

Fetch Delphi’s digital surveillance sensors.

API docs: <https://cmu-delphi.github.io/delphi-epidata/api/digital_surveillance_sensors.html>

Requires a private API key.

Parameters:

  • auth (str) – Private API key.

  • names (Union[str, Sequence[str]]) – Sensor names to fetch. See Data Sources.

  • locations (Union[str, Sequence[str]]) – List of locations to fetch. See Geographic Codes.

  • epiweeks (Union[int, str, EpiRange, EpiRangeDict, date, Week, Sequence[Union[int, str, EpiRange, EpiRangeDict, date, Week]]]) – Epiweeks to fetch. Supports EpiRange and defaults to all (“*”) weeks. Format as epirange(startweek, endweek), where startweek and endweek are of the form YYYYWW (string or numeric).

Return type:

EpiDataCall

EpiDataContext.pvt_twitter(auth, locations, time_type, time_values='*')

Fetch HealthTweets data.

API docs: <https://cmu-delphi.github.io/delphi-epidata/api/twitter.html>

Requires a private API key.

Parameters:

  • auth (str) – Private API key.

  • locations (Union[str, Sequence[str]]) – List of locations to fetch. See Geographic Codes.

  • time_type (Literal['day', 'week']) – The temporal resolution to use (“day” or “week”).

  • time_values (Union[int, str, EpiRange, EpiRangeDict, date, Week, Sequence[Union[int, str, EpiRange, EpiRangeDict, date, Week]]]) – Temporal points to fetch. Supports EpiRange and defaults to all (“*”) dates/weeks. Format as epirange(start, end), where start and end are of the form YYYY-MM-DD or YYYYWW depending on the time_type.

Return type:

EpiDataCall

Make API requests

Discover endpoints and control how queries are built, cached, and fetched.

class EpiDataContext(base_url='https://api.delphi.cmu.edu/epidata/', session=None, use_cache=None, cache_max_age_days=None, cast_base_url='https://delphi.cmu.edu/epidata/v5/')

Endpoint catalog and synchronous fetcher for Delphi’s Epidata API.

Parameters:

  • base_url (str)

  • session (Session | None)

  • use_cache (bool | None)

  • cache_max_age_days (int | None)

  • cast_base_url (str)

class EpiDataCall(base_url, session, endpoint, params, meta=None, only_supports_classic=False, use_cache=None, cache_max_age_days=None, api_version='classic', post_filter=None, return_empty=False)

epidata call representation

Parameters:

  • base_url (str)

  • session (Session | None)

  • endpoint (str)

  • params (Mapping[str, EpiRangeParam | None])

  • meta (Sequence[EpidataFieldInfo] | None)

  • only_supports_classic (bool)

  • use_cache (bool | None)

  • cache_max_age_days (int | None)

  • api_version (ApiVersion)

  • post_filter (CastPostFilter | None)

  • return_empty (bool)

classic(fields=None, disable_date_parsing=False, disable_type_parsing=False)

Request and parse epidata in CLASSIC message format.

Parameters:

  • fields (Sequence[str] | None)

  • disable_date_parsing (bool | None)

  • disable_type_parsing (bool | None)

Return type:

EpiDataResponse

df(fields=None, disable_date_parsing=False)

Request and parse epidata as a pandas data frame

Parameters:

  • fields (Sequence[str] | None)

  • disable_date_parsing (bool | None)

Return type:

DataFrame

request_arguments(fields=None)

Format this call into a (URL, params) tuple.

Parameters:

fields (Sequence[str] | None)

Return type:

tuple[str, Mapping[str, str]]

request_url(fields=None)

Format this call into a full HTTP request url with encoded parameters.

Parameters:

fields (Sequence[str] | None)

Return type:

str

available_endpoints()

Get a DataFrame of available endpoints and their descriptions.

Return type:

DataFrame

Configuration and utilities

class EpiRange(start, end)

Range object for dates/epiweeks

Parameters:

  • start (Union[int, str, date, Week])

  • end (Union[int, str, date, Week])

exception InvalidArgumentException

exception for an invalid argument

exception EmptyResultWarning

A cast-API query returned no rows, or the local filters dropped them all.