Open Disease Getting Started: Quickstart Guide (2026)

Getting started overview

The Open Disease API, diseases.sh, offers public access to current and historical data related to various diseases, including COVID-19 statistics. Unlike many other APIs, Open Disease does not require an account, API keys, or any form of authentication to make requests. This design allows developers to integrate data directly into applications without an initial setup phase for credentials. The API provides endpoints for global, country-specific, and historical disease statistics, as well as disease-related news feeds.

This guide focuses on the immediate steps to make your first successful API call. The process involves identifying the desired endpoint from the Open Disease API documentation and constructing a standard HTTP GET request. The API delivers data in JSON format, which is a common data interchange format for web APIs, as defined by The JSON Data Interchange Standard. Understanding basic HTTP request methods and JSON parsing is beneficial for working with this API. For those new to API concepts, resources like the MDN Web Docs on using the Fetch API can provide foundational knowledge for making web requests.

Here's a quick reference for getting started:

Create an account and get keys

The Open Disease API does not require users to create an account or obtain API keys. All endpoints are publicly accessible without authentication. This simplifies the onboarding process significantly, allowing developers to begin making requests immediately after reviewing the available API documentation.

This approach contrasts with many commercial APIs, such as those from Stripe's API key management or PayPal's developer access tokens, which mandate registration and credential management for security and usage tracking. The Open Disease API's public nature means there are no rate limits enforced through individual keys, and no personal data is collected for API access. Developers can proceed directly to constructing their first API request without any preliminary setup steps related to user accounts or authentication tokens.

Your first request

To make your first request to the Open Disease API, you will use a standard HTTP GET method to one of its publicly available endpoints. This example demonstrates how to retrieve global COVID-19 statistics. You can use a command-line tool like cURL, a web browser, or a programming language to perform this action.

Example: Global COVID-19 Statistics

The endpoint for global COVID-19 statistics is https://disease.sh/v3/covid-19/all. This endpoint provides an overview of cases, deaths, and recoveries worldwide.

Using cURL (Command Line)

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

curl https://disease.sh/v3/covid-19/all

Upon execution, the terminal will display a JSON object containing global COVID-19 data. The output will resemble the following (values are illustrative and change frequently):

{
  "cases": 700000000,
  "deaths": 7000000,
  "recovered": 650000000,
  "active": 43000000,
  "population": 8000000000,
  "tests": 10000000000,
  "todayCases": 100000,
  "todayDeaths": 1000,
  "todayRecovered": 50000,
  "critical": 20000,
  "casesPerOneMillion": 87500,
  "deathsPerOneMillion": 875,
  "testsPerOneMillion": 1250000,
  "oneCasePerPeople": 11,
  "oneDeathPerPeople": 1142,
  "oneTestPerPeople": 1,
  "activePerOneMillion": 5375,
  "recoveredPerOneMillion": 81250,
  "criticalPerOneMillion": 2.5,
  "affectedCountries": 220
}

Using a Web Browser

You can also paste the URL directly into your web browser's address bar:

https://disease.sh/v3/covid-19/all

The browser will display the raw JSON response. Many browsers offer built-in JSON viewers or extensions to format the output for better readability.

Using JavaScript (Fetch API)

For client-side web applications, the Fetch API is a modern way to make HTTP requests. Here's how you can make the request and log the data to the console:

fetch('https://disease.sh/v3/covid-19/all')
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error fetching data:', error));

This JavaScript code snippet sends a GET request to the specified endpoint, parses the JSON response, and then prints the resulting data object to the browser's developer console.

Using Python (requests library)

For server-side applications or scripting, Python's requests library is commonly used for making HTTP requests:

import requests
import json

url = "https://disease.sh/v3/covid-19/all"
response = requests.get(url)

if response.status_code == 200:
    data = response.json()
    print(json.dumps(data, indent=2))
else:
    print(f"Error: {response.status_code}")

