Merge master with fast-api conversion.

.all-contributorsrc

@@ -110,6 +110,15 @@
       "contributions": [
         "doc"
       ]
+    },
+    {
+      "login": "carmelag",
+      "name": "carmelag",
+      "avatar_url": "https://avatars0.githubusercontent.com/u/5394906?v=4",
+      "profile": "http://www.carmelagreco.dev",
+      "contributions": [
+        "doc"
+      ]
     }
   ],
   "contributorsPerLine": 7,

README.md

@@ -1,8 +1,6 @@
-<h1 align="center">
-  coronavirus-tracker (API)
-</h1>
-
-> 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!
+## Coronavirus Tracker API
+Provides up-to-date data about Coronavirus outbreak. Includes numbers about confirmed cases, deaths and recovered.
+Support multiple data-sources.
 
 ![Travis build](https://api.travis-ci.com/ExpDev07/coronavirus-tracker-api.svg?branch=master)
 [![License](https://img.shields.io/github/license/ExpDev07/coronavirus-tracker-api)](LICENSE.md)
@@ -20,26 +18,63 @@
 ![Covid-19 Recovered](https://covid19-badges.herokuapp.com/recovered/latest)
 ![Covid-19 Deaths](https://covid19-badges.herokuapp.com/deaths/latest)
 
-## Endpoints
+## Available data-sources:
+
+Currently 2 different data-sources are available to retrieve the data:
 
-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.
+* **jhu** - https://github.com/CSSEGISandData/COVID-19 - Worldwide Data repository operated by the Johns Hopkins University Center for Systems Science and Engineering (JHU CSSE). 
 
-### Picking data source
+* **csbs** - https://www.csbs.org/information-covid-19-coronavirus - U.S. County data that comes from the Conference of State Bank Supervisors.
 
-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.
+__jhu__ data-source will be used as a default source if you don't specify a *source parameter* in your request.
 
-#### Available sources:
 
-* **jhu** - https://github.com/CSSEGISandData/COVID-19 - Data repository operated by the Johns Hopkins University Center for Systems Science and Engineering (JHU CSSE).
+## API Reference
 
-* **csbs** - https://www.csbs.org/information-covid-19-coronavirus - U.S. County data that comes from the Conference of State Bank Supervisors.
+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](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
+```
+
+
+## API Endpoints 
+
+### Sources Endpoint
+
+Getting the data-sources that are currently available to Coronavirus Tracker API to retrieve the data of the pandemic.
+
+```http
+GET /v2/sources
+```
+
+__Sample response__
+```json
+{
+    "sources": [
+        "jhu",
+        "csbs"
+    ]
+}
+```
 
-* **... more to come later**.
+### Latest Endpoint
+
+Getting latest amount of total confirmed cases, deaths, and recovered.
 
-### Getting latest amount of total confirmed cases, deaths, and recoveries.
 ```http
 GET /v2/latest
 ```
+
+__Query String Parameters__
+| __Query string parameter__ | __Description__                                                                  | __Type__ |
+| -------------------------- | -------------------------------------------------------------------------------- | -------- |
+| source                     | The data-source where data will be retrieved from *(jhu/csbs)*. Default is *jhu* | String   |
+
+__Sample response__
 ```json
 {
   "latest": {
@@ -50,10 +85,69 @@ GET /v2/latest
 }
 ```
 
-### Getting all locations.
+### Locations Endpoint
+
+Getting latest amount of confirmed cases, deaths, and recovered per location.
+
+#### The Location Object
+```http
+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. | Integer  |
+
+__Query String Parameters__
+| __Query string parameter__ | __Description__                                                                  | __Type__ |
+| -------------------------- | -------------------------------------------------------------------------------- | -------- |
+| source                     | The data-source where data will be retrieved from *(jhu/csbs)*. Default is *jhu* | String   |
+
+#### Example Request
+```http
+GET /v2/locations/39
+```
+
+__Sample response__
+```json
+{
+  "location": {
+    "id": 39,
+    "country": "Norway",
+    "country_code": "NO",
+    "province": "",
+    "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
 ```http
 GET /v2/locations
 ```
+
+__Query String Parameters__
+| __Query string parameter__ | __Description__                                                                                                                                  | __Type__ |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -------- |
+| source                     | The data-source where data will be retrieved from.<br>__Value__ can be: *jhu/csbs*. __Default__ is *jhu*                                         | String   |
+| 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   |
+| timelines                  | To set the visibility of timelines (*daily tracking*).<br>__Value__ can be: *0/1*. __Default__ is *0* (timelines are not visible)                | Integer  |
+
+__Sample response__
 ```json
 {
   "latest": {
@@ -98,54 +192,76 @@ GET /v2/locations
 }
 ```
 
-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)).
-```http
-GET /v2/locations?country_code=US
-```
+__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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) 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__.<br>__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
 
-Include timelines.
 ```http
-GET /v2/locations?timelines=1
+GET /v2/locations?country_code=IT
 ```
 
-### Getting a specific location (includes timelines by default).
-```http
-GET /v2/locations/:id
-```
+__Sample Response__
 ```json
 {
-  "location": {
-    "id": 39,
-    "country": "Norway",
-    "country_code": "NO",
-    "province": "",
-    "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
+    "latest": {
+        "confirmed": 59138,
+        "deaths": 5476,
+        "recovered": 7024
+    },
+    "locations": [
+        {
+            "coordinates": {
+                "latitude": "43",
+                "longitude": "12"
+            },
+            "country": "Italy",
+            "country_code": "IT",
+            "id": 16,
+            "last_updated": "2020-03-23T13:32:23.913872Z",
+            "latest": {
+                "confirmed": 59138,
+                "deaths": 5476,
+                "recovered": 7024
+            },
+            "province": ""
         }
-      },
-      "deaths": { },
-      "recovered": { }
-    }
-  }
+    ]
 }
 ```
 
-Exclude timelines.
-```http
-GET /v2/locations?timelines=0
-```
+__Parameter: source__
+
+Getting the data from the data-source specified by the *source parameter*, in this case [csbs](https://www.csbs.org/information-covid-19-coronavirus)
+
 
-### Getting US per county information.
 ```http
 GET /v2/locations?source=csbs
 ```
+
+__Sample Response__
 ```json
 {
   "latest": {
@@ -194,6 +310,23 @@ GET /v2/locations?source=csbs
 }
 ```
 
+__Parameter: timelines__
+
+Getting the data for all the locations including the daily tracking of confirmed cases, deaths and recovered per location.
+
+```http
+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](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.
@@ -284,6 +417,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
     <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></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>
   </tr>
 </table>
 

app/routes/__init__.py

@@ -1,12 +1,12 @@
-from flask import Blueprint, redirect, request, current_app as app
+from flask import Blueprint, redirect, request, abort, current_app as app
 from ..data import data_source
 
 # Follow the import order to avoid circular dependency
 api_v1 = Blueprint('api_v1', __name__, url_prefix='')
 api_v2 = Blueprint('api_v2', __name__, url_prefix='/v2')
 
 # API version 2.
-from .v2 import locations, latest
+from .v2 import locations, latest, sources
 
 # API version 1.
 from .v1 import confirmed, deaths, recovered, all
@@ -23,8 +23,12 @@ def datasource():
     Attaches the datasource to the request.
     """
     # Retrieve the datas ource from query param.
-    source = request.args.get('source', type=str, default='jhu')
+    source = data_source(request.args.get('source', type=str, default='jhu'))
+
+    # Abort with 404 if source cannot be found.
+    if not source:
+        return abort(404, description='The provided data-source was not found.')
 
     # Attach source to request and return it.
-    request.source = data_source(source)
+    request.source = source
     pass

app/routes/v2/locations.py

@@ -17,7 +17,7 @@ def locations():
             try:
                 locations = [j for j in locations if getattr(j, i) == args.get(i, type=str)]
             except AttributeError:
-                print('TimelinedLocation object does not have attribute {}.'.format(i))
+                print('Location does not have attribute {}.'.format(i))
 
     # Serialize each location and return.
     return jsonify({

app/routes/v2/sources.py

@@ -0,0 +1,12 @@
+from flask import jsonify
+from ...data import data_sources
+from ...routes import api_v2 as api
+
+@api.route('/sources')
+def sources():
+    """
+    Retrieves a list of data-sources that are availble to use.
+    """
+    return jsonify({
+        'sources': list(data_sources.keys())
+    })