Giters

Spiderpig86 / coronavirus-us-api

🦠🇺🇸 A fast (< 400ms) microservice for live statistics on Coronavirus/Covid-19/SARS-CoV-2 impact on the US.

Home Page:http://coronavirus-us-api.herokuapp.com/

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

apicoronaviruscoronavirus-real-timecoronavirus-trackingcountycovid-19covid-19-usfastapimicroservicencovpythonrest

coronavirus-us-api

forthebadge


CI MIT License codecov Code style: black Reviewed by Hound

What

This API is designed to serve up to date information on confirmed cases and deaths across the United States at a country, state, and county level.

Built With

  • ⚡ FastAPI - a modern, fast (high-performance), web framework for building APIs with Python 3.6+ based on standard Python type hints.
  • 💰 Redis - in-memory data structure store/cache.
  • 🌾 Swagger - open source documentation tools.

Documentation

Since coronavirus-us-api is powered by FastAPI, the API specification strictly follows the OpenAPI standard. The JSON file for this API can be found here.

The API documentation comes in three flavors:

  • Swagger - standard way to test out the endpoints.
  • Redoc - mobile friendly documentation.
  • RapidAPI - documentation and testing managed by RapidAPI.

Data Sources

The data used by the API comes from two sources:

Endpoints

Before getting started, let's go over some of the common types you will see in the remainder of the documentation:

Timelines

Key Description Type
timelines Object containing measured statistics and their historical values. Object
timelines.statistic Object that contains information for that statistic. For now, only confirmed and deaths are supported. Object
timelines.statistic.history Object containing a list of key value pairs where the key is the date and the value is the number for that statistic for that date. Object
timelines.statistic.latest Value of statistic at current date. Object

Properties

Key Description Type
properties Object containing information regarding naming, classification, coordinates, and population. Object
propertes.uid Unique ID used by JHU CSSE to identify different locations. string
properties.iso2 Country code following alpha-2 ISO country name standards. string
properties.iso3 Country code following alpha-3 ISO country name standards. string
properties.code3 A three digit numerical country code identifier. string
properties.fips A five digit identifier for US county and county-equivalents. string
properties.county Name of US county if applicable. string
properties.state Name of US state if applicable. string
properties.country Code for country. string
properties.coordinates Object containing coordinates for given location. object
properties.coordinates.latitude Latitude of location. string
properties.coordinates.longitude Longitude of location. string
properties.combined_key Unique key combining location names based on specificity of request result. string
properties.population Population of location. number

Location Data

Endpoints for fetching information (confirmed, deaths, etc) at the country, state, or county level. By default, these endpoints will show the latest statistic. Other fields such as the timeline and properties for the location can be enabled via query parameters.

Country

Retrieve information on the country level.

GET /api/country/all

Query Parameters

Parameter Description Type
source The data source to fetch data from.
Options: ["nyt", "jhu"]
Default: "nyt"		 string
timelines Display timeline for daily statistics.
Default: false		 boolean
properties Display properties associated with a given location.
Default: false		 boolean

Sample Request

GET /api/country/all?timelines=true&properties=true
Sample Response 
{
  "latest": {
    "confirmed": 3199715,
    "deaths": 133901
  },
  "locations": [
    {
      "id": "US",
      "country": "US",
      "state": "",
      "county": "",
      "fips": "",
      "timelines": {
        "confirmed": {
          "history": {
            "2020-01-21": 1,
            "2020-01-22": 1,
            "2020-01-23": 1,
            ... 
          },
          "latest": 3199715
        },
        "deaths": {
          "history": {
            "2020-01-21": 0,
            "2020-01-22": 0,
            "2020-01-23": 0,
            ...
          },
          "latest": 133901
        }
      },
      "last_updated": "2020-07-11",
      "latest": {
        "confirmed": 3199715,
        "deaths": 133901
      },
      "properties": {
        "uid": "840",
        "iso2": "US",
        "iso3": "USA",
        "code3": "840",
        "fips": "",
        "county": "",
        "state": "",
        "country": "US",
        "coordinates": {
          "latitude": "37.0902",
          "longitude": "-95.7129"
        },
        "combined_key": "United States",
        "population": 329466283
      }
    }
  ]
}

Response

Key Description Type
latest Object containing latest measurements for supported statistics. object
latest.statistic Contains the value for statistic at current date. number
locations List of Location matching given criteria if present. List
locations.location.id Unique ID for the country. string
locations.location.country Name of the country. string
locations.location.state State of the location if applicable. string
locations.location.county County of the location if applicable. string
locations.location.fips Fips code of location if applicable. string
locations.location.timelines Timeline for statistics in location. Timeline
locations.location.last_updated Date for when the data was updated. string
locations.location.latest Latest values for supported statistics. string
locations.location.properties Properties for a given location. Properties

