coronavirus-tracker-api

🦠 A simple and fast (< 200ms) API for tracking the global coronavirus (COVID-19, SARS-CoV-2) outbreak. It's written in python using the 🔥 FastAPI framework. Supports multiple sources!

1,592

323

1,592

View on GitHub

Top Related Projects

covid19

1,227

JSON time-series of coronavirus cases (confirmed, deaths and recovered) per country - updated daily

COVID-19

29,136

Novel Coronavirus (COVID-19) Cases, provided by JHU CSSE

API

2,459

API for Current cases and more stuff about COVID-19 and Influenza

covid-19-api

1,356

COVID-19 global data (from JHU CSSE for now) as-a-service

CoronaTracker

1,541

Coronavirus tracker app for iOS & macOS with maps & charts

Quick Overview

The coronavirus-tracker-api is an open-source API for tracking the global coronavirus (COVID-19) outbreak. It provides up-to-date data on cases, deaths, and recoveries for countries and regions worldwide, sourced from reputable organizations like Johns Hopkins CSSE.

Pros

Easy-to-use RESTful API for accessing COVID-19 data
Supports multiple data sources (JHU, CSE, etc.)
Provides both current and historical data
Well-documented and actively maintained

Cons

Dependent on external data sources for accuracy
May experience rate limiting or downtime during high traffic periods
Limited to COVID-19 data only, not suitable for other disease tracking
Requires some technical knowledge to implement and use effectively

Code Examples

Fetching latest global COVID-19 data:

import requests

url = "https://coronavirus-tracker-api.herokuapp.com/v2/latest"
response = requests.get(url)
data = response.json()

print(f"Global confirmed cases: {data['latest']['confirmed']}")
print(f"Global deaths: {data['latest']['deaths']}")
print(f"Global recoveries: {data['latest']['recovered']}")

Getting COVID-19 data for a specific country:

import requests

country = "US"
url = f"https://coronavirus-tracker-api.herokuapp.com/v2/locations?country={country}"
response = requests.get(url)
data = response.json()

for location in data['locations']:
    print(f"State: {location['province']}")
    print(f"Confirmed cases: {location['latest']['confirmed']}")
    print(f"Deaths: {location['latest']['deaths']}")
    print("---")

Retrieving historical data for a specific location:

import requests

location_id = 225  # New York, US
url = f"https://coronavirus-tracker-api.herokuapp.com/v2/locations/{location_id}?timelines=true"
response = requests.get(url)
data = response.json()

timeline = data['location']['timelines']['confirmed']['timeline']
for date, cases in timeline.items():
    print(f"Date: {date}, Confirmed cases: {cases}")

Getting Started

To start using the coronavirus-tracker-api:

Install the requests library:
```
pip install requests
```

Make API calls using the base URL:

import requests

base_url = "https://coronavirus-tracker-api.herokuapp.com/v2"

# Get latest global data
response = requests.get(f"{base_url}/latest")
global_data = response.json()

# Get data for a specific country
country = "Italy"
response = requests.get(f"{base_url}/locations?country={country}")
country_data = response.json()

# Process and use the data as needed

Refer to the API documentation for more endpoints and options: https://github.com/ExpDev07/coronavirus-tracker-api#api-endpoints

Competitor Comparisons

covid19

1,227

JSON time-series of coronavirus cases (confirmed, deaths and recovered) per country - updated daily

Pros of covid19

Simpler data structure with a focus on time series data
Provides data in JSON format, making it easy to integrate with JavaScript applications
Regular updates from Johns Hopkins CSSE data source

Cons of covid19

Limited to global COVID-19 data, lacking additional features or data sources
Does not offer real-time API access, relies on periodic data updates

Code comparison

covid19:

fetch("https://pomber.github.io/covid19/timeseries.json")
  .then(response => response.json())
  .then(data => {
    data["Argentina"].forEach(({ date, confirmed, recovered, deaths }) =>
      console.log(`${date} active cases: ${confirmed - recovered - deaths}`)
    )
  })

coronavirus-tracker-api:

from flask import Flask, jsonify
from .utils.populations import country_population

