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:
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
Golang
C#
Python
Java
Node.js
Ruby
Lua
Prerequisites
You will need the following things properly installed on your computer.
Installation
git clone https://github.com/ExpDev07/coronavirus-tracker-api.gitcd coronavirus-tracker-api
- Make sure you have
python3.8installed and on yourPATH. - Install the
pipenvdependency manager- with pipx
$ pipx install pipenv - with Homebrew/Linuxbrew
$ brew install pipenv - with pip/pip3 directly
$ pip install --user pipenv
- with pipx
- 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
pipenv run test
Linting
pipenv run lint
Formatting
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):
License
See LICENSE.md for the license. Please link to this repo somewhere in your project :).
![[BUG]Death data missing from countries id266 onwards as from 23/08/22](https://avatars.githubusercontent.com/u/62831517?v=4)
![[BUG] Unable to access the site. Error 503 (Service Unavailable)](https://avatars.githubusercontent.com/u/1524687?v=4)
10 Dec 02, 2022
12.7k Jan 03, 2023
38 Feb 20, 2022
2 Apr 28, 2022
2 Nov 29, 2021
3 Aug 11, 2022
1 Dec 18, 2021
2 Feb 01, 2022
37 Dec 20, 2022
2 Nov 15, 2021
4 Sep 13, 2021
5 Nov 08, 2021
1 Jan 01, 2022
1 May 10, 2022
33 Dec 22, 2022
2.7k Jan 03, 2023
1 Dec 16, 2021
104 Dec 29, 2022
79 Nov 16, 2022
2 Feb 17, 2022