State

Retrieve information on the state level.

GET /api/state/all

Query Parameters

Parameter Description Type
source The data source to fetch data from.
Options: ["nyt", "jhu"]
Default: "nyt"		 string
timelines Display timeline for daily statistics.
Default: false		 boolean
properties Display properties associated with a given location.
Default: false		 boolean
fips Only show locations matching the fips code. number
state Only show locations matching state name. The name can be the full name or a 2-letter ANSI code. string

Sample Request

GET /api/state/all?timelines=true&properties=true
Sample Response 
{
  "latest": {
    "confirmed": 3199790,
    "deaths": 133906
  },
  "locations": [
    {
      "id": "US@Washington@53",
      "country": "US",
      "state": "Washington",
      "county": "",
      "fips": "53",
      "timelines": {
        "confirmed": {
          "history": {
            "2020-01-21": 1,
            "2020-01-22": 1,
            "2020-01-23": 1,
            ...
          },
          "latest": 41090
        },
        "deaths": {
          "history": {
            "2020-01-21": 0,
            "2020-01-22": 0,
            "2020-01-23": 0,
            ...
          },
          "latest": 1426
        }
      },
      "last_updated": "2020-07-11",
      "latest": {
        "confirmed": 41090,
        "deaths": 1426
      },
      "properties": {
        "uid": "84000053",
        "iso2": "US",
        "iso3": "USA",
        "code3": "840",
        "fips": "53",
        "county": "",
        "state": "Washington",
        "country": "US",
        "coordinates": {
          "latitude": "47.4009",
          "longitude": "-121.4905"
        },
        "combined_key": "Washington, US",
        "population": 7614893
      }
    }
  ]
}

Response

Key Description Type
latest Object containing latest measurements for supported statistics. object
latest.statistic Contains the value for statistic at current date. number
locations List of Location matching given criteria if present. List
locations.location.id Unique ID for the country. string
locations.location.country Name of the country. string
locations.location.state State of the location if applicable. string
locations.location.county County of the location if applicable. string
locations.location.fips Fips code of location if applicable. string
locations.location.uid (Optional depends on source) Unique identifier for location. string
locations.location.iso2 (Optional depends on source) Country code following alpha-2 ISO country name standards. string
locations.location.iso3 (Optional depends on source) Country code following alpha-3 ISO country name standards. string
locations.location.code3 (Optional depends on source) A three digit numerical country code identifier. string
locations.location.latitude (Optional depends on source) Latitude of location string
locations.location.longitude (Optional depends on source) Longitude of location. string
locations.location.timelines Timeline for statistics in location. Timeline
locations.location.last_updated Date for when the data was updated. string
locations.location.latest Latest values for supported statistics. string
locations.location.properties Properties for a given location. Properties

Sample Request with Parameter

GET /api/state/all?state=WA
{
  "latest": {
    "confirmed": 39218,
    "deaths": 1424
  },
  "locations": [
    {
      "id": "US@Washington",
      "country": "US",
      "state": "Washington",
      "county": "",
      "fips": "53",
      "uid": "84000053",
      "iso2": "US",
      "iso3": "USA",
      "code3": "840",
      "latitude": "47.4009",
      "longitude": "-121.4905",
      "last_updated": "2020-07-11",
      "latest": {
        "confirmed": 39218,
        "deaths": 1424
      }
    }
  ]
}

County

Retrieve information on the county level.

GET /api/county/all

Query Parameters

Parameter Description Type
source The data source to fetch data from.
Options: ["nyt", "jhu"]
Default: "nyt"		 string
timelines Display timeline for daily statistics.
Default: false		 boolean
properties Display properties associated with a given location.
Default: false		 boolean
fips Only show locations matching the fips code. number
state Only show locations matching state name. The name can be the full name or a 2-letter ANSI code. string
county Only show locations matching county name. string

Sample Request