@app.route('/v2/locations/<int:id>')
def location(id):
    # ... (location data retrieval logic)
    return jsonify({
        'location': location,
        'country_population': country_population(location)
    })

Summary

While covid19 offers a straightforward approach to accessing COVID-19 time series data, coronavirus-tracker-api provides a more comprehensive API with additional features and data sources. The choice between the two depends on specific project requirements and desired level of data granularity.

COVID-19

29,136

Novel Coronavirus (COVID-19) Cases, provided by JHU CSSE

Pros of COVID-19

Comprehensive and widely-used dataset for COVID-19 statistics
Regularly updated with global data from authoritative sources
Provides raw data in easily accessible CSV format

Cons of COVID-19

Requires data processing and analysis to extract meaningful insights
No built-in API for easy integration into applications
Limited visualization options without additional tools

Code Comparison

coronavirus-tracker-api:

@app.route("/v2/locations")
def locations():
    # ... (code to fetch and return location data)
    return jsonify({"locations": locations})

COVID-19:

Province/State,Country/Region,Last Update,Confirmed,Deaths,Recovered
Hubei,Mainland China,2020-02-15T23:13:05,56249,1596,5623
Guangdong,Mainland China,2020-02-15T12:23:05,1294,2,409

The coronavirus-tracker-api provides a ready-to-use API endpoint for retrieving location data, while COVID-19 offers raw CSV data that requires further processing to be used in applications.

coronavirus-tracker-api is more suitable for developers looking for a quick integration solution, while COVID-19 is better for data analysts and researchers who need access to raw data for custom analysis and visualization.

API

2,459

API for Current cases and more stuff about COVID-19 and Influenza

Pros of disease-sh/API

More comprehensive data sources, including worldometers, Johns Hopkins CSSE, and official government reports
Offers additional health-related data beyond COVID-19, such as HIV/AIDS and influenza statistics
Provides more detailed historical data and country-specific information

Cons of disease-sh/API

Potentially higher latency due to aggregating data from multiple sources
More complex API structure, which may require additional learning for developers
Larger codebase, potentially making it harder to contribute or customize

Code Comparison

coronavirus-tracker-api:

@app.route("/v2/locations")
def locations():
    # Simple route for fetching all location data
    return jsonify({"locations": [location.serialize() for location in data_source.get_all()]})

disease-sh/API:

router.get('/v3/covid-19/countries', async (req, res) => {
    const { sort, yesterday, twoDaysAgo, allowNull } = req.query;
    const countries = await getCountries(keys, redis);
    res.send(countries);
});

The disease-sh/API code snippet shows a more complex route handling with query parameters and asynchronous data fetching, reflecting its broader feature set and data sources.

covid-19-api

1,356

COVID-19 global data (from JHU CSSE for now) as-a-service

Pros of covid-19-api

More frequent updates and active maintenance
Supports multiple languages through i18n
Provides historical data and time series information

Cons of covid-19-api

Less comprehensive documentation
Fewer data sources (primarily relies on JHU CSSE)
Limited customization options for data retrieval

Code Comparison

covid-19-api:

const getData = async () => {
  const { data } = await axios.get(
    'https://covid19.mathdro.id/api'
  );
  return data;
};

coronavirus-tracker-api:

@app.route("/v2/locations")
def locations():
    return jsonify(
        locations=[location.serialize() for location in get_all_locations()]
    )

The covid-19-api uses JavaScript with Axios for data fetching, while coronavirus-tracker-api uses Python with Flask for API routing. The coronavirus-tracker-api appears to have a more structured approach to handling location data.

Both APIs provide similar functionality for tracking COVID-19 data, but they differ in implementation languages, update frequency, and data sources. The choice between them would depend on specific project requirements, preferred programming language, and desired data granularity.

CoronaTracker

1,541

Coronavirus tracker app for iOS & macOS with maps & charts

Pros of CoronaTracker

Built as a native iOS app, providing a better user experience for Apple device users
Offers a more comprehensive set of features, including maps, charts, and detailed country information
Includes a news section to keep users informed about the latest COVID-19 developments

Cons of CoronaTracker

