🌍 Epidatasets

Sponsored by

AI-powered epidemiological intelligence

A Python library providing unified access to 41 epidemiological data sources from around the world, with a plugin registry, CLI, and optional extras for specialized data.

📋 Table of Contents

Overview
Installation
Quick Start
Repository Structure
Available Datasets
- Global
- North America
- South America
- Europe
- Africa
- Asia
- Oceania
CLI Usage
Usage Examples
Available Sources
FAQ
Contributing
Related Projects
Citation
License

🎯 Overview

epidatasets provides:

Unified interface — A single get_source() API to access 41 data sources worldwide
Plugin registry — Sources are discovered at runtime via entry_points, making it easy to extend
Optional extras — Install only the dependencies you need (pip install epidatasets[who,brazil])
CLI — Command-line tool for listing sources, inspecting metadata, and querying countries
Caching & rate limiting — Built-in utilities for responsible API usage
Reproducible research — Standardized access to heterogeneous epidemiological datasets

📦 Installation

From PyPI

pip install epidatasets

With optional extras

# WHO Global Health Observatory data
pip install epidatasets[who]

# Brazilian DATASUS/SINAN data via PySUS
pip install epidatasets[brazil]

# Eurostat EU health statistics
pip install epidatasets[eurostat]

# Climate/environmental data (Copernicus CDS)
pip install epidatasets[climate]

# Google Earth Engine satellite imagery
pip install epidatasets[earthengine]

# Geospatial visualization
pip install epidatasets[geo]

# Plotting & visualization
pip install epidatasets[viz]

# Genomic data (Pathoplexus)
pip install epidatasets[genomics]

# CLI support
pip install epidatasets[cli]

# World Bank indicators
pip install epidatasets[worldbank]

# Install everything
pip install epidatasets[all]

Development installation

git clone https://github.com/fccoelho/epidemiological-datasets.git
cd epidemiological-datasets
pip install -e ".[dev,docs]"

🚀 Quick Start

from epidatasets import get_source, list_sources

# Discover available sources
sources = list_sources()
for name, meta in sorted(sources.items()):
    print(f"{name}: {meta['description']}")

# Get a specific source
paho = get_source("paho")
countries = paho.list_countries()
print(f"PAHO covers {len(countries)} countries")

# Get WHO data (requires: pip install epidatasets[who])
who = get_source("who")
malaria = who.get_indicator(
    indicator="MALARIA_EST_INCIDENCE",
    years=[2020, 2021, 2022],
    countries=["BRA", "IND", "NGA"]
)

# Get OWID COVID-19 data
owid = get_source("owid")
covid = owid.get_covid_data(
    countries=["BRA", "USA", "IND"],
    metrics=["cases", "deaths"]
)

📁 Repository Structure

epidemiological-datasets/
├── src/epidatasets/           # Main Python package
│   ├── __init__.py            # Public API (get_source, list_sources)
│   ├── _base.py               # BaseAccessor ABC
│   ├── _registry.py           # Plugin registry (entry_points)
│   ├── cli.py                 # CLI (typer)
│   ├── newsfeeds/             # RSS/news-feed aggregator + spatiotemporal viz
│   ├── sources/               # 32 data source accessors
│   │   ├── __init__.py
│   │   ├── africa_cdc.py
│   │   ├── cdc_opendata.py
│   │   ├── china_cdc.py
│   │   ├── hk_chp.py
│   │   ├── colombia_ins.py
│   │   ├── copernicus_cds.py
│   │   ├── datasus_pysus.py
│   │   ├── ecdc_opendata.py
│   │   ├── epipulse.py
│   │   ├── eurostat.py
│   │   ├── global_health.py
│   │   ├── google_earth_engine.py
│   │   ├── healthdata_gov.py
│   │   ├── india_idsp.py
│   │   ├── infodengue_api.py
│   │   ├── malaria_atlas.py
│   │   ├── nhs_prescribing.py
│   │   ├── nz_health.py
│   │   ├── oman_moh.py
│   │   ├── opendengue.py
│   │   ├── owid.py
│   │   ├── paho.py
│   │   ├── pakistan_nih.py
│   │   ├── pathoplexus.py
│   │   ├── respicast.py
│   │   ├── rki_germany.py
│   │   ├── srag_opendata_sus.py
│   │   ├── swiss_bag.py
│   │   ├── ukhsa.py
│   │   └── who_ghoclient.py
│   └── utils/                 # Utilities
│       ├── cache.py           # Caching layer
│       ├── rate_limit.py      # API rate limiting
│       ├── geo.py             # Geospatial helpers
│       ├── validation.py      # Data validation
│       └── io.py              # I/O utilities
├── tests/                     # Test suite
│   ├── sources/
│   ├── utils/
│   ├── conftest.py
│   └── ...
├── docs/                      # MkDocs documentation
│   ├── mkdocs.yml
│   └── docs/
│       ├── index.md
│       ├── installation.md
│       ├── quickstart.md
│       ├── sources/           # Per-source API docs (36 pages)
│       ├── api/               # API reference
│       │   ├── base.md
│       │   ├── registry.md
│       │   ├── cli.md
│       │   └── utils.md
│       └── examples/          # Jupyter notebooks
├── mkdocs.yml                 # Docs config
├── .readthedocs.yaml          # ReadTheDocs config
├── pyproject.toml             # Package configuration
└── README.md

