Covid-19 JHU CSSE Getting Started: Data Access and Usage (2026)

Getting started overview

The Johns Hopkins University Center for Systems Science and Engineering (JHU CSSE) COVID-19 data repository offers a comprehensive dataset for tracking the pandemic. Unlike many data services, the JHU CSSE data is not accessed via a traditional REST API requiring authentication keys. Instead, all data is publicly available through a GitHub repository, primarily in Comma Separated Values (CSV) format. This approach simplifies initial access, as developers and researchers can directly download the files or clone the repository to retrieve the latest information.

The data is structured to provide daily reports, time series data, and supplementary information on global COVID-19 cases, deaths, and recoveries. This direct access model makes it suitable for integration into various analytical tools, dashboards, and research projects without the overhead of API key management or rate limit considerations inherent in traditional API services.

The core process for getting started involves identifying the specific CSV files you need within the repository and then implementing a method to fetch or update these files programmatically or manually. This guide will walk through accessing the data, understanding its structure, and making your first data retrieval.

Create an account and get keys

Accessing the Covid-19 JHU CSSE dataset does not require account creation, API keys, or any form of authentication. The data is maintained in a public GitHub repository, making it freely available to anyone with internet access. This design choice aims to maximize accessibility for researchers, public health officials, and the general public without proprietary barriers.

Therefore, to begin, you do not need to register on any platform or generate credentials. You can proceed directly to accessing the data files as described in the next section. This simplifies the onboarding process significantly compared to services that utilize OAuth 2.0 or API key authentication, which require initial setup steps such as registering an application and managing client secrets or personal access tokens, as detailed in OAuth 2.0 specifications or AWS access key best practices.

Your first request

Since the JHU CSSE data is hosted on GitHub as CSV files, a "first request" typically involves downloading a specific CSV file. We will demonstrate how to directly access the daily reports using a common programming language, Python, and then provide an example for command-line access.

Data Structure Overview

The primary data is found in the csse_covid_19_data directory within the GitHub repository. Key subdirectories include:

• csse_covid_19_daily_reports: Daily reports with cumulative data by administrative division.
• csse_covid_19_time_series: Time series data for confirmed, deaths, and recovered cases.
• csse_covid_19_unified_dataset: A more recent unified dataset offering consolidated information.

For this example, we will retrieve a daily report.

Example: Retrieving a daily report using Python

This Python script downloads a specific daily report CSV file directly from the GitHub repository using the requests library.

import requests

# Define the base URL for the daily reports
base_url = "https://raw.githubusercontent.com/CSSEGISandData/COVID-19/master/csse_covid_19_data/csse_covid_19_daily_reports/"

# Define the date for the report (e.g., May 28, 2026). Format: MM-DD-YYYY
report_date = "05-28-2026"
file_name = f"{report_date}.csv"
full_url = f"{base_url}{file_name}"

try:
    # Make the HTTP GET request
    response = requests.get(full_url)
    response.raise_for_status() # Raise an HTTPError for bad responses (4xx or 5xx)

    # Decode the content and print the first few lines
    data = response.text
    print(f"Successfully retrieved data for {report_date}.")
    print("First 5 lines of the CSV file:")
    for i, line in enumerate(data.splitlines()):
        if i < 5:
            print(line)
        else:
            break

    # Optionally, save the data to a local file
    # with open(file_name, 'w', encoding='utf-8') as f:
    #     f.write(data)
    # print(f"Data saved to {file_name}")

except requests.exceptions.RequestException as e:
    print(f"Error retrieving data: {e}")
    print(f"Please check the URL: {full_url} and date format.")

Before running this script, ensure you have the requests library installed (pip install requests).

Example: Retrieving data using curl (command line)

For command-line access, you can use curl to download the file directly:

curl -o 05-28-2026.csv "https://raw.githubusercontent.com/CSSEGISandData/COVID-19/master/csse_covid_19_data/csse_covid_19_daily_reports/05-28-2026.csv"

This command downloads the daily report for May 28, 2026, and saves it as 05-28-2026.csv in your current directory. The -o flag specifies the output filename.

Common next steps

After successfully retrieving your first CSV file, several common next steps emerge for utilizing the Covid-19 JHU CSSE data effectively:

