Covid-19 Datenhub Getting Started: Accessing Swiss COVID-19 Data

Getting started overview

The Covid-19 Datenhub offers a public API that provides access to various datasets related to COVID-19 in Switzerland. This includes detailed information on cases, hospitalizations, vaccinations, and mobility trends. The API is designed for developers, researchers, and data analysts who require programmatic access to facilitate public health research, data visualization, epidemiological analysis, and informed policy making.

Unlike many commercial APIs, the Covid-19 Datenhub API does not require an API key or any form of authentication for standard data access. This design choice simplifies the onboarding process significantly, allowing users to begin querying data immediately upon understanding the available endpoints and data structures. Data is served in JSON format, a widely supported and easily parsable standard for web APIs (JSON API specification).

To get started, users primarily need to familiarize themselves with the API documentation to identify the relevant endpoints for their specific data needs. The API structure is organized logically, with distinct endpoints for different data categories, making it straightforward to navigate and retrieve precise information (Covid-19 Datenhub API documentation).

Quick-reference guide

The following table summarizes the essential steps to begin using the Covid-19 Datenhub API:

Create an account and get keys

The Covid-19 Datenhub API operates on an open access model, meaning there is no requirement to create an account or obtain API keys to access its public datasets. This distinguishes it from many commercial API services that typically gate access through authentication mechanisms like OAuth 2.0 or API key headers (OAuth 2.0 specification).

For the Covid-19 Datenhub, direct access to the API endpoints specified in the official documentation is sufficient. This simplifies the initial setup significantly, as developers do not need to manage credentials, handle authentication tokens, or implement authorization flows. The focus shifts entirely to understanding the data structure and constructing correct API requests.

While an account is not needed for API access, users may wish to visit the official Covid-19 Datenhub homepage for general information or to explore other resources related to the project. However, for the sole purpose of querying data via the API, no preliminary registration or key generation is necessary.

Your first request

To make your first request to the Covid-19 Datenhub API, you will need to identify an endpoint and construct a simple HTTP GET request. For this example, we will retrieve the latest case data for Switzerland. The API's base URL is https://www.covid19-data.ch/api/v2/.

Example: Fetching daily case data

One common endpoint for retrieving daily case numbers is for the entire country. According to the Covid-19 Datenhub API reference, a relevant endpoint could be /daily/cases/ch for Switzerland-wide daily case data.

Step 1: Construct the URL

The full URL for fetching daily cases for Switzerland would be:

https://www.covid19-data.ch/api/v2/daily/cases/ch

Step 2: Execute the request

You can execute this request using various tools. Here are examples for a command-line tool (curl), a web browser, and a Python script.

Using curl (command line)

Open your terminal or command prompt and enter the following command:

curl https://www.covid19-data.ch/api/v2/daily/cases/ch

This command will print the JSON response directly to your console.

Using a web browser

Simply paste the URL https://www.covid19-data.ch/api/v2/daily/cases/ch into your browser's address bar and press Enter. Most modern browsers will display the JSON response, often formatted for readability.

Using Python

For programmatic access, you can use a language like Python with its requests library:

import requests
import json

url = "https://www.covid19-data.ch/api/v2/daily/cases/ch"

try:
    response = requests.get(url)
    response.raise_for_status()  # Raises an HTTPError for bad responses (4xx or 5xx)
    data = response.json()
    print(json.dumps(data, indent=2)) # Pretty print the JSON data
except requests.exceptions.RequestException as e:
    print(f"An error occurred: {e}")

This Python script will fetch the data and print it in a human-readable JSON format to your console. The requests.get() method initiates an HTTP GET request, and response.json() parses the JSON content from the response body (Python Requests library documentation).

Step 3: Interpret the response

The API will return a JSON array of objects, where each object represents daily COVID-19 case data. The structure will typically include fields such as date, cases, and other relevant metrics. For example:

[
  {
    "date": "2023-01-01",
    "cases": 1234,
    "new_cases": 50,
    "tests": 10000
  },
  {
    "date": "2023-01-02",
    "cases": 1280,
    "new_cases": 46,
    "tests": 9800
  }
]

The exact fields may vary by endpoint, so consulting the API documentation for each specific endpoint is crucial for precise data interpretation.

Common next steps

Once you have successfully made your first API call and understand the basic request/response cycle, consider these common next steps to further integrate with the Covid-19 Datenhub API:

1. Explore more endpoints: The Covid-19 Datenhub offers a variety of datasets beyond daily cases. Investigate endpoints for hospitalizations, vaccinations, mobility data, and cantonal (regional) breakdowns. The full API documentation is the best resource for discovering these.
2. Implement filtering and parameters: Many API endpoints support query parameters to filter data by date range, region, or other criteria. Learning how to use these parameters will allow you to retrieve more specific and relevant datasets, reducing the amount of data you need to process client-side.
3. Data storage and processing: For applications that require historical analysis or offline access, you might want to store the retrieved data in a local database (e.g., PostgreSQL, MongoDB) or data warehouse. This enables faster querying and more complex analytical operations without repeatedly hitting the API.
4. Build visualizations: Leverage data visualization libraries (e.g., D3.js, Matplotlib, Tableau) to create interactive charts, graphs, and maps from the fetched data. This is particularly useful for public health dashboards or research presentations.
5. Automate data retrieval: For applications requiring up-to-date information, schedule automated scripts to periodically fetch new data from the API. Implement robust error handling and retry mechanisms to ensure data continuity (Google Cloud's retry strategy guidance).
6. Contribute to the community: While not directly API-related, engaging with the public health data community can provide insights into best practices for data analysis and visualization.

Troubleshooting the first call

Encountering issues during your first API call is common. Here's a guide to troubleshooting typical problems when accessing the Covid-19 Datenhub API:

1. URL syntax errors:

   • Problem: Incorrect endpoint path, typos in the base URL, or missing slashes.
   • Solution: Double-check the URL against the official API documentation. Ensure correct casing and placement of all characters.
   • Example: Instead of /daily/cases/ch, you might have typed /daily/case/ch.

2. Network connectivity issues:

   • Problem: Your machine cannot reach the API server. This might manifest as a timeout or a connection refused error.
   • Solution: Verify your internet connection. Try pinging www.covid19-data.ch from your terminal. Check if any firewalls or proxy settings are blocking outgoing requests from your environment.

3. HTTP status codes:

   • Problem: The API returns an HTTP status code other than 200 OK. Common codes include 404 Not Found, 500 Internal Server Error, or 400 Bad Request.
   • Solution:
     • 404 Not Found: Indicates an incorrect endpoint or resource path. Re-verify the URL against the documentation.
     • 500 Internal Server Error: Suggests an issue on the API server's side. This is typically outside your control; monitor the API's status or try again later.
     • 400 Bad Request: Although less common for this API due to the lack of complex parameters, it could indicate malformed query parameters if you were attempting to use them.
   • Debugging: Many tools (like curl with -v or browser developer tools' network tab) can show the full HTTP response, including status codes and headers, which often contain clues.

4. JSON parsing errors:

   • Problem: Your code fails to parse the JSON response. This can happen if the response is not valid JSON or if it's empty.
   • Solution:
     • Inspect the raw API response (e.g., using print(response.text) in Python).
     • Use an online JSON validator to check the structure if you suspect malformed JSON.
     • Ensure your parsing library (e.g., Python's json module, JavaScript's JSON.parse()) is correctly handling the data.

5. Empty or unexpected data:

   • Problem: The API returns an empty array or data that doesn't match your expectations.
   • Solution:
     • Confirm you are querying the correct endpoint for the data you expect.
     • Check if there are any date or geographical filters implicitly applied or that you might be missing.
     • Verify the data availability period. Some historical data might not be present for certain endpoints or regions.

By systematically checking these common areas, you can usually resolve issues encountered during your initial interactions with the Covid-19 Datenhub API.