GET /api/county/all?source=jhu&timelines=true&properties=true
Sample Response 
{
  "latest": {
    "confirmed": 11568,
    "deaths": 633
  },
  "locations": [
    {
      "id": "US@Texas@King",
      "country": "US",
      "last_updated": "2020-07-11",
      "latest": {
        "confirmed": 0,
        "deaths": 0
      },
      "timelines": {
        "confirmed": {
          "latest": 0,
          "history": {
            "2020-01-22": 0,
            "2020-01-23": 0,
            ...
          }
        },
        "deaths": {
          "latest": 0,
          "history": {
            "2020-01-22": 0,
            "2020-01-23": 0,
            ...
          }
        }
      },
      "properties": {
        "uid": "84048269",
        "iso2": "US",
        "iso3": "USA",
        "code3": "840",
        "fips": "48269",
        "county": "King",
        "state": "Texas",
        "country": "US",
        "coordinates": {
          "latitude": "33.61643847",
          "longitude": "-100.2558057"
        },
        "combined_key": "King, Texas, US",
        "population": 272
      },
      "uid": "84048269",
      "iso2": "US",
      "iso3": "USA",
      "code3": "840",
      "state": "Texas",
      "county": "King",
      "fips": "48269.0",
      "latitude": "33.61643847",
      "longitude": "-100.2558057"
    },
    {
      "id": "US@Washington@King",
      "country": "US",
      "last_updated": "2020-07-11",
      "latest": {
        "confirmed": 11568,
        "deaths": 633
      },
      "timelines": {
        "confirmed": {
          "latest": 11568,
          "history": {
            "2020-01-22": 1,
            "2020-01-23": 1,
            ...
          }
        },
        "deaths": {
          "latest": 633,
          "history": {
            "2020-01-22": 0,
            "2020-01-23": 0,
            ...
          }
        }
      },
      "properties": {
        "uid": "84053033",
        "iso2": "US",
        "iso3": "USA",
        "code3": "840",
        "fips": "53033",
        "county": "King",
        "state": "Washington",
        "country": "US",
        "coordinates": {
          "latitude": "47.49137892",
          "longitude": "-121.8346131"
        },
        "combined_key": "King, Washington, US",
        "population": 2252782
      },
      "uid": "84053033",
      "iso2": "US",
      "iso3": "USA",
      "code3": "840",
      "state": "Washington",
      "county": "King",
      "fips": "53033.0",
      "latitude": "47.49137892",
      "longitude": "-121.8346131"
    },
    ...
  ]
}

Response

Key Description Type
latest Object containing latest measurements for supported statistics. object
latest.statistic Contains the value for statistic at current date. number
locations List of Location matching given criteria if present. List
locations.location.id Unique ID for the country. string
locations.location.country Name of the country. string
locations.location.state State of the location if applicable. string
locations.location.county County of the location if applicable. string
locations.location.fips Fips code of location if applicable. string
locations.location.uid (Optional depends on source) Unique identifier for location. string
locations.location.iso2 (Optional depends on source) Country code following alpha-2 ISO country name standards. string
locations.location.iso3 (Optional depends on source) Country code following alpha-3 ISO country name standards. string
locations.location.code3 (Optional depends on source) A three digit numerical country code identifier. string
locations.location.latitude (Optional depends on source) Latitude of location string
locations.location.longitude (Optional depends on source) Longitude of location. string
locations.location.timelines Timeline for statistics in location. Timeline
locations.location.last_updated Date for when the data was updated. string
locations.location.latest Latest values for supported statistics. string
locations.location.properties Properties for a given location. Properties

Sample Request with Parameter

GET /api/state/all?source=jhu&county=King
  "latest": {
    "confirmed": 0,
    "deaths": 0
  },
  "locations": [
    {
      "id": "US@New York@Queens",
      "country": "US",
      "last_updated": "2020-07-12",
      "latest": {
        "confirmed": 0,
        "deaths": 0
      },
      "timelines": {
        "confirmed": {
          "latest": 0,
          "history": {
            "2020-01-22": 0,
            "2020-01-23": 0,
            ...
          }
        },
        "deaths": {
          "latest": 0,
          "history": {
            "2020-01-22": 0,
            "2020-01-23": 0,
            ...
          }
        }
      },
      "uid": "84036081",
      "iso2": "US",
      "iso3": "USA",
      "code3": "840",
      "state": "New York",
      "county": "Queens",
      "fips": "36081.0",
      "latitude": "40.71088124",
      "longitude": "-73.81684712"
    }
  ]
}
  • Note: Multiple locations that share the same county name or share the same state will also be shown. The value you see for latest is the aggregate for all matching results.