🌐 Available Datasets

Global 🌍

Dataset	Description	Update Frequency	Access Level	Module
WHO Global Health Observatory	Health indicators by country	Annual	Open	`epidatasets.sources.who_ghoclient`
disease.sh	Global COVID-19 & influenza statistics (real-time, historical, vaccines)	Real-time	Open	`epidatasets.sources.disease_sh`
Our World in Data - Health	COVID-19, vaccination, excess mortality	Daily/Weekly	Open	`epidatasets.sources.owid`
Global Health Data Exchange (GHDx)	Catalog of health datasets	Varies	Varies	Catalog only
HDX (Humanitarian Data Exchange)	Health in crisis contexts	Real-time	Open	Planned
Global.health	Pandemic linelist data	Varies	Open	`epidatasets.sources.global_health`
GMPD (Global Mammal Parasite Database)	Wild mammal host-parasite associations (primates, carnivores, ungulates)	Irregular	Open	`epidatasets.sources.gmpd`
OpenDengue	Global dengue case counts (100+ countries, adm0–adm2, 1924–present; CC BY 4.0)	Monthly	Open	`epidatasets.sources.opendengue`
Malaria Atlas Project	Malaria prevalence & vector data	Annual	Open	`epidatasets.sources.malaria_atlas`
Copernicus Climate Data Store	Environmental & climate data	Varies	Open	`epidatasets.sources.copernicus_cds`
Google Earth Engine	Satellite imagery (Landsat, Sentinel-2, MODIS) — vegetation, built-up, water indices	Varies (per-scene)	Free registration	`epidatasets.sources.google_earth_engine`
Pathoplexus	Pathogen genomic data	Continuous	Open	`epidatasets.sources.pathoplexus`
InfoDengue	Dengue surveillance (Brazil)	Weekly	Open	`epidatasets.sources.infodengue_api`

North America 🇺🇸🇨🇦🇲🇽

Dataset	Description	Update Frequency	Access Level	Module
CDC Open Data	CDC datasets portal (COVID-19, Influenza, NNDSS, CDI)	Varies	Open	`epidatasets.sources.cdc_opendata`
HealthData.gov	US health system data	Weekly	Open	`epidatasets.sources.healthdata_gov`
Statistics Canada - Health	Canadian health data	Quarterly	Open	Planned

South America 🌎

Dataset	Description	Update Frequency	Access Level	Module
SINAN / DATASUS - Brazil	Brazilian notifiable diseases & health system data	Weekly	Open*	`epidatasets.sources.datasus_pysus`
SRAG 2019–2026 (OpenData SUS)	Brazilian severe acute respiratory syndrome line-level surveillance (Sivep-Gripe / e-SUS Notifica)	Weekly	Open	`epidatasets.sources.srag_opendata_sus`
PAHO/WHO Regional Data	Pan-American health data	Monthly	Open	`epidatasets.sources.paho`
Chile DEIS	Chilean health statistics	Monthly	Open	Planned
Colombia INS	Colombian public health data (SIVIGILA)	Weekly	Open	`epidatasets.sources.colombia_ins`

