coronavirus-us-api

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 [email protected]: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.

Name		Name	Last commit message	Last commit date
Latest commit History 233 Commits
.github		.github
backend		backend
data		data
e2e		e2e
load		load
static		static
tests		tests
.coveragerc		.coveragerc
.dockerignore		.dockerignore
.example.env		.example.env
.flake8		.flake8
.gitignore		.gitignore
.isort.cfg		.isort.cfg
.pre-commit-config.yaml		.pre-commit-config.yaml
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
Pipfile		Pipfile
Pipfile.lock		Pipfile.lock
Procfile		Procfile
README.md		README.md
codecov.yml		codecov.yml
docker-compose.yml		docker-compose.yml
requirements.txt		requirements.txt
runtime.txt		runtime.txt
tasks.py		tasks.py

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

coronavirus-us-api

What

Built With

Documentation

Data Sources

Endpoints

Location Data

Country

State

County

Latest

Sources

Heartbeat

Development

Docker

Projects Using This API

License

About

Releases 1

Sponsor this project

Packages

Contributors 2

Languages

License

Spiderpig86/coronavirus-us-api

Folders and files

Latest commit

History

Repository files navigation

coronavirus-us-api

What

Built With

Documentation

Data Sources

Endpoints

Location Data

Country

State

County

Latest

Sources

Heartbeat

Development

Docker

Projects Using This API

License

About

Topics

Resources

License

Stars

Watchers

Forks

Releases 1

Sponsor this project

Packages 0

Contributors 2

Languages

Packages