Home

Awesome

<h1 align="center"> Coronavirus Tracker API </h1>

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

Travis build Coverage Status License All Contributors GitHub stars GitHub forks GitHub last commit GitHub pull requests GitHub issues Total alerts Code style: black Tweet

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 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 parameterDescriptionType
sourceThe data-source where data will be retrieved from (jhu/csbs/nyt). Default is jhuString

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 parameterRequired/OptionalDescriptionType
idOPTIONALThe 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/locationsInteger

Query String Parameters

Query string parameterDescriptionType
sourceThe data-source where data will be retrieved from (jhu/csbs/nyt). Default is jhuString

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 parameterDescriptionType
sourceThe data-source where data will be retrieved from.<br>Value can be: jhu/csbs/nyt. Default is jhuString
country_codeThe ISO (alpha-2 country_code) to the Country/Province for which you're calling the EndpointString
timelinesTo set the visibility of timelines (daily tracking).<br>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 ItemDescriptionType
{latest}The total amount of confirmed cases, deaths and recovered for all the locationsObject
{latest}/confirmedThe up-to-date total number of confirmed cases for all the locations within the data-sourceInteger
{latest}/deathsThe up-to-date total amount of deaths for all the locations within the data-sourceInteger
{latest}/recoveredThe up-to-date total amount of recovered for all the locations within the data-sourceInteger
{locations}The collection of locations contained within the data-sourceObject
{location}Information that identifies a locationObject
{latest}The amount of confirmed cases, deaths and recovered related to the specific locationObject
{locations}/{location}/{latest}/confirmedThe up-to-date number of confirmed cases related to the specific locationInteger
{locations}/{location}/{latest}/deathsThe up-to-date number of deaths related to the specific locationInteger
{locations}/{location}/{latest}/recoveredThe up-to-date number of recovered related to the specific locationInteger
{locations}/{location}/idThe location id. This unique id is assigned to the location by the data-source.Integer
{locations}/{location}/countryThe Country nameString
{locations}/{location}/country_codeThe ISO alpha-2 country_code Country code for the location.String
{locations}/{location}/provinceThe province where the location belongs to. (Used for US locations coming from csbs data-source.<br>Empty when jhu data-source is usedString
{locations}/{location}/{coordinates}/latitudeThe location latitudeFloat
{locations}/{location}/{coordinates}/longitudeThe location longitudeFloat

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

Golang

C#

Python

Java

Node.js

Ruby

Lua

Prerequisites

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

Installation

  1. Make sure you have python3.8 installed and on your PATH.
  2. Install the pipenv dependency manager
  3. Create virtual environment and install all dependencies $ pipenv sync --dev
  4. 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.

Without live reloading.

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):

<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --> <!-- prettier-ignore-start --> <!-- markdownlint-disable --> <table> <tr> <td align="center"><a href="https://github.com/ExpDev07"><img src="https://avatars3.githubusercontent.com/u/10024730?v=4" width="100px;" alt=""/><br /><sub><b>ExpDev</b></sub></a><br /><a href="https://github.com/ExpDev07/coronavirus-tracker-api/commits?author=ExpDev07" title="Code">πŸ’»</a> <a href="https://github.com/ExpDev07/coronavirus-tracker-api/commits?author=ExpDev07" title="Documentation">πŸ“–</a> <a href="#maintenance-ExpDev07" title="Maintenance">🚧</a></td> <td align="center"><a href="https://github.com/bjarkimg"><img src="https://avatars2.githubusercontent.com/u/1289419?v=4" width="100px;" alt=""/><br /><sub><b>bjarkimg</b></sub></a><br /><a href="#question-bjarkimg" title="Answering Questions">πŸ’¬</a></td> <td align="center"><a href="https://github.com/Bost"><img src="https://avatars0.githubusercontent.com/u/1174677?v=4" width="100px;" alt=""/><br /><sub><b>Bost</b></sub></a><br /><a href="https://github.com/ExpDev07/coronavirus-tracker-api/commits?author=Bost" title="Documentation">πŸ“–</a></td> <td align="center"><a href="https://github.com/gribok"><img src="https://avatars1.githubusercontent.com/u/40306040?v=4" width="100px;" alt=""/><br /><sub><b>GRIBOK</b></sub></a><br /><a href="https://github.com/ExpDev07/coronavirus-tracker-api/commits?author=gribok" title="Code">πŸ’»</a> <a href="https://github.com/ExpDev07/coronavirus-tracker-api/commits?author=gribok" title="Tests">⚠️</a></td> <td align="center"><a href="https://github.com/oliver-xapix-io"><img src="https://avatars0.githubusercontent.com/u/13470858?v=4" width="100px;" alt=""/><br /><sub><b>Oliver Thamm</b></sub></a><br /><a href="https://github.com/ExpDev07/coronavirus-tracker-api/commits?author=oliver-xapix-io" title="Documentation">πŸ“–</a></td> <td align="center"><a href="https://maurom.dev"><img src="https://avatars1.githubusercontent.com/u/22800592?v=4" width="100px;" alt=""/><br /><sub><b>Mauro M.</b></sub></a><br /><a href="https://github.com/ExpDev07/coronavirus-tracker-api/commits?author=MM-coder" title="Documentation">πŸ“–</a></td> <td align="center"><a href="https://github.com/JKSenthil"><img src="https://avatars2.githubusercontent.com/u/12533226?v=4" width="100px;" alt=""/><br /><sub><b>JKSenthil</b></sub></a><br /><a href="https://github.com/ExpDev07/coronavirus-tracker-api/commits?author=JKSenthil" title="Code">πŸ’»</a> <a href="https://github.com/ExpDev07/coronavirus-tracker-api/commits?author=JKSenthil" title="Documentation">πŸ“–</a> <a href="https://github.com/ExpDev07/coronavirus-tracker-api/commits?author=JKSenthil" title="Tests">⚠️</a></td> </tr> <tr> <td align="center"><a href="https://github.com/SeanCena"><img src="https://avatars1.githubusercontent.com/u/17202203?v=4" width="100px;" alt=""/><br /><sub><b>SeanCena</b></sub></a><br /><a href="https://github.com/ExpDev07/coronavirus-tracker-api/commits?author=SeanCena" title="Code">πŸ’»</a> <a href="https://github.com/ExpDev07/coronavirus-tracker-api/commits?author=SeanCena" title="Documentation">πŸ“–</a> <a href="https://github.com/ExpDev07/coronavirus-tracker-api/commits?author=SeanCena" title="Tests">⚠️</a></td> <td align="center"><a href="https://github.com/Abdirahiim"><img src="https://avatars0.githubusercontent.com/u/13730460?v=4" width="100px;" alt=""/><br /><sub><b>Abdirahiim Yassin </b></sub></a><br /><a href="https://github.com/ExpDev07/coronavirus-tracker-api/commits?author=Abdirahiim" title="Documentation">πŸ“–</a> <a href="#tool-Abdirahiim" title="Tools">πŸ”§</a> <a href="#platform-Abdirahiim" title="Packaging/porting to new platform">πŸ“¦</a></td> <td align="center"><a href="https://github.com/kant"><img src="https://avatars1.githubusercontent.com/u/32717?v=4" width="100px;" alt=""/><br /><sub><b>DarΓ­o HereΓ±ΓΊ</b></sub></a><br /><a href="https://github.com/ExpDev07/coronavirus-tracker-api/commits?author=kant" title="Documentation">πŸ“–</a></td> <td align="center"><a href="https://github.com/o-ba"><img src="https://avatars1.githubusercontent.com/u/8812114?v=4" width="100px;" alt=""/><br /><sub><b>Oliver</b></sub></a><br /><a href="https://github.com/ExpDev07/coronavirus-tracker-api/commits?author=o-ba" title="Documentation">πŸ“–</a></td> <td align="center"><a href="http://www.carmelagreco.dev"><img src="https://avatars0.githubusercontent.com/u/5394906?v=4" width="100px;" alt=""/><br /><sub><b>carmelag</b></sub></a><br /><a href="https://github.com/ExpDev07/coronavirus-tracker-api/commits?author=carmelag" title="Documentation">πŸ“–</a></td> <td align="center"><a href="https://github.com/Kilo59"><img src="https://avatars3.githubusercontent.com/u/13108583?v=4" width="100px;" alt=""/><br /><sub><b>Gabriel</b></sub></a><br /><a href="https://github.com/ExpDev07/coronavirus-tracker-api/commits?author=Kilo59" title="Code">πŸ’»</a> <a href="#infra-Kilo59" title="Infrastructure (Hosting, Build-Tools, etc)">πŸš‡</a> <a href="https://github.com/ExpDev07/coronavirus-tracker-api/commits?author=Kilo59" title="Tests">⚠️</a> <a href="https://github.com/ExpDev07/coronavirus-tracker-api/commits?author=Kilo59" title="Documentation">πŸ“–</a></td> <td align="center"><a href="https://lioncoding.com"><img src="https://avatars0.githubusercontent.com/u/26142591?v=4" width="100px;" alt=""/><br /><sub><b>Kodjo Laurent Egbakou</b></sub></a><br /><a href="https://github.com/ExpDev07/coronavirus-tracker-api/commits?author=egbakou" title="Documentation">πŸ“–</a> <a href="#tool-egbakou" title="Tools">πŸ”§</a> <a href="#platform-egbakou" title="Packaging/porting to new platform">πŸ“¦</a></td> </tr> <tr> <td align="center"><a href="https://github.com/Turreted"><img src="https://avatars2.githubusercontent.com/u/41593269?v=4" width="100px;" alt=""/><br /><sub><b>Turreted</b></sub></a><br /><a href="https://github.com/ExpDev07/coronavirus-tracker-api/commits?author=Turreted" title="Code">πŸ’»</a></td> <td align="center"><a href="http://ibtida.me"><img src="https://avatars1.githubusercontent.com/u/33792969?v=4" width="100px;" alt=""/><br /><sub><b>Ibtida Bhuiyan</b></sub></a><br /><a href="https://github.com/ExpDev07/coronavirus-tracker-api/commits?author=ibhuiyan17" title="Code">πŸ’»</a> <a href="https://github.com/ExpDev07/coronavirus-tracker-api/commits?author=ibhuiyan17" title="Documentation">πŸ“–</a></td> <td align="center"><a href="https://github.com/james-gray"><img src="https://avatars1.githubusercontent.com/u/2904597?v=4" width="100px;" alt=""/><br /><sub><b>James Gray</b></sub></a><br /><a href="https://github.com/ExpDev07/coronavirus-tracker-api/commits?author=james-gray" title="Code">πŸ’»</a></td> <td align="center"><a href="https://github.com/nischalshankar"><img src="https://avatars2.githubusercontent.com/u/33793411?v=4" width="100px;" alt=""/><br /><sub><b>Nischal Shankar</b></sub></a><br /><a href="https://github.com/ExpDev07/coronavirus-tracker-api/commits?author=nischalshankar" title="Code">πŸ’»</a> <a href="https://github.com/ExpDev07/coronavirus-tracker-api/commits?author=nischalshankar" title="Documentation">πŸ“–</a></td> </tr> </table> <!-- markdownlint-enable --> <!-- prettier-ignore-end --> <!-- ALL-CONTRIBUTORS-LIST:END -->

License

See LICENSE.md for the license. Please link to this repo somewhere in your project :).