Awesome

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

• :zap: FastAPI - a modern, fast (high-performance), web framework for building APIs with Python 3.6+ based on standard Python type hints.
• :moneybag: Redis - in-memory data structure store/cache.
• :ear_of_rice: 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:

• New York Times
• John Hopkins University

Endpoints

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

Timelines

Properties

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

Sample Request

GET /api/country/all?timelines=true&properties=true

{
  "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

State

Retrieve information on the state level.

GET /api/state/all

Query Parameters

Sample Request

GET /api/state/all?timelines=true&properties=true

{
  "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

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

Sample Request

GET /api/county/all?source=jhu&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"
    },
    ...
  ]
}

Response

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

Sample Request

GET /api/county/latest?source=jhu

{
  "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

{
  "sources": [
    "nyt",
    "jhu"
  ]
}

Heartbeat

Endpoint to test service health.

GET /api/health/heartbeat

Sample Request

GET /api/health/heartbeat

{
  "is_alive": true
}

Development

Below are some of the dependencies you will need:

• Python 3.7+
• Pipenv

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.

• CovidPovertyLink

License

See LICENSE.md for information regarding usage and attribution.