This Python script fetches the data and prints it in a formatted JSON structure. Ensure you have the requests library installed (pip install requests).

Common next steps

After successfully making your first request to the Open Disease API, consider these common next steps to further integrate and utilize the data:

1. Explore More Endpoints: The Open Disease API offers a variety of endpoints beyond global statistics. These include country-specific data, historical data for COVID-19, and general disease news. Refer to the Open Disease API documentation to discover endpoints like /v3/covid-19/countries/{country} for specific country data or /v3/covid-19/historical/all for historical trends.
2. Integrate into an Application: Begin incorporating the data into your web, mobile, or desktop application. Depending on your application's requirements, you might display statistics on a dashboard, use historical data for trend analysis, or power a news feed with disease-related articles.
3. Data Visualization: Utilize charting libraries or data visualization tools to present the retrieved data graphically. Visualizing trends, comparisons between countries, or the spread of diseases can make the data more accessible and understandable for end-users. Tools like D3.js for web-based visualizations or Matplotlib for Python applications are popular choices.
4. Error Handling: Implement robust error handling in your application. While the Open Disease API is generally reliable, network issues, malformed requests, or temporary service interruptions can occur. Your application should gracefully handle HTTP status codes other than 200 (OK) and provide informative feedback to the user or log errors for debugging.
5. Consider Rate Limits: Although the Open Disease API does not enforce authentication-based rate limits, it is good practice to design your application to make requests responsibly. Avoid hammering the API with excessive requests in a short period. For applications needing frequent updates, consider implementing caching mechanisms to store data locally for a period, reducing the load on the API and improving your application's performance.
6. Stay Updated: Periodically check the Open Disease homepage or documentation for updates to the API, new features, or changes in data structure. APIs can evolve, and staying informed ensures your integration remains compatible and leverages the latest capabilities.

Troubleshooting the first call

If your first API call to Open Disease does not return the expected data, consider the following troubleshooting steps:

• Check the URL: Verify that the endpoint URL is spelled correctly and matches the paths specified in the Open Disease API documentation. A common error is a typo in the domain (disease.sh) or the path (e.g., /v3/covid-19/all).
• Network Connectivity: Ensure your device has an active internet connection. If you are behind a corporate firewall or proxy, it might be blocking outgoing HTTP requests to external domains. Test with a simple request to a known working URL, like curl google.com, to confirm network access.
• HTTP Method: Confirm you are using the HTTP GET method. The Open Disease API primarily uses GET for data retrieval. Using other methods like POST or PUT will result in an error.
• Response Status Code: Examine the HTTP status code returned with the response. A 200 OK indicates success. Other common codes include:
  • 404 Not Found: Often means the endpoint URL is incorrect or the requested resource (e.g., a specific country that doesn't exist in the dataset) could not be found.
  • 5xx Server Error: Indicates an issue on the API server's side. If this occurs, it's usually temporary, and retrying after a short delay might resolve it.
  • 400 Bad Request: Suggests that the request syntax is invalid or parameters are malformed. Although less common for simple GET requests without parameters, it's worth checking if you've added any query parameters incorrectly.
  You can inspect the status code in cURL using the -v flag (curl -v https://disease.sh/v3/covid-19/all) or in your programming language's HTTP client library.
• JSON Parsing Errors: If you receive a response but your application fails to process it, the issue might be with JSON parsing. Ensure your code correctly handles the JSON format. Sometimes, an API might return an error message as plain text or HTML instead of JSON, which can cause parsing failures. Check the Content-Type header of the response; it should typically be application/json.
• Browser Extensions: If testing in a browser, temporarily disable any browser extensions that might interfere with how JSON data is displayed or processed, such as ad blockers or JSON formatters, to see the raw response.
• Consult Documentation: Re-read the specific endpoint's section in the Open Disease documentation. There might be specific requirements or nuances for that particular endpoint that you missed.