The COVID Tracking Project API changes covidtracking.com

Since the COVID Tracking Project started in March, we have been collating and publishing our data in the form of a single Google Sheet. Our API and website both used that sheet to publish all our core dataset. As our data collection effort has matured, we have built new tools to improve our publishing process. To that end, all of our API and website data are now based on an improved publishing system that no longer uses Google sheets.

However, people have been using our public sheets to import our data in ways that were never intended. We only support pulling data through our API. Supporting users whose apps broke because we changed the public sheet has had a significant impact on our support teams.

We encourage anyone who is using the public sheet for importing data to switch to our API, or import the CSV files available from our download page. As of November 28, the sheet will be static and no longer get new rows or columns, and on December 24, it will be taken offline.

The field totalTestResultsSource in the states/daily endpoints are now marked as deprecated, and will return null in two weeks.

Instead you should use the field totalTestResultsField in the states/info endpoint to find out what field is used to compute for totalTestResults.

The states info endpoint now have a new totalTestResultsField field that indicates which field we are pulling from for the state's totalTestResults value.

Per our announcement on US total test results, the sources of totalTestResults are now updated to match our new standards.

While the field posNeg has been marked as deprecated since April, we are now returning 0 for that field.

We are adding two new fields to the states info endpoints (/v1/states/info.json, and v1/states/info.csv):

• covidTrackingProjectPreferredTotalTestField - Locator field that explains which API fields The COVID Tracking Project prefers for each state’s “New tests” chart and on the state’s history page on our website. Selects from the following options in order of priority: totalTestEncountersViral, totalTestsViral, totalTestsPeopleViral, or—where those units are all missing a sufficient time series—totalTestResults.
• covidTrackingProjectPreferredTotalTestUnits - Label indicating which units The COVID Tracking Project prefers for each state’s “New tests” chart and on the state’s history page on our website. Selects from the following options in order of priority: test encounters, specimens, people, or—where those units are all missing a sufficient time series—negatives plus positives.

We have updated our API page to align all field definitions with those in our data definitions page.

On August 14 2020, we will be publishing twelve new API fields in the states endpoints for antigen, PCR, and antibody testing:

• Total Test Encounters (PCR) totalTestEncountersViral
• Total PCR Tests (People) totalTestsPeopleViral
• Total Antibody Tests totalTestsAntibody
• Positive Antibody Tests positiveTestsAntibody
• Negative Antibody Tests negativeTestsAntibody
• Total Antibody Tests (People) totalTestsPeopleAntibody
• Positive Antibody Tests (People) positiveTestsPeopleAntibody
• Negative Antibody Tests (People) negativeTestsPeopleAntibody
• Total Antigen Tests (People) totalTestsPeopleAntigen
• Positive Antigen Tests (People) positiveTestsPeopleAntigen
• Total Antigen Tests totalTestsAntigen
• Positive Antigen Tests positiveTestsAntigen

We are officially deprecating the old API URLs that have been redirecting since April 2 to our current API paths. Users of these old URLs should update their apps before October 15, when these paths will start returning 404 errors.

In order to serve the API more efficiently, we are moving the API service to a new domain: api.covidtracking.com. All of the relative URL paths like /v1/states/info.json are exactly the same and unchanged.

You can move your apps to the new domain now. On August 17, we will start redirecting all traffic from our old API endpoints at covidtracking.com/api to the new domain.

The COVID Tracking Project was founded in the early days of the COVID pandemic arriving in the US, and provided an API from day one. Since then, the data we collect has undergone many changes.

Because of this, we are working on a new version of the API. Please read the RFC and give a comment or thumbs up. We'd love to hear your feedback!