Limited to iOS platform, reducing accessibility for non-Apple users
Requires more frequent updates to maintain compatibility with iOS versions and device types
May consume more device resources compared to a lightweight API solution

Code Comparison

CoronaTracker (Swift):

func fetchData() {
    let url = URL(string: "https://corona.lmao.ninja/v2/countries")!
    URLSession.shared.dataTask(with: url) { (data, response, error) in
        // Process and update UI with fetched data
    }.resume()
}

coronavirus-tracker-api (Python):

@app.route('/v2/locations')
def locations():
    data = DataSource()
    return jsonify({
        'locations': [location.serialize() for location in data.locations]
    })

The code snippets demonstrate the different approaches: CoronaTracker focuses on fetching and displaying data in a mobile app, while coronavirus-tracker-api is designed as a RESTful API service.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Coronavirus Tracker API

Provides up-to-date data about Coronavirus outbreak. Includes numbers about confirmed cases, deaths and recovered. Support multiple data-sources.

Live global stats (provided by fight-covid19/bagdes) from this API:

Covid-19 Confirmed Covid-19 Recovered Covid-19 Deaths

New York Times is now available as a source!

Specify source parameter with ?source=nyt. NYT also provides a timeseries! To view timelines of cases by US counties use ?source=nyt&timelines=true

Recovered cases showing 0

JHU (our main data provider) no longer provides data for amount of recoveries, and as a result, the API will be showing 0 for this statistic. Apologies for any inconvenience. Hopefully we'll be able to find an alternative data-source that offers this.

Available data-sources:

Currently 3 different data-sources are available to retrieve the data:

jhu - https://github.com/CSSEGISandData/COVID-19 - Worldwide Data repository operated by the Johns Hopkins University Center for Systems Science and Engineering (JHU CSSE).
csbs - https://www.csbs.org/information-covid-19-coronavirus - U.S. County data that comes from the Conference of State Bank Supervisors.
nyt - https://github.com/nytimes/covid-19-data - The New York Times is releasing a series of data files with cumulative counts of coronavirus cases in the United States. This API provides the timeseries at the US county level.

jhu data-source will be used as a default source if you don't specify a source parameter in your request.

API Reference

All endpoints are located at coronavirus-tracker-api.herokuapp.com/v2/ and are accessible via https. For instance: you can get data per location by using this URL: https://coronavirus-tracker-api.herokuapp.com/v2/locations

You can open the URL in your browser to further inspect the response. Or you can make this curl call in your terminal to see the prettified response:

curl https://coronavirus-tracker-api.herokuapp.com/v2/locations | json_pp

Swagger/OpenAPI

Consume our API through our super awesome and interactive SwaggerUI (on mobile, use the mobile friendly ReDocs instead for the best experience).

The OpenAPI json definition can be downloaded at https://coronavirus-tracker-api.herokuapp.com/openapi.json

API Endpoints

Sources Endpoint

Getting the data-sources that are currently available to Coronavirus Tracker API to retrieve the data of the pandemic.

GET /v2/sources

Sample response

{
    "sources": [
        "jhu",
        "csbs",
        "nyt"
    ]
}

Latest Endpoint

Getting latest amount of total confirmed cases, deaths, and recovered.

GET /v2/latest

Query String Parameters

Query string parameter	Description	Type
source	The data-source where data will be retrieved from (jhu/csbs/nyt). Default is jhu	String

Sample response

{
  "latest": {
    "confirmed": 197146,
    "deaths": 7905,
    "recovered": 80840
  }
}

Locations Endpoint

Getting latest amount of confirmed cases, deaths, and recovered per location.

The Location Object

GET /v2/locations/:id

Path Parameters

Path parameter	Required/Optional	Description	Type
id	OPTIONAL	The unique location id for which you want to call the Locations Endpoint. The list of valid location IDs (:id) can be found in the locations response: `/v2/locations`	Integer

Query String Parameters

Query string parameter	Description	Type
source	The data-source where data will be retrieved from (jhu/csbs/nyt). Default is jhu	String

Example Request

GET /v2/locations/39

Sample response