1. Automate Data Retrieval: For applications requiring up-to-date information, automate the daily download of the latest CSV files. This can be achieved using cron jobs on Linux/macOS, Windows Task Scheduler, or cloud functions (e.g., Google Cloud Functions, AWS Lambda) that trigger a script to fetch new data at regular intervals. Ensure your automation handles potential network issues or changes in the GitHub repository structure.
2. Data Parsing and Cleaning: The raw CSV data may require parsing and cleaning specific to your application's needs. This often involves converting data types (e.g., strings to numbers for case counts), handling missing values, and standardizing column names. Libraries like Pandas in Python or readr in R are highly effective for these tasks.
3. Database Integration: For large-scale analysis or long-term storage, integrate the downloaded data into a relational database (e.g., PostgreSQL, MySQL) or a NoSQL database. This allows for more complex querying, historical trend analysis, and efficient data serving to front-end applications. Consider data warehousing solutions for aggregated historical data.
4. Data Visualization: Utilize the data to create dashboards, charts, and maps. Tools like Tableau, Power BI, D3.js, or Python libraries such as Matplotlib, Seaborn, and Plotly can render compelling visualizations of case trends, geographical distribution, and mortality rates. The JHU CSSE data is frequently used in mapping applications, often overlaid on geographical base maps provided by services like ArcGIS with COVID-19 datasets.
5. Advanced Analysis: Conduct epidemiological modeling, predictive analytics, or comparative studies. The time series data, in particular, is valuable for analyzing growth rates, doubling times, and the impact of public health interventions. Machine learning techniques can be applied to forecast future case numbers or identify correlations with other public health metrics.
6. Contribute to an Open-Source Project: If your work enhances the accessibility or analysis of this data, consider contributing it back to the community through an open-source project, following open-source best practices.

Troubleshooting the first call

When retrieving data from the Covid-19 JHU CSSE GitHub repository, you might encounter issues. Here are common problems and their solutions:

1. File Not Found (HTTP 404 Error)

• Problem: The most common reason is an incorrect URL, especially the date format or filename. GitHub's "raw" content links are case-sensitive and demand precise paths.
• Solution:
  • Verify the URL: Double-check the exact path and filename in the JHU CSSE GitHub repository. Navigate to the specific file on GitHub and click the "Raw" button to get the exact raw content URL.
  • Date Format: Ensure the date format for daily reports is MM-DD-YYYY.csv (e.g., 05-28-2026.csv).
  • Recent Data & Delays: The data is typically updated daily. If you try to access a report for "today" very early in the day, it might not have been pushed to the repository yet. Wait a few hours and try again, or check the repository's commit history for the latest update.

2. Network Connectivity Issues

• Problem: Your internet connection is unstable, or there are temporary issues accessing GitHub.
• Solution:
  • Check Internet Connection: Confirm your device has an active internet connection.
  • GitHub Status: Check GitHub's status page for any reported outages or performance issues.
  • Firewall/Proxy: If you are in a corporate network, a firewall or proxy might be blocking direct access to GitHub. Consult your IT department or try accessing from a different network.

3. Data Decoding Errors

• Problem: The downloaded file is not correctly interpreted, leading to parsing errors in your script.
• Solution:
  • Encoding: Ensure you are using the correct character encoding (UTF-8 is standard for these CSVs). Most programming languages handle this automatically, but explicit declaration (e.g., encoding='utf-8' in Python's open() function) can resolve issues.
  • CSV Parser: Use robust CSV parsing libraries (e.g., Python's csv module, Pandas read_csv). Avoid splitting lines by comma manually, as CSVs can contain commas within quoted fields.

4. Unexpected Data Content

• Problem: The downloaded file is empty, truncated, or contains HTML (e.g., a 404 page) instead of CSV data.
• Solution:
  • Check Response Status: Always check the HTTP status code (e.g., response.status_code in Python requests). A 200 OK indicates success, while 404 Not Found or 500 Internal Server Error points to issues on the server side or with your request URL.
  • Inspect Content: Print the first few lines of the downloaded content to verify it's indeed CSV data and not an error page.

5. Repository Structure Changes

• Problem: The JHU CSSE team might occasionally reorganize the repository or change file naming conventions.
• Solution:
  • Monitor GitHub: Regularly check the repository's README and directory structure for announcements or changes. Subscribe to repository updates if available.
  • Adapt Your Code: Be prepared to adapt your data retrieval scripts if paths or filenames change.