*Note: DATASUS access requires pip install epidatasets[brazil] (installs PySUS).

Europe 🇪🇺

Dataset	Description	Update Frequency	Access Level	Module
ECDC EpiPulse	European surveillance portal (53 countries, 50+ diseases)	Daily/Weekly	Registration	`epidatasets.sources.epipulse`
ECDC Open Data	Infectious disease surveillance (50+ diseases, 30 countries)	Weekly	Open	`epidatasets.sources.ecdc_opendata`
ECDC RespiCast	Respiratory disease forecasting hub	Weekly	Open	`epidatasets.sources.respicast`
Eurostat Health	EU health statistics	Annual	Open	`epidatasets.sources.eurostat`
UK Health Security Agency	UK health data	Weekly	Open	`epidatasets.sources.ukhsa`
NHS England Prescribing (OpenPrescribing + EPD)	NHS primary care prescribing: spending, antibiotic stewardship measures, practice-level EPD bulk data	Monthly	Open	`epidatasets.sources.nhs_prescribing`
Robert Koch Institute	German surveillance data	Weekly	Open	`epidatasets.sources.rki_germany`
Swiss BAG Infectious Diseases Dashboard	Swiss national & cantonal surveillance: notifiable diseases, sentinel ILI/ARI, wastewater viral load, antimicrobial resistance	Weekly (Wed)	Open	`epidatasets.sources.swiss_bag`

Africa 🌍

Dataset	Description	Update Frequency	Access Level	Module
WHO Afro Health Observatory	African region health data	Annual	Open	`epidatasets.sources.who_ghoclient`
Africa CDC	African public health data (55 AU member states)	Weekly	Open	`epidatasets.sources.africa_cdc`

Asia 🌏

Dataset	Description	Update Frequency	Access Level	Module
China CDC Weekly	Chinese surveillance data (notifiable diseases, CNIC influenza, weekly multi-pathogen respiratory sentinel ILI/SARI surveillance, monthly overviews, COVID-19)	Weekly	Open	`epidatasets.sources.china_cdc`
Flu Express (data.gov.hk)	Hong Kong influenza & COVID-19 surveillance	Weekly	Open	`epidatasets.sources.hk_chp`
IDSP India	Indian disease surveillance	Weekly	Open*	`epidatasets.sources.india_idsp`
Oman MOH	Omani annual health reports (morbidity, mortality, indicators)	Annual	Open	`epidatasets.sources.oman_moh`
Pakistan NIH	Pakistan IDSR weekly surveillance bulletins	Weekly	Open	`epidatasets.sources.pakistan_nih`
Japan IDWR (JIHS)	Prefecture-level weekly surveillance of notifiable & sentinel diseases (2023+)	Weekly	Open	`epidatasets.sources.japan_idwr`
Korea CDC	Korean disease control data	Weekly	Open	Planned

Oceania 🇦🇺🇳🇿

Dataset	Description	Update Frequency	Access Level	Module
Australian Institute of Health and Welfare	Australian health data	Annual	Open	Planned
NZ Ministry of Health	New Zealand health statistics (mortality, life tables, hospital events, immunisation)	Annual	Open	`epidatasets.sources.nz_health`

💻 CLI Usage

The epidatasets CLI provides quick access from the terminal (requires pip install epidatasets[cli]):

# List all available data sources
epidatasets sources

# Show detailed info about a source
epidatasets info who

# List countries covered by a source
epidatasets countries paho

News-feed aggregator subcommands:

epidatasets news feeds                                  # list feeds
epidatasets news fetch --days 30 -o items.csv           # fetch + tag
epidatasets news fetch --query "dengue when:30d" -o dengue.csv
epidatasets news plot items.csv --timeline -o timeline.png
epidatasets news map items.csv -o news_map.html         # interactive HTML
epidatasets news animate items.csv -o news_map.gif      # cumulative GIF

💡 Usage Examples

Example 0: Public-health news feeds (early-warning signals)

from epidatasets.newsfeeds import NewsAggregator

agg = NewsAggregator()                       # feeds cached on disk (TTL 6h)
items = agg.fetch(days=30)                   # WHO, PAHO, CDC, CIDRAP, ...
locations = agg.geotag(items)                # country/city mentions -> iso3, lat, lon