{
  "location": {
    "id": 39,
    "country": "Norway",
    "country_code": "NO",
    "country_population": 5009150,
    "province": "",
    "county": "",
    "last_updated": "2020-03-21T06:59:11.315422Z",
    "coordinates": { },
    "latest": { },
    "timelines": {
      "confirmed": {
        "latest": 1463,
        "timeline": {
          "2020-03-16T00:00:00Z": 1333,
          "2020-03-17T00:00:00Z": 1463
        }
      },
      "deaths": { },
      "recovered": { }
    }
  }
}

List of all locations

GET /v2/locations

Query String Parameters

Query string parameter	Description	Type
source	The data-source where data will be retrieved from. Value can be: jhu/csbs/nyt. Default is jhu	String
country_code	The ISO (alpha-2 country_code) to the Country/Province for which you're calling the Endpoint	String
timelines	To set the visibility of timelines (daily tracking). Value can be: 0/1. Default is 0 (timelines are not visible)	Integer

Sample response

{
  "latest": {
    "confirmed": 272166,
    "deaths": 11299,
    "recovered": 87256
  },
  "locations": [
    {
      "id": 0,
      "country": "Thailand",
      "country_code": "TH",
      "country_population": 67089500,
      "province": "",
      "county": "",
      "last_updated": "2020-03-21T06:59:11.315422Z",
      "coordinates": {
        "latitude": "15",
        "longitude": "101"
      },
      "latest": {
        "confirmed": 177,
        "deaths": 1,
        "recovered": 41
      }
    },
    {
      "id": 39,
      "country": "Norway",
      "country_code": "NO",
      "province": "",
      "county": "",
      "last_updated": "2020-03-21T06:59:11.315422Z",
      "coordinates": {
        "latitude": "60.472",
        "longitude": "8.4689"
      },
      "latest": {
        "confirmed": 1463,
        "deaths": 3,
        "recovered": 1
      }
    }
  ]
}

Response definitions