GET /api/county/all?source=jhu&county=king&timelines=true&properties=true
{
  "latest": {
    "confirmed": 11568,
    "deaths": 633
  },
  "locations": [
    {
      "id": "US@Texas@King",
      "country": "US",
      "last_updated": "2020-07-11",
      "latest": {
        "confirmed": 0,
        "deaths": 0
      },
      "timelines": {
        "confirmed": {
          "latest": 0,
          "history": {
            "2020-01-22": 0,
            "2020-01-23": 0,
            ...
          }
        },
        "deaths": {
          "latest": 0,
          "history": {
            "2020-01-22": 0,
            "2020-01-23": 0,
            ...
          }
        }
      },
      "properties": {
        "uid": "84048269",
        "iso2": "US",
        "iso3": "USA",
        "code3": "840",
        "fips": "48269",
        "county": "King",
        "state": "Texas",
        "country": "US",
        "coordinates": {
          "latitude": "33.61643847",
          "longitude": "-100.2558057"
        },
        "combined_key": "King, Texas, US",
        "population": 272
      },
      "uid": "84048269",
      "iso2": "US",
      "iso3": "USA",
      "code3": "840",
      "state": "Texas",
      "county": "King",
      "fips": "48269.0",
      "latitude": "33.61643847",
      "longitude": "-100.2558057"
    },
    {
      "id": "US@Washington@King",
      "country": "US",
      "last_updated": "2020-07-11",
      "latest": {
        "confirmed": 11568,
        "deaths": 633
      },
      "timelines": {
        "confirmed": {
          "latest": 11568,
          "history": {
            "2020-01-22": 1,
            "2020-01-23": 1,
            ...
          }
        },
        "deaths": {
          "latest": 633,
          "history": {
            "2020-01-22": 0,
            "2020-01-23": 0,
            ...
          }
        }
      },
      "properties": {
        "uid": "84053033",
        "iso2": "US",
        "iso3": "USA",
        "code3": "840",
        "fips": "53033",
        "county": "King",
        "state": "Washington",
        "country": "US",
        "coordinates": {
          "latitude": "47.49137892",
          "longitude": "-121.8346131"
        },
        "combined_key": "King, Washington, US",
        "population": 2252782
      },
      "uid": "84053033",
      "iso2": "US",
      "iso3": "USA",
      "code3": "840",
      "state": "Washington",
      "county": "King",
      "fips": "53033.0",
      "latitude": "47.49137892",
      "longitude": "-121.8346131"
    },
    ...
  ]
}

Latest

Retrieve the latest statistics for the entire country.

GET /api/country/latest

Query Parameters

Parameter Description Type
source The data source to fetch data from.
Options: ["nyt", "jhu"]
Default: "nyt"		 string

Sample Request

GET /api/county/latest?source=jhu
Sample Response 
{
  "latest": {
    "confirmed": 3184573,
    "deaths": 134092
  },
  "last_updated": "2020-07-12"
}

Sources

Retrieve the list of sources that the API supports.

GET /api/data/sources

Sample Request

GET /api/data/sources
Sample Response 
{
  "sources": [
    "nyt",
    "jhu"
  ]
}

Heartbeat

Endpoint to test service health.

GET /api/health/heartbeat

Sample Request

GET /api/health/heartbeat
Sample Response 
{
  "is_alive": true
}

Development

Below are some of the dependencies you will need:

Then, clone the repository and create a Pipenv environment.

$ git clone git@github.com:Spiderpig86/coronavirus-us-api.git
$ cd ./coronavirus-us-api

Install Pipenv and set up your virtual environment with the needed dependencies.

$ pip install --user pipenv
$ pipenv sync --dev
$ pipenv shell

Now that this is all setup, you can run the commands to run, test, and format the project. The project will start at localhost:8000 by default (configurable in backend/core/config/config.yml):

Debugging/Live Reloading

$ pipenv run dev

Running

$ pipenv run start

Formatting

$ invoke black

Sort Imports

$ invoke sort

Linting

$ invoke check

Unit Testing

$ invoke test

End to End Tests

$ invoke e2e

Generate Test Coverage

$ invoke coverage

Docker

Setting up Docker is quite straight forward -- unless you are using Windows 10 Home (more on this later).

Run these commands.

docker-compose build
docker-compose up

If you are using a non-supported OS for Docker, you would need to use Docker Toolkit. Once you have it set up, if you are not able to access the container itself, allow port 8080 in your VM. Reference

Projects Using This API

Let me know if you are using the API! It means a great deal.

License

See LICENSE.md for information regarding usage and attribution.

About

🦠🇺🇸 A fast (< 400ms) microservice for live statistics on Coronavirus/Covid-19/SARS-CoV-2 impact on the US.

http://coronavirus-us-api.herokuapp.com/

apicoronaviruscoronavirus-real-timecoronavirus-trackingcountycovid-19covid-19-usfastapimicroservicencovpythonrest

License:GNU General Public License v3.0

Languages

Language:Python 95.2%Language:JavaScript 4.3%Language:Dockerfile 0.2%Language:Procfile 0.2%Language:Makefile 0.1%