agg.plot_timeline(items, by="disease_tags", out="timeline.png")
agg.plot_map(locations, out="news_map.html")
agg.animate_map(locations, out="news_map.gif")

Requires pip install "epidatasets[news,geo]". See the news-feed aggregator docs for the full feed inventory and licensing notes.

Example 1: WHO Global Health Data

from epidatasets import get_source

who = get_source("who")

# Get malaria incidence data
data = who.get_indicator(
    indicator="MALARIA_EST_INCIDENCE",
    years=[2020, 2021, 2022],
    countries=["BRA", "IND", "NGA"]
)
print(data.head())

Example 2: PAHO Pan-American Health Data

from epidatasets import get_source

paho = get_source("paho")

# List member countries
countries = paho.list_countries()
print(f"Total countries: {len(countries)}")

# Get immunization coverage
coverage = paho.get_immunization_coverage(
    vaccines=['DTP3', 'MCV1'],
    subregion='Southern Cone',
    years=[2020, 2021, 2022]
)

# Compare health indicators
comparison = paho.compare_countries(
    indicator='LIFE_EXPECTANCY',
    countries=['BRA', 'MEX', 'ARG', 'COL'],
    years=[2019, 2020, 2021]
)

Example 3: Eurostat EU Health Statistics

from epidatasets import get_source

eurostat = get_source("eurostat")

# Healthcare expenditure
expenditure = eurostat.get_healthcare_expenditure(
    countries=['DEU', 'FRA', 'ITA'],
    years=list(range(2015, 2024))
)

# Mortality data by cause
mortality = eurostat.get_mortality_data(
    cause_code='COVID-19',
    countries=['DEU', 'FRA', 'ITA'],
    years=[2020, 2021, 2022]
)

# Life expectancy comparison
life_exp = eurostat.get_life_expectancy(
    countries=['DEU', 'FRA', 'ITA', 'ESP'],
    years=[2019, 2020, 2021]
)

Example 4: Our World in Data

from epidatasets import get_source

owid = get_source("owid")

# COVID-19 data for specific countries
covid = owid.get_covid_data(
    countries=['BRA', 'USA', 'IND'],
    metrics=['cases', 'deaths', 'hospitalizations'],
    start_date='2021-01-01',
    end_date='2021-12-31'
)

# Excess mortality estimates
excess = owid.get_excess_mortality(
    countries=['GBR', 'ITA', 'USA'],
    start_date='2020-03-01'
)

# Global summary
summary = owid.get_global_summary()

Example 5: Brazil DATASUS via PySUS

from epidatasets import get_source

datasus = get_source("datasus")

# Access Brazilian notifiable disease data
dengue = datasus.download(
    disease="Dengue",
    years=[2022, 2023],
    states=["RJ", "SP", "MG"]
)

Example 6: Africa CDC Data

from epidatasets import get_source

africa_cdc = get_source("africa_cdc")

# List all 55 African Union member states
countries = africa_cdc.list_countries()

# Get disease outbreaks
ebola = africa_cdc.get_disease_outbreaks(
    disease='EBOLA',
    countries=['CD', 'UG', 'GN']
)

# Vaccination coverage
vax = africa_cdc.get_vaccination_coverage(
    countries=['NG', 'ET', 'ZA'],
    vaccines=['COVID-19', 'Measles']
)

Example 7: RKI Germany Surveillance

from epidatasets import get_source

rki = get_source("rki")

# COVID-19 nowcasting with R estimates
nowcast = rki.get_covid_nowcast(
    date_range=('2022-01-01', '2022-06-30')
)

# Influenza surveillance
flu = rki.get_influenza_data(seasons=['2022/23', '2023/24'])

Example 8: Multi-source Comparison

from epidatasets import get_source, list_sources

# See all available sources
print(list_sources().keys())

# Compare data across sources
who = get_source("who")
owid = get_source("owid")

who_malaria = who.get_indicator(
    indicator="MALARIA_EST_INCIDENCE",
    years=[2022],
    countries=["BRA"]
)

owid_covid = owid.get_covid_data(
    countries=["BRA"],
    metrics=["cases", "deaths"],
    start_date='2022-01-01',
    end_date='2022-12-31'
)

Example 9: disease.sh Global COVID-19 & Influenza

