API


The Covid Atlas’ public data API provides access to state-level and county-level confirmed cases and death count data from USAFacts. We also provide local indicators of spatial association results (LISA statistics).

  • All dates and times are in US central time (CDT). Data are updated on a daily basis every afternoon.
  • Users should first register for an API key. You will recieve an email with your API key.
  • All data are returned in json format.


  • API Domain


    All API requests should be made to: https://api.theuscovidatlas.org


    Confirmed COVID Cases, Deaths


    DATA SOURCES

    Confirmed Case and Death Counts: USAFacts

    USAFacts provides county-level death and confirmed case data on a daily basis with updates every afternoon.


    API PARAMETERS

  • state (required): str case insensitive state abbreviation
  • category (required): str "data"
  • type (optional): str “confirmed”, “death”, defaults to “death”
  • source (optional): str “usafacts” case insensitive, defaults to “usafacts”
  • level (optional): str “state” or “county”, default as “county”
  • start (optional): 8-digit integer start date in format “20201005”, defaults to 7 days prior to today. Ranges from 20200122 to today
  • end (optional): 8-digit integer end date in format “20201005”, defaults to today. Ranges from 20200122 to today

  • API QUERY EXAMPLE

    To get county-level death data of Illinois from September 1st, 2020 to October 1st, 2020, the query should be set as:
    https://api.theuscovidatlas.org/v1/data/?state=il&category=data&start=20200901&end=20201001&type=death


    POSSIBLE ERROR MESSAGES

  • Invalid State Input: if the field is missing or have typos
  • Invalid Date: if start date is before 20200122 or end date after today, or end date before start date
  • Invalid Type: if type input is other than “death” or “confirmed”
  • Invalid Level Type: if level input is other than “state” or “county”
  • Internal server error: try making a smaller query by querying a shorter date range


  • LISA "HotSpot" Statistics


    DATA SOURCES

    The Covid Atlas team calculated LISA statistics using the pygeoda library. Data used to produce the calculations were confirmed cases and death data provided by USAFacts and 1 Point 3 Acres. The LISA value for each observation gives an indication of the extent of significant spatial clustering of similar values around that observation. For this application, counties are divided into five categories:

  • 1 High-high: area with high values and neighbored by areas with high values;
  • 2 Low-low: area with low values and neighbored by areas with low values;
  • 3 High-low: area with high values and neighbored by areas with low values;
  • 4 Low-high: area with low values and neighbored by areas with high values;
  • 5 Not significant

  • API PARAMETERS

  • state (required): str case insensitive state abbreviation
  • category (required): str "lisa"
  • type (optional): str “confirmed”, “death”, default as “death”
  • source (optional): str “usafacts” or “1p3a” case insensitive, default as “usafacts”
  • level (optional): str “state” or “county”, default as “county” (state only available for 1p3a)
  • start (optional): 8-digit integer start date in format as “20201005”, defaults to 7 days prior to today. Ranges from 20200122 to today
  • end (optional): 8-digit integer end date in format as “20201005”, defaults to today. Ranges from 20200122 to today

  • API QUERY EXAMPLE

    To get county-level death LISA values of Illinois using 1P3A data from September 1st, 2020 to October 1st, 2020, the query should be set as:
    https://api.theuscovidatlas.org/v1/lisa/?state=IL&category=lisa&start=20200901&end=20201001&source=1p3a&type=death&level=county


    POSSIBLE ERROR MESSAGES

  • Invalid State Input: if the field is missing or have typos
  • Invalid Date: if start date is before 20200122 or end date after today, or end date before start date
  • Invalid Type: if type input is other than “death” or “confirmed”
  • Invalid Level Type: if level input is other than “state” or “county”
  • Internal server error: try making a smaller query by querying a shorter date range


  • 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"}'