The Covid Atlas API: Sharing Hotspot Statistics

Our team is excited to announce the release of the Covid Atlas API! Break out the masks and socially distanced festivities in celebration.

The Covid Atlas’ public data API provides access to state-level and county-level USAFacts confirmed case and death count data, and a local indicator of spatial association (ie. our hotspot statistics).

The US Covid Atlas “Hotspot” statistics show COVID hotspot clusters (red), or counties with high rates surrounded by other counties with high rates as well as coldspots (blue), which are counties with low rates surrounded by similarly low numbers. We also highlight outliers in either direction (pink and light blue). This snapshot shows a 7-day ave of new cases per 100,000 persons, as of Oct 9, 2020.

This will allow developers to directly access case data (via USAFacts), and/or daily hot spot statistics (using USAFacts or 1P3A inputs) at county and state levels. We thought of the best way to deliver the statistical hotspot data dynamically (since we update daily), and this was the best option!

• API requests will be made to: https://api.theuscovidatlas.org/v1/data
• Users should first register for an API key. A confirmation email will be sent to you with an API key once we’ve processed your request.
• All data are returned in JSON format.
• All dates and times are in US central time (CDT).
• Data are updated on a daily basis every afternoon.

A breakdown of the API architecture for accessing hot spot statistics

The details and parameter specifications can be found on the API page at the Covid Atlas main site: https://geodacenter.github.io/covid/api.html

We provide two examples of using the API, in python and curl.

Python Example:

import requests
url = 'https://api.theuscovidatlas.org/v1/data/?state=AZ&category=lisa'
headers = {'x-api-key': 'insert your API key'}
req = requests.get(url, headers=headers)
req.text

curl Example:

curl -X GET \
'https://api.theuscovidatlas.org/v1/data/?state=AZ&category=lisa' \
-H 'content-type: application/json' \
-d '{"x-api-key": "insert your API key"}'

The statistics behind the hotspots are local indicators of spatial association (LISA), which we calculate using pygeoda. The same calculation happens on the front-end every time you open the US Covid Atlas, using a different iteration of a geoda library. Check out the API page for more details!

This project was brought to you by our Data Engineer Fellow Stephanie Yang and Software Engineer Extraordinaire Vidal Anguiano Jr., with write-up by M. Kolak, edits by V. Anguiano, & D. Halpern.