from epidatasets.sources.disease_sh import DiseaseShAccessor, DiseaseShAPIError

ds = DiseaseShAccessor()  # optional: cache_ttl_hours=24 for influenza

# Global COVID-19 totals
totals = ds.get_global_totals()

# Per-country current data (name, ISO-2 or ISO-3)
brazil = ds.get_country_data("BRA")

# Historical time series with date filtering
hist = ds.get_historical(
    country=["USA", "BRA"],
    lastdays=90,
    start_date="2023-01-01",
    end_date="2023-03-01",
)

# Vaccine coverage and US CDC influenza surveillance
vax = ds.get_vaccine_coverage(country="USA", lastdays=60)
ili = ds.get_influenza_ilinet()

# Clear errors: invalid country -> ValueError, API failures -> DiseaseShAPIError
try:
    ds.get_country_data("Atlantis")
except ValueError as e:
    print(e)

Example 10: NHS England Prescribing (OpenPrescribing + EPD)

from epidatasets.sources.nhs_prescribing import NHSPrescribingAccessor

nhs = NHSPrescribingAccessor()  # filesystem cache, 7-day TTL (monthly releases)

# National monthly spending on antibacterials (BNF 5.1)
spending = nhs.get_spending(bnf_code="5.1")

# Spending by CCG/SICBL for a single month
ccg = nhs.get_spending_by_ccg(bnf_code="5.1", year_month="2024-01")

# Practice-level spending within a CCG
practice = nhs.get_spending_by_practice(bnf_code="5.1", ccg_code="15N", year_month="2024-01")

# Prescribing quality measures (e.g. antibiotic stewardship)
measures = nhs.get_measures(measure="ktt9_antibiotics", org_type="practice", org_code="L81001")

# Practice locations for spatial analysis (lat/lon from GeoJSON)
practices = nhs.get_practice_locations(ccg_code="15N")

# NHSBSA English Prescribing Dataset (EPD) bulk CSVs — practice-level,
# SNOMED-coded, ~600M rows/year. Chunked + BNF-filtered reading:
chunks = nhs.get_epd_month(2024, 1, bnf_section="5.1", chunksize=500_000)
for chunk in chunks:  # lazy evaluation for large files
    ...

# Monthly time-series for a single chemical (e.g. amoxicillin)
ts = nhs.get_epd_timeseries("0501013B0", "2024-01", "2024-06")

Example 11: Brazilian SRAG line-level surveillance (Sivep-Gripe)

from epidatasets.sources.srag_opendata_sus import SRAGOpenDataSUSAccessor

srag = SRAGOpenDataSUSAccessor()

# Years available on the OpenData SUS portal
srag.available_years()  # [2019, 2020, ..., 2026]

# One year of line-level records (chunked download + lazy reading;
# 0.5-3 GB per year). All filters are composable:
df = srag.get_year(
    2024,
    state="RJ",                  # residence state
    municipality_code=3304557,   # IBGE municipality (6 or 7 digits)
    week_start=1, week_end=26,   # epidemiological weeks
    pathogen="SARS-CoV-2",       # or "Influenza", "VSR"/"RSV", ...
    outcome="death",             # or "cure"
    age_min=60,
    columns=["DT_NOTIFIC", "SEM_NOT", "SG_UF", "EVOLUCAO"],  # narrow early
)

# Memory-bounded chunk iteration for very large years
for chunk in srag.get_year(2022, chunksize=500_000):
    ...

# Weekly counts by geography and pathogen across years
ts = srag.get_weekly_counts(
    years=[2022, 2023, 2024],
    groupby="state",
    pathogens=["SARS-CoV-2", "Influenza", "VSR"],
)

# IBGE municipality helpers
srag.municipality_name(3304557)          # 'Rio de Janeiro'
srag.municipality_code("São Paulo")      # '3550308'

Example 12: Global dengue surveillance (OpenDengue)

Citation required (CC BY 4.0): Clarke J, Lim A, Gupte P, Pigott DM, van Panhuis WG, Brady OJ. A global dataset of publicly available dengue case count data. Sci Data 11, 296 (2024). https://doi.org/10.1038/s41597-024-03120-7

from epidatasets.sources.opendengue import OpenDengueAccessor

od = OpenDengueAccessor()
print(od.citation())  # mandatory citation for CC BY 4.0

