COVID-19

Data Resources

This page contains resources for navigating the COVID-19 Nursing Home Data Report, Accessing the Data, and API resources.


Use the Map to View Residents Cases and Deaths by State

This maps display the "Total Residents Confirmed COVID-19 Cases by State" and "Total Residents COVID-19 Deaths by State. You can hover over a state with your mouse to see the data for each state.

Use the Map to Search for a Nursing Home

You can also use a map to search for a particular nursing home. Fill out the name and address of the nursing home in the search bar. This will zoom on a point where you then click on the location to show additional information on the selected nursing home.


The underlying data for the COVID-19 Nursing Home Data report and data dictionary can be found here. From this page, the dataset can be downloaded in a number of different formats.

Exporting the Data

To export the dataset, first navigate to the dataset page. There are several options at the top of the dataset. To download the data, choose the Export button.
There are several export options to choose from, as the data contains geographical information, the dataset can be downloaded in both standard and geospatial formats.

Access via OData 

Use OData to open the dataset in tools like Excel or Tableau. This provides a direct connection to the data that can be refreshed on-demand within the connected application.
Connect to either the OData V2 or V4 endpoints by choosing the ellipses on the dataset page.


Access API Endpoint

The COVID-19 Nursing Home dataset can also be accessed by the Socrata Open Data (SODA) API. The SODA API provides programmatic access to this dataset including the ability to filter, query, and aggregate data.
The API endpoint for the dataset can also be found on the dataset page by choosing the API button. This button will display the API endpoint of the dataset which is also listed below:

Dataset API Docs

The COVID-19 Nursing Home dataset has API Docs specific to the dataset. This documentation will contain information on the dataset including dataset metadata, column data types, and code snippets.

Developer Resources

The Socrata Developer Portal contains additional documents on querying data and interacting with different data types as well as Libraries and SDKs for popular programming languages.

Application Tokens

The Socrata API uses application tokens to associate API calls with specific applications and not IP addresses. Setting up and using an app token will allow API calls to avoid being throttled. While not required, it's always advised to use an application token when connecting to data from the API. 
In order to create an app token, you will first need to sign up for a Socrata account and log in to your profile.
Once logged in to your account, you can generate an app token by choosing Edit Profile > Developer Settings on your profile page.
Please note that as this data is public no additional authentication is required.

Paging through Data

The SODA API returns a default of 1000 rows of data when querying the API endpoint. In order to access all records in the dataset, you can use the $limit and $offset query parameters. 
The $limit parameter sets the number of results to return from the API call. There is no upper limit to the value that can be used with the limit parameter. For example, the following API query would retrieve 2000 records instead of the default 1000:
https://data.cms.gov/resource/s2uc-8wxp.json?$limit=2000
The $offset parameter will define the starting point of where you would like to retrieve the data. By using the limit and offset parameters in conjunction to page through the data. The three below API calls would be an example of paging through the data 1000 records at a time:
https://data.cms.gov/resource/s2uc-8wxp.json?$limit=1000&$offset=0
https://data.cms.gov/resource/s2uc-8wxp.json?$limit=1000&$offset=1000
https://data.cms.gov/resource/s2uc-8wxp.json?$limit=1000&$offset=2000
Pro Tip: The order of the results of a query are not implicitly ordered, so if you're paging, make sure you provide an $order clause or at a minimum $order=:id. This will guarantee that the order of your results will be stable as you page through the dataset.

Questions?

For questions about the data, please contact: NH_COVID_Data@cms.hhs.gov
For questions on how to use this site, please contact: socrata-support@tylertech.com