epidatpy Reference

epidatpy.request module

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

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)

Bases: object

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)

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

meta: Final[Sequence[EpidataFieldInfo]]
meta_by_name: Final[Mapping[str, EpidataFieldInfo]]
only_supports_classic: Final[bool]
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

use_cache: Final[bool]
with_base_url(base_url)
Parameters:

base_url (str)

Return type:

EpiDataCall

with_session(session)
Parameters:

session (Session)

Return type:

EpiDataCall

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/')

Bases: object

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)

epidata(source, signals, geo_type, geo_values='*', reference_time='*', fill_method=None, snapshot_date=None, report_time=None)

Router for CAST-API queries.

Dispatches to epidata_archive() when report_time is supplied or snapshot_date == "*"; otherwise to epidata_snapshot(). report_time and snapshot_date are mutually exclusive.

Parameters:

  • source (str)

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

  • geo_type (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 | int | None)

  • report_time (str | date | EpiRange | None)

Return type:

EpiDataCall

epidata_archive(source, signals, geo_type, geo_values='*', reference_time='*', fill_method=None, report_time='*')

Fetch the full report-time history of CAST-API signals.

report_time accepts an exact date, an operator-prefixed string (e.g. "<2025-10-16"), or an EpiRange. "*" (default) requests all report times. geo_values, reference_time, and the EpiRange lower bound are filtered locally after the API call.

Parameters:

  • source (str)

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

  • geo_type (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)

  • report_time (str | date | EpiRange | None)

Return type:

EpiDataCall

epidata_meta(source)

Fetch source-level metadata from the CAST API.

Returns the parsed JSON (a list of signal/geo descriptors) for source.

Parameters:

source (str)

Return type:

Any

epidata_snapshot(source, signals, geo_type, geo_values='*', reference_time='*', fill_method=None, snapshot_date=None)

Fetch a snapshot of CAST-API signals as they appeared on snapshot_date.

snapshot_date=None returns the latest available version. geo_values and reference_time are filtered locally after the API call.

Parameters:

  • source (str)

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

  • geo_type (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 | int | None)

Return type:

EpiDataCall

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

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

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

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.

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', '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

pub_covidcast_meta()

Fetch COVIDcast surveillance stream metadata.

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.

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

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

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

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

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

Fetch CDC FluSurv flu hospitalizations.

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

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

Fetch CDC FluView ILINet outpatient doctor visits.

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

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

Fetch CDC FluView flu tests from clinical labs.

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

pub_fluview_meta()

Fetch Metadata for the FluView endpoint.

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

Return type:

EpiDataCall

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

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

pub_meta()

Fetch API metadata.

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

Return type:

EpiDataCall

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

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

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

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

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

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

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

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

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

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

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

Fetch Quidel data.

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

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

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

with_base_url(base_url)
Parameters:

base_url (str)

Return type:

EpiDataContext

with_session(session)
Parameters:

session (Session)

Return type:

EpiDataContext

available_endpoints()

Get a DataFrame of available endpoints and their descriptions.

Return type:

DataFrame

epidatpy._endpoints module

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/')

Bases: object

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)

epidata(source, signals, geo_type, geo_values='*', reference_time='*', fill_method=None, snapshot_date=None, report_time=None)

Router for CAST-API queries.

Dispatches to epidata_archive() when report_time is supplied or snapshot_date == "*"; otherwise to epidata_snapshot(). report_time and snapshot_date are mutually exclusive.

Parameters:

  • source (str)

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

  • geo_type (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 | int | None)

  • report_time (str | date | EpiRange | None)

Return type:

EpiDataCall

epidata_archive(source, signals, geo_type, geo_values='*', reference_time='*', fill_method=None, report_time='*')

Fetch the full report-time history of CAST-API signals.

report_time accepts an exact date, an operator-prefixed string (e.g. "<2025-10-16"), or an EpiRange. "*" (default) requests all report times. geo_values, reference_time, and the EpiRange lower bound are filtered locally after the API call.

Parameters:

  • source (str)

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

  • geo_type (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)

  • report_time (str | date | EpiRange | None)

Return type:

EpiDataCall

epidata_meta(source)

Fetch source-level metadata from the CAST API.

Returns the parsed JSON (a list of signal/geo descriptors) for source.

Parameters:

source (str)

Return type:

Any

epidata_snapshot(source, signals, geo_type, geo_values='*', reference_time='*', fill_method=None, snapshot_date=None)

Fetch a snapshot of CAST-API signals as they appeared on snapshot_date.

snapshot_date=None returns the latest available version. geo_values and reference_time are filtered locally after the API call.

Parameters:

  • source (str)

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

  • geo_type (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 | int | None)

Return type:

EpiDataCall

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

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

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

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.

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', '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

pub_covidcast_meta()

Fetch COVIDcast surveillance stream metadata.

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.

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

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

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

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

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

Fetch CDC FluSurv flu hospitalizations.

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

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

Fetch CDC FluView ILINet outpatient doctor visits.

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

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

Fetch CDC FluView flu tests from clinical labs.

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

pub_fluview_meta()

Fetch Metadata for the FluView endpoint.

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

Return type:

EpiDataCall

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

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

pub_meta()

Fetch API metadata.

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

Return type:

EpiDataCall

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

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

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

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

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

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

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

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

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

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

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

Fetch Quidel data.

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

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

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

with_base_url(base_url)
Parameters:

base_url (str)

Return type:

EpiDataContext

with_session(session)
Parameters:

session (Session)

Return type:

EpiDataContext