# Global extracts: "national", "highest_spatial", "highest_temporal"
global_national = od.get_global(level="national")

# Countries covered (name + ISO3)
od.list_countries()

# Country series with fuzzy name matching and ISO3 codes
bra = od.get_country("Brasil")                      # fuzzy -> BRAZIL
bra = od.get_country(
    "BRA",
    start_date="2015-01-01",
    end_date="2024-12-31",
    admin_level=1,        # state-level series only
)

# One location's time-series
rj = od.get_timeseries("Brazil", admin1="Rio de Janeiro")

# Underlying data-source series per country
od.get_sources(country="India")

📊 Available Sources

Source Name	Class	Extra	Description
`africa_cdc`	`AfricaCDCAccessor`	—	Africa CDC public health data (55 AU states)
`cdc_opendata`	`CDCOpenDataAccessor`	—	US CDC Open Data portal
`china_cdc`	`ChinaCDCAccessor`	—	China surveillance: CDC Weekly, NDCPA monthly overviews, CNIC influenza, weekly respiratory sentinel ILI/SARI positivity, COVID-19
`hk_chp`	`HongKongCHPAccessor`	—	Hong Kong CHP Flu Express & COVID-19 open data
`colombia_ins`	`ColombiaINSAccessor`	—	Colombia INS/SIVIGILA surveillance
`copernicus_cds`	`CopernicusCDSAccessor`	`[climate]`	Copernicus Climate Data Store
`datasus`	`DataSUSAccessor`	`[brazil]`	Brazilian DATASUS/SINAN (via PySUS)
`disease_sh`	`DiseaseShAccessor`	—	disease.sh global COVID-19 & influenza statistics
`ecdc`	`ECDCOpenDataAccessor`	—	ECDC infectious disease data
`epipulse`	`EpiPulseAccessor`	—	ECDC EpiPulse surveillance portal
`eurostat`	`EurostatAccessor`	`[eurostat]`	EU health statistics
`global_health`	`GlobalHealthAccessor`	—	Global.health pandemic linelist data
`gmpd`	`GMPDAccessor`	—	Global Mammal Parasite Database (wild mammals)
`healthdata_gov`	`HealthDataGovAccessor`	—	US HealthData.gov
`india_idsp`	`IndiaIDSPAccessor`	—	India IDSP disease surveillance
`infodengue`	`InfoDengueAPI`	—	InfoDengue dengue surveillance (Brazil)
`japan_idwr`	`JapanIDWRAccessor`	—	Japan IDWR prefecture-level weekly surveillance (2023+)
`opendatasus`	`OpenDataSUSAccessor`	—	OpenDataSUS catalog (dadosabertos.saude.gov.br): list datasets, metadata & downloads
`malaria_atlas`	`MalariaAtlasAccessor`	—	Malaria Atlas Project data
`nhs_prescribing`	`NHSPrescribingAccessor`	—	NHS England prescribing (OpenPrescribing API + NHSBSA EPD bulk CSVs)
`opendengue`	`OpenDengueAccessor`	—	Global dengue case counts, 100+ countries (CC BY 4.0 — cite Clarke et al. 2024)
`nz_health`	`NZHealthAccessor`	—	New Zealand health statistics (Stats NZ & Health NZ)
`oman_moh`	`OmanMOHAccessor`	—	Oman Ministry of Health annual reports
`owid`	`OWIDAccessor`	—	Our World in Data (COVID-19, vaccination)
`paho`	`PAHOAccessor`	—	PAHO Pan-American health data
`pakistan_nih`	`PakistanNIHAccessor`	—	Pakistan NIH IDSR surveillance
`pathoplexus`	`PathoplexusAccessor`	`[genomics]`	Pathoplexus pathogen genomic data
`respicast`	`RespiCastAccessor`	—	ECDC respiratory disease forecasting
`rki`	`RKIGermanyAccessor`	—	Robert Koch Institute (Germany)
`srag`	`SRAGOpenDataSUSAccessor`	—	Brazilian SRAG line-level surveillance (Sivep-Gripe / e-SUS Notifica)
`swiss_bag`	`SwissBAGAccessor`	—	Swiss BAG IDD: 54 topics, national & cantonal (26 cantons), weekly versions since 2023-11
`ukhsa`	`UKHSAAccessor`	—	UK Health Security Agency
`who`	`WHOAccessor`	`[who]`	WHO Global Health Observatory

