Python Interface to COVID-19 Data Hub

This article was first published on Python Tutorials , and kindly contributed to python-bloggers. (You can report issue about the content on this page here)
Want to share your content on python-bloggers? click here.

The goal of COVID-19 Data Hub is to provide the research community with a unified dataset by collecting worldwide fine-grained case data, merged with exogenous variables helpful for a better understanding of COVID-19. Please agree to the Terms of Use and cite the following reference when using it:


Guidotti, E., Ardia, D., (2020).
COVID-19 Data Hub
Journal of Open Source Software, 5(51):2376

Setup and usage

Install from pip with

pip install covid19dh

Importing the main function covid19()

from covid19dh import covid19
x, src = covid19() 

Return values

The function covid19() returns 2 pandas dataframes:

  • the data and
  • references to the data sources.



List of country names (case-insensitive) or ISO codes (alpha-2, alpha-3 or numeric). The list of ISO codes can be found here.

Fetching data from a particular country:

x, src = covid19("USA") # Unites States

Specify multiple countries at the same time:

x, src = covid19(["ESP","PT","andorra",250])

If country is omitted, the whole dataset is returned:

x, src = covid19()

Raw data

Logical. Skip data cleaning? Default True. If raw=False, the raw data are cleaned by filling missing dates with NaN values. This ensures that all locations share the same grid of dates and no single day is skipped. Then, NaN values are replaced with the previous non-NaN value or 0.

x, src = covid19(raw = False)

Date filter

Date can be specified with datetime.datetime, or as a str in format YYYY-mm-dd.

from datetime import datetime
x, src = covid19("SWE", start = datetime(2020,4,1), end = "2020-05-01")


Integer. Granularity level of the data:

  1. Country level
  2. State, region or canton level
  3. City or municipality level
from datetime import date
x, src = covid19("USA", level = 2, start = date(2020,5,1))


Logical. Memory caching? Significantly improves performance on successive calls. By default, using the cached data is enabled.

Caching can be disabled (e.g. for long running programs) by:

x, src = covid19("FRA", cache = False)


Logical. Retrieve the snapshot of the dataset that was generated at the end date instead of using the latest version. Default False.

To fetch e.g. US data that were accessible on 22th April 2020 type

x, src = covid19("USA", end = "2020-04-22", vintage = True)

The vintage data are collected at the end of the day, but published with approximately 48 hour delay,
once the day is completed in all the timezones.

Hence if vintage = True, but end is not set, warning is raised and None is returned.

x, src = covid19("USA", vintage = True) # too early to get today's vintage
UserWarning: vintage data not available yet

Data Sources

The data sources are returned as second value.

from covid19dh import covid19
x, src = covid19("USA")


COVID-19 Data Hub harmonizes the amount of heterogeneous data that have become available around the pandemic. It represents a first effort towards open public data standards and sharing in light of COVID-19. Publications using COVID-19 Data Hub are available here.


COVID-19 Data Hub is supported by the Institute for Data Valorization IVADO, Canada. The covid19dh package was developed by Martin Beneš

[1] Guidotti, E., Ardia, D., (2020). COVID-19 Data Hub, Journal of Open Source Software, 5(51):2376

To leave a comment for the author, please follow the link and comment on their blog: Python Tutorials .

Want to share your content on python-bloggers? click here.