Response Item	Description	Type
{latest}	The total amount of confirmed cases, deaths and recovered for all the locations	Object
{latest}/confirmed	The up-to-date total number of confirmed cases for all the locations within the data-source	Integer
{latest}/deaths	The up-to-date total amount of deaths for all the locations within the data-source	Integer
{latest}/recovered	The up-to-date total amount of recovered for all the locations within the data-source	Integer
{locations}	The collection of locations contained within the data-source	Object
{location}	Information that identifies a location	Object
{latest}	The amount of confirmed cases, deaths and recovered related to the specific location	Object
{locations}/{location}/{latest}/confirmed	The up-to-date number of confirmed cases related to the specific location	Integer
{locations}/{location}/{latest}/deaths	The up-to-date number of deaths related to the specific location	Integer
{locations}/{location}/{latest}/recovered	The up-to-date number of recovered related to the specific location	Integer
{locations}/{location}/id	The location id. This unique id is assigned to the location by the data-source.	Integer
{locations}/{location}/country	The Country name	String
{locations}/{location}/country_code	The ISO alpha-2 country_code Country code for the location.	String
{locations}/{location}/province	The province where the location belongs to. (Used for US locations coming from csbs data-source. Empty when jhu data-source is used	String
{locations}/{location}/{coordinates}/latitude	The location latitude	Float
{locations}/{location}/{coordinates}/longitude	The location longitude	Float

Example Requests with parameters

Parameter: country_code

Getting data for the Country specified by the country_code parameter, in this case Italy - IT

GET /v2/locations?country_code=IT

Sample Response

{
  "latest": {
    "confirmed": 59138,
    "deaths": 5476,
    "recovered": 7024
  },
  "locations": [
    {
      "id": 16,
      "country": "Italy",
      "country_code": "IT",
      "country_population": 60340328,
      "province": "",
      "county": "",
      "last_updated": "2020-03-23T13:32:23.913872Z",
      "coordinates": {
          "latitude": "43",
          "longitude": "12"
      },
      "latest": {
          "confirmed": 59138,
          "deaths": 5476,
          "recovered": 7024
      }
    }
  ]
}

Parameter: source

Getting the data from the data-source specified by the source parameter, in this case csbs

GET /v2/locations?source=csbs

Sample Response

{
  "latest": {
    "confirmed": 7596,
    "deaths": 43,
    "recovered": 0
  },
  "locations": [
    {
      "id": 0,
      "country": "US",
      "country_code": "US",
      "country_population": 310232863,
      "province": "New York",
      "state": "New York",
      "county": "New York",
      "last_updated": "2020-03-21T14:00:00Z",
      "coordinates": {
        "latitude": 40.71455,
        "longitude": -74.00714
      },
      "latest": {
        "confirmed": 6211,
        "deaths": 43,
        "recovered": 0
      }
    },
    {
      "id": 1,
      "country": "US",
      "country_code": "US",
      "country_population": 310232863,
      "province": "New York",
      "state": "New York",
      "county": "Westchester",
      "last_updated": "2020-03-21T14:00:00Z",
      "coordinates": {
        "latitude": 41.16319759,
        "longitude": -73.7560629
      },
      "latest": {
        "confirmed": 1385,
        "deaths": 0,
        "recovered": 0
      },
    }
  ]
}

Parameter: timelines

Getting the data for all the locations including the daily tracking of confirmed cases, deaths and recovered per location.

GET /v2/locations?timelines=1

Explore the response by opening the URL in your browser https://coronavirus-tracker-api.herokuapp.com/v2/locations?timelines=1 or make the following curl call in your terminal:

curl https://coronavirus-tracker-api.herokuapp.com/v2/locations?timelines=1 | json_pp

NOTE: Timelines tracking starts from day 22nd January 2020 and ends to the last available day in the data-source.

Wrappers

These are the available API wrappers created by the community. They are not necessarily maintained by any of this project's authors or contributors.

PHP

CovidPHP by @o-ba.

Golang

Go-corona by @itsksaurabh.

C#

Prerequisites

You will need the following things properly installed on your computer.

Python 3 (with pip)
pipenv

Installation

git clone https://github.com/ExpDev07/coronavirus-tracker-api.git
cd coronavirus-tracker-api

Make sure you have python3.8 installed and on your PATH.
Install the pipenv dependency manager
- with pipx $ pipx install pipenv
- with Homebrew/Linuxbrew $ brew install pipenv
- with pip/pip3 directly $ pip install --user pipenv
Create virtual environment and install all dependencies $ pipenv sync --dev
Activate/enter the virtual environment $ pipenv shell

And don't despair if don't get the python setup working on the first try. No one did. Guido got pretty close... once. But that's another story. Good luck.

Running / Development

For a live reloading on code changes.

pipenv run dev

Without live reloading.

pipenv run start

Visit your app at http://localhost:8000.

Alternatively run our API with Docker.

Running Tests

pytest

pipenv run test

Linting

pylint

pipenv run lint

Formatting

black

pipenv run fmt

Update requirements files

invoke generate-reqs

Pipfile.lock will be automatically updated during pipenv install.

Docker

Our Docker image is based on tiangolo/uvicorn-gunicorn-fastapi/.

invoke docker --build

Run with docker run or docker-compose

Alternate Docker images

If a full gunicorn deployment is unnecessary or impractical on your hardware consider using our single instance Uvicorn based Dockerfile.

Invoke

Additional developer commands can be run by calling them with the python invoke task runner.

invoke --list

Deploying

Contributors â¨

Thanks goes to these wonderful people (emoji key):

_ExpDev ð» ð ð§	_bjarkimg ð¬	_Bost ð	_GRIBOK ð» â ï¸	_{Oliver Thamm} ð	_{Mauro M.} ð	_JKSenthil ð» ð â ï¸
_SeanCena ð» ð â ï¸	_{Abdirahiim Yassin} ð ð§ ð¦	_{DarÃo HereÃ±Ãº} ð	_Oliver ð	_carmelag ð	_Gabriel ð» ð â ï¸ ð	_{Kodjo Laurent Egbakou} ð ð§ ð¦
_Turreted ð»	_{Ibtida Bhuiyan} ð» ð	_{James Gray} ð»	_{Nischal Shankar} ð» ð