❓ FAQ

What is epidatasets?

A Python library providing a unified interface to 41 epidemiological data sources worldwide, installable via pip install epidatasets.

Do I need to install all optional dependencies?

No. The base install covers most sources. Only install extras for sources that need them (e.g., pip install epidatasets[who] for WHO GHO data, pip install epidatasets[brazil] for DATASUS).

How do I discover available sources?

from epidatasets import list_sources
print(list_sources())

Or from the CLI: epidatasets sources

Are all dataset accessors fully implemented?

Most accessors provide working data retrieval. Some are structured placeholders for sources that require registration or have limited public APIs. Check the documentation for each source's status.

Can I contribute a new data source?

Yes! Sources are registered via entry_points in pyproject.toml. See CONTRIBUTING.md for guidelines on adding new accessors.

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for detailed guidelines.

Quick Links for Contributors

📋 Contributing Guide - How to get started
🐛 Report a Bug
💡 Request a Feature
🌍 Request a Data Source
💬 GitHub Discussions - Ask questions, share ideas

Priority Contributions

New data source accessors - Especially from underrepresented regions
Example notebooks - Jupyter notebooks demonstrating data analysis
Documentation - Translations, improvements, and API docs
Bug fixes - Check the issue tracker

Badges for Contributors

📚 Related Projects

Project	Description	Repository
PySUS	Brazilian health data (DATASUS)	AlertaDengue/PySUS
ghoclient	WHO Global Health Observatory	fccoelho/ghoclient
epigrass	Epidemic simulation	EpiGrass/epigrass
epimodels	Mathematical epidemiology	fccoelho/epimodels

📊 Statistics

Data sources: 39 registered (via plugin registry)
Countries covered: 100+
Optional extras: 15 (who, brazil, eurostat, earthengine, climate, geo, viz, genomics, cli, worldbank, search, scraping, gisaid, pdf, news)
Example notebooks: 47
Documentation: epidatasets.readthedocs.io

📚 Citation

If you use this package in your research, please cite:

@misc{fccoelho_epidatasets,
  author = {Coelho, Flávio Codeço},
  title = {Epidatasets: Python Access to Epidemiological Datasets Worldwide},
  year = {2026},
  publisher = {GitHub},
  journal = {GitHub Repository},
  howpublished = {\url{https://github.com/fccoelho/epidemiological-datasets}}
}

For PySUS:

@software{pysus,
  author = {AlertaDengue Team},
  title = {PySUS: Tools for Brazilian Public Health Data},
  url = {https://github.com/AlertaDengue/PySUS}
}

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

💜 Sponsor

This project is sponsored by

Kwar-AI — Intelligence for Epidemiology

AI-powered solutions for disease surveillance and outbreak prediction

🙏 Acknowledgments

PySUS Contributors - For making Brazilian health data accessible
WHO - For maintaining the Global Health Observatory
All data providers who make epidemiological data openly accessible
Global public health community

📞 Contact

Author: Flávio Codeço Coelho (@fccoelho)
Website: https://fccoelho.github.io/
Documentation: https://epidatasets.readthedocs.io

Made with ❤️ for the epidemiological research community

🐛 Report Bug • 💡 Request Feature • 💬 Discussions

Disclaimer: This repository is a community effort to catalog open data sources. Please always refer to the original data providers for official statistics and verify data usage terms. The maintainers are not responsible for data quality or availability.

Name		Name	Last commit message	Last commit date
.github		.github
assets		assets
bin		bin
config		config
data		data
docs		docs
src/epidatasets		src/epidatasets
tests		tests
.gitignore		.gitignore
.readthedocs.yaml		.readthedocs.yaml
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
ECDC_DATA_SOURCES.md		ECDC_DATA_SOURCES.md
LICENSE		LICENSE
README.md		README.md
coverage.xml		coverage.xml
mkdocs.yml		mkdocs.yml
pyproject.toml		pyproject.toml
requirements-dev.txt		requirements-dev.txt
requirements.txt		requirements.txt
uv.lock		uv.lock

Latest commit

History

Folders and files

Repository files navigation