Skip to content

Commit ca7be61

Browse files
ExpDev07ExpDev07
authored
Merge pull request #150 from carmelag/api-docs-changes
Api docs changes
2 parents 56c5be6 + a2473c1 commit ca7be61

File tree

1 file changed

+224
-42
lines changed

1 file changed

+224
-42
lines changed

‎README.md‎

Lines changed: 224 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,6 @@
1-
<h1 align="center">
2-
coronavirus-tracker (API)
3-
</h1>
4-
5-
> This is a fast (< 200ms) and basic API for tracking development of the new coronavirus (COVID-19, SARS-CoV-2). It's written in python using 🍼 Flask. Supports multiple sources!
1+
## Coronavirus Tracker API
2+
Provides up-to-date data about Coronavirus outbreak. Includes numbers about confirmed cases, deaths and recovered.
3+
Support multiple data-sources.
64

75
![Travis build](https://api.travis-ci.com/ExpDev07/coronavirus-tracker-api.svg?branch=master)
86
[![License](https://img.shields.io/github/license/ExpDev07/coronavirus-tracker-api)](LICENSE.md)
@@ -20,26 +18,58 @@
2018
![Covid-19 Recovered](https://covid19-badges.herokuapp.com/recovered/latest)
2119
![Covid-19 Deaths](https://covid19-badges.herokuapp.com/deaths/latest)
2220

23-
## Endpoints
21+
## Available data-sources:
22+
23+
Currently 2 different data-sources are available to retrieve the data:
2424

25-
All requests must be made to the base url: ``https://coronavirus-tracker-api.herokuapp.com/v2/`` (e.g: https://coronavirus-tracker-api.herokuapp.com/v2/locations). You can try them out in your browser to further inspect responses.
25+
* **jhu** - https://github.com/CSSEGISandData/COVID-19 - Worldwide Data repository operated by the Johns Hopkins University Center for Systems Science and Engineering (JHU CSSE).
2626

27-
### Picking data source
27+
* **csbs** - https://www.csbs.org/information-covid-19-coronavirus - U.S. County data that comes from the Conference of State Bank Supervisors.
2828

29-
We provide multiple data-sources you can pick from, simply add the query parameter ``?source=your_source_of_choice`` to your requests. JHU will be used as a default if you don't provide one. Dynamically retrieve available sources at ``/v2/sources``.
29+
__jhu__ data-source will be used as a default source if you don't specify a *source parameter* in your request.
3030

31-
#### Available sources:
3231

33-
* **jhu** - https://github.com/CSSEGISandData/COVID-19 - Data repository operated by the Johns Hopkins University Center for Systems Science and Engineering (JHU CSSE).
32+
## API Reference
3433

35-
* **csbs** - https://www.csbs.org/information-covid-19-coronavirus - U.S. County data that comes from the Conference of State Bank Supervisors.
34+
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:
35+
*[https://coronavirus-tracker-api.herokuapp.com/v2/locations](https://coronavirus-tracker-api.herokuapp.com/v2/locations)*
36+
37+
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:
38+
39+
```
40+
curl https://coronavirus-tracker-api.herokuapp.com/v2/locations | json_pp
41+
```
3642

37-
* **... more to come later**.
3843

39-
### Getting latest amount of total confirmed cases, deaths, and recoveries.
44+
## API Endpoints
45+
46+
### Sources Endpoint
47+
48+
Getting the data-sources that are currently available to Coronavirus Tracker API to retrieve the data of the pandemic.
49+
50+
```http
51+
GET /v2/sources
52+
```
53+
54+
__Sample response__
55+
```json
56+
{
57+
"sources": [
58+
"jhu",
59+
"csbs"
60+
]
61+
}
62+
```
63+
64+
### Latest Endpoint
65+
66+
Getting latest amount of total confirmed cases, deaths, and recovered.
67+
4068
```http
4169
GET /v2/latest
4270
```
71+
72+
__Sample response__
4373
```json
4474
{
4575
"latest": {
@@ -50,10 +80,63 @@ GET /v2/latest
5080
}
5181
```
5282

53-
### Getting all locations.
83+
__Query String Parameters__
84+
| __Query string parameter__ | __Description__ | __Type__ |
85+
| -------------------------- | -------------------------------------------------------------------------------- | -------- |
86+
| source | The data-source where data will be retrieved from *(jhu/csbs)*. Default is *jhu* | String |
87+
88+
89+
### Locations Endpoint
90+
91+
Getting latest amount of confirmed cases, deaths, and recovered per location.
92+
93+
#### The Location Object
94+
```http
95+
GET /v2/locations/:id
96+
```
97+
98+
__Path Parameters__
99+
| __Path parameter__ | __Required/Optional__ | __Description__ | __Type__ |
100+
| ------------------ | --------------------- | ------------------------------------------------------------------------- | -------- |
101+
| id | OPTIONAL | The unique location id for which you want to call the Locations Endpoint. | Integer |
102+
103+
104+
#### Example Request
105+
```http
106+
GET /v2/locations/39
107+
```
108+
__Sample response__
109+
```json
110+
{
111+
"location": {
112+
"id": 39,
113+
"country": "Norway",
114+
"country_code": "NO",
115+
"province": "",
116+
"last_updated": "2020-03-21T06:59:11.315422Z",
117+
"coordinates": { },
118+
"latest": { },
119+
"timelines": {
120+
"confirmed": {
121+
"latest": 1463,
122+
"timeline": {
123+
"2020-03-16T00:00:00Z": 1333,
124+
"2020-03-17T00:00:00Z": 1463
125+
}
126+
},
127+
"deaths": { },
128+
"recovered": { }
129+
}
130+
}
131+
}
132+
```
133+
134+
#### List of all locations
54135
```http
55136
GET /v2/locations
56137
```
138+
139+
__Sample response__
57140
```json
58141
{
59142
"latest": {
@@ -98,50 +181,149 @@ GET /v2/locations
98181
}
99182
```
100183

101-
Additionally, you can also filter by any attribute, including province and country ([alpha-2 country_code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).
184+
__Query String Parameters__
185+
| __Query string parameter__ | __Description__ | __Type__ |
186+
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -------- |
187+
| source | The data-source where data will be retrieved from.<br>__Value__ can be: *jhu/csbs*. __Default__ is *jhu* | String |
188+
| country_code | The ISO ([alpha-2 country_code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)) to the Country/Province for which you're calling the Endpoint | String |
189+
| timelines | To set the visibility of timelines (*daily tracking*).<br>__Value__ can be: *0/1*. __Default__ is *0* (timelines are not visible) | Integer |
190+
191+
192+
__Response definitions__
193+
| __Response Item__ | __Description__ | __Type__ |
194+
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -------- |
195+
| {latest} | The total amount of confirmed cases, deaths and recovered for all the locations | Object |
196+
| {latest}/confirmed | The up-to-date total number of confirmed cases for all the locations within the data-source | Integer |
197+
| {latest}/deaths | The up-to-date total amount of deaths for all the locations within the data-source | Integer |
198+
| {latest}/recovered | The up-to-date total amount of recovered for all the locations within the data-source | Integer |
199+
| {locations} | The collection of locations contained within the data-source | Object |
200+
| {location} | Information that identifies a location | Object |
201+
| {latest} | The amount of confirmed cases, deaths and recovered related to the specific location | Object |
202+
| {locations}/{location}/{latest}/confirmed | The up-to-date number of confirmed cases related to the specific location | Integer |
203+
| {locations}/{location}/{latest}/deaths | The up-to-date number of deaths related to the specific location | Integer |
204+
| {locations}/{location}/{latest}/recovered | The up-to-date number of recovered related to the specific location | Integer |
205+
| {locations}/{location}/id | The location id. This unique id is assigned to the location by the data-source. | Integer |
206+
| {locations}/{location}/country | The Country name | String |
207+
| {locations}/{location}/country_code | The [ISO alpha-2 country_code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) Country code for the location. | String |
208+
| {locations}/{location}/province | The province where the location belongs to. (Used for US locations coming from __csbs data-source__.<br>__Empty__ when *jhu data-source* is used | String |
209+
| {locations}/{location}/{coordinates}/latitude | The location latitude | Float |
210+
| {locations}/{location}/{coordinates}/longitude | The location longitude | Float |
211+
212+
213+
### Example Requests with parameters
214+
215+
__Parameter: country_code__
216+
217+
Getting data for the Country specified by the *country_code parameter*, in this case Italy - IT
218+
102219
```http
103-
GET /v2/locations?country_code=US
220+
GET /v2/locations?country_code=IT
104221
```
105222

106-
Include timelines.
107-
```http
108-
GET /v2/locations?timelines=1
223+
__Sample Response__
224+
```json
225+
{
226+
"latest": {
227+
"confirmed": 59138,
228+
"deaths": 5476,
229+
"recovered": 7024
230+
},
231+
"locations": [
232+
{
233+
"coordinates": {
234+
"latitude": "43",
235+
"longitude": "12"
236+
},
237+
"country": "Italy",
238+
"country_code": "IT",
239+
"id": 16,
240+
"last_updated": "2020-03-23T13:32:23.913872Z",
241+
"latest": {
242+
"confirmed": 59138,
243+
"deaths": 5476,
244+
"recovered": 7024
245+
},
246+
"province": ""
247+
}
248+
]
249+
}
109250
```
110251

111-
### Getting a specific location (includes timelines by default).
252+
__Parameter: source__
253+
254+
Getting the data from the data-source specified by the *source parameter*, in this case [csbs](https://www.csbs.org/information-covid-19-coronavirus)
255+
256+
112257
```http
113-
GET /v2/locations/:id
258+
GET /v2/locations?source=csbs
114259
```
260+
261+
__Sample Response__
115262
```json
116263
{
117-
"location": {
118-
"id": 39,
119-
"country": "Norway",
120-
"country_code": "NO",
121-
"province": "",
122-
"last_updated": "2020-03-21T06:59:11.315422Z",
123-
"coordinates": { },
124-
"latest": { },
125-
"timelines": {
126-
"confirmed": {
127-
"latest": 1463,
128-
"timeline": {
129-
"2020-03-16T00:00:00Z": 1333,
130-
"2020-03-17T00:00:00Z": 1463
131-
}
264+
"latest": {
265+
"confirmed": 7596,
266+
"deaths": 43,
267+
"recovered": 0
268+
},
269+
"locations": [
270+
{
271+
"id": 0,
272+
"country": "US",
273+
"country_code": "US",
274+
"province": "New York",
275+
"state": "New York",
276+
"county": "New York",
277+
"last_updated": "2020-03-21T14:00:00Z",
278+
"coordinates": {
279+
"latitude": 40.71455,
280+
"longitude": -74.00714
281+
},
282+
"latest": {
283+
"confirmed": 6211,
284+
"deaths": 43,
285+
"recovered": 0
286+
}
287+
},
288+
{
289+
"id": 1,
290+
"country": "US",
291+
"country_code": "US",
292+
"province": "New York",
293+
"state": "New York",
294+
"county": "Westchester",
295+
"last_updated": "2020-03-21T14:00:00Z",
296+
"coordinates": {
297+
"latitude": 41.16319759,
298+
"longitude": -73.7560629
299+
},
300+
"latest": {
301+
"confirmed": 1385,
302+
"deaths": 0,
303+
"recovered": 0
132304
},
133-
"deaths": { },
134-
"recovered": { }
135305
}
136-
}
306+
]
137307
}
138308
```
139309

140-
Exclude timelines.
310+
__Parameter: timelines__
311+
312+
Getting the data for all the locations including the daily tracking of confirmed cases, deaths and recovered per location.
313+
141314
```http
142-
GET /v2/locations?timelines=0
315+
GET /v2/locations?timelines=1
316+
```
317+
Explore the response by opening the URL in your browser [https://coronavirus-tracker-api.herokuapp.com/v2/locations?timelines=1](https://coronavirus-tracker-api.herokuapp.com/v2/locations?timelines=1) or make the following curl call in your terminal:
318+
319+
```
320+
curl https://coronavirus-tracker-api.herokuapp.com/v2/locations?timelines=1 | json_pp
143321
```
144322

323+
__NOTE:__ Timelines tracking starts from day 22nd January 2020 and ends to the last available day in the data-source.
324+
325+
326+
145327
## Wrappers
146328

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

0 commit comments

Comments
 (0)