Introduction

The Covid Tracking Project API (CTP API) allows users to access data in real time relating to positive Covid-19 related cases in the United States. The API is organized using a REST architectural style, and uses an HTTP GET request for each available endpoint. Each endpoint returns a standardized HTTP response code, along with a JSON-encoded object as a response.

Base URL: https://api.covidtracking.com/

Access to Legacy Version

Notice: The legacy version (v1) is depreciated and will be removed on May 21, 2021. It is recommended that users update their applications to use the new v2 API endpoints.

You can access version 2 (recommended) here:
https://api.covidtracking.com/v2

To access the legacy API:
https://api.covidtracking.com/v1

Authorization (Legacy)

Notice: v2 of the API no longer requires authorization. It is recommended to update your applications to use the new v2 API endpoints. This section is left here for archival purposes.

The CTP API uses OAuth2 in order to authorize and authenticate API requests. To make a request to the API, you must acquire a client ID, which you can find here: https://covidtracking.com/data/api/authorize

The login screen will ask for your username and password. Once logged in, the API will redirect you to a page that reveals your client ID. You must append the client ID to each API request that you make.

The client ID to append to the end of your URL will look like this:
client_id={CLIENT_ID}

An example API request would look like this:
api.covidtracking.com/v1/states?client_id=16724286

Getting Started

To access all national data available in reverse chronological order, send an HTTP GET request to this endpoint:
https://api.covidtracking.com/v2/us/daily.json

You can use a tool such as curl in order to send an HTTP request to this resource. The curl request would look like this:

1
curl https://api.covidtracking.com/v2/us/daily.json

An HTTP status of 200 indicates that your request was successful.

Interpreting the JSON Response

The API will return a JSON encoded response that’s simplified to look like this:

1
2
3
4
5
{
    "links":     {…},
    "meta":	 {…},
    "data":	 […]
}

As you can see, the API returns three top level resources:

  • [Object] links: contains information about the accessed endpoint.
  • [Object] meta: contains information including build time and parameters used to generate the response.
  • [Array] data: contains the national data on covid reports.

What we are most interested in is the information contained within the data array. Open the data array. You will see a list of objects contained inside of it. Each object in this array represents a testing sample from a specific date, along with information about the case results, testing, and outcomes for each date. The objects in the array are in reverse chronological order, starting with the latest date as index 0, and the first day of testing as the last. 

1
2
3
4
5
6
7
{
    "date":	   "2020-09-01",
    "states":	   56,
    "cases":	   {…},
    "testing":	   {…},
    "outcomes":    {…}
}

As you can see in our current sample, the date is September 1st, 2020, and there were 56 states sampled from on this date. Open the cases object to see more information about the positive test cases found on this date.

1
2
3
4
5
6
7
8
9
10
cases {
    total {
        "value": 28296840,
        "calculated": {
            "population_percent": 8.5542,
            "change_from_prior_day": 71245,
            "seven_day_change_percent": 1.7
        }
    }
}

Here, you can see the total amount of positive cases for this date was 28,296,840. The cases object also provides some calculated values, such as the amount of positive cases found on that date contributing to the total value.

For more information on the cases object and its field definitions, you can reference the Resources section of this guide.

Endpoints

The Covid Tracking Project API is organized into two main categories:

  • National Data
  • State & Territories Data

National Data

Historic US Values

Retrieves all national positive cases in reverse chronological order.

URL path: /v2/us/daily.json
HTTP Methods: GET
Example: https://api.covidtracking.com/v2/us/daily.json

Single Day of Data

Retrieves a single day of positive cases on a national level.

URL path: /v2/us/daily/{date-iso-format}.json
HTTP Methods: GET
Arguments:

  • date-iso-format: The date to retrieve data from. Follows the format yyyy-mm-dd.

Example: https://api.covidtracking.com/v2/us/daily/2021-01-02.json

States and Territorial Data

Historic Data for a State or Territory

Retrieves all positive cases within a state in reverse chronological order.

URL path: /v2/states/{state-code}/daily.json
HTTP Methods: GET
Arguments:

  • state-code: The two-character acronym representing the state or territory. Refer to the State Codes section for reference.

Example: https://api.covidtracking.com/v2/states/ca/daily.json

Single Day of Data for a State or Territory

Retrieves a single date of data on a state level.

URL path: /v2/states/{state-code}/{date-iso-format}.json
HTTP Methods: GET
Arguments:

  • state-code: The two-character acronym representing the state or territory. Refer to the State Codes section for reference.
  • date-iso-format: The date to retrieve data from. Follows the format yyyy-mm-dd.

Example: https://api.covidtracking.com/v2/states/ca/2021-01-10.json

Resources

The links object contains information on the endpoint used to access the API. The API will generate and attach a links object to every API request made.

1
2
3
"links": {
    "self": "https://api.covidtracking.com/us/daily"
}

[string] links: The endpoint used to access the API.

Meta

The meta object contains information on the current build metadata. The API will generate and attach a metadata object to every API request made.

1
2
3
4
5
6
"meta": {
    "build_time": "2021-06-01T07:03:25.055Z",
    "license": "CC-BY-4.0",
    "version": "2.0-beta",
    "field_definitions": [...]
}

[string] build_time: The date and time that the API was last built.
[string] license: The license that the current API version is registered under.
[string] version: The current version of the API.
[array] field_definitions: An array containing the field names used within the API.

Cases

The cases object contains information on the amount of positive cases found.

1
2
3
4
5
6
7
8
9
10
"cases": {
    total {
    "value": 28296840,
        "calculated": {
            "population_percent": 8.5542,
            "change_from_prior_day": 71245,
            "seven_day_change_percent": 1.7
        }
    }
}

[int] value: The total amount of positive cases found.
[float] population_percent: The percentage that the value represents over the total population living in the US.
[int] change_from_prior_day: The difference between the amount of new cases found from yesterday.
[float] seven_day_change_percent: The percentage of change calculated between a seven day period.

Testing

The testing object represents information on the total amount of tests administered.

1
2
3
4
5
6
7
8
9
10
"testing": {
    total {
        "value": 363825123,
        "calculated": {
            "population_percent": 109.9858,
            "change_from_prior_day": 1170059,
            "seven_day_change_percent": 2.8
        }
    }
}

[int] value: The total amount of Covid tests administered.
[float] population_percent: The percentage that the value represents over the total population living in the US.
[int] change_from_prior_day: The difference between the amount of tests cases reported from yesterday.
[float] seven_day_change_percent: The percentage of change calculated between a seven day period.

Outcomes

The outcomes object contains information on the consequences related to Covid-19, including the number of people who are:

  • Hospitalized
  • Dead
1
2
3
4
"outcomes": {
    "hospitalized": {...},
    "death": {...}
}

Please refer to Hospitalized and Death in the resources section for more information on each object.

Hospitalized

The hospitalized object contains information on the total number those who are hospitalized due to Covid-19, including cases of those who are:

  • in ICU
  • on a ventilator
1
2
3
4
5
6
7
8
9
10
11
12
13
"hospitalized": {
    "currently": {
    "value": 40199,
    "calculated": {
        "population_percent": 0.0122,
        "change_from_prior_day": -1202,
        "seven_day_change_percent": -15.1,
        "seven_day_average": 43843
    }
},
"in_icu": {...},
"on_ventilator": {...}
}

[int] value: The total amount of people hospitalized due to Covid-19.
[float] population_percent: The percentage that the value represents over the total population living in the US.
[int] change_from_prior_day: The difference between the amount of people hospitalized reported from yesterday.
[float] seven_day_change_percent: The percentage of change calculated between a seven day period.
[int] seven_day_change_percent: The average calculated within a seven day period.

Please refer to In ICU and On Ventilator in the resources section for more information on each object.

In ICU

The in_icu object contains all the information on those who are hospitalized and put into Intensive Care Unit due to Covid-19.

1
2
3
4
5
6
7
8
9
10
11
"in_icu": {
    "currently": {
        "value": 8134,
        "calculated": {
            "population_percent": 0.0025,
            "change_from_prior_day": -275,
            "seven_day_change_percent": -17,
            "seven_day_average": 8938
        }
    }
}

[int] value: The total amount of people who were put into ICU due to Covid-19.
[float] population_percent: The percentage that the value represents over the total population living in the US.
[int] change_from_prior_day: The difference between amount of people put into ICU reported from yesterday.
[float] seven_day_change_percent: The percentage of change calculated between a seven day period.
[int] seven_day_change_percent: The average calculated within a seven day period.

On Ventilator

The on_ventilator object contains the all information on those who were hospitalized and put on a ventilator due to Covid-19.

1
2
3
4
5
6
7
8
9
10
11
"on_ventilator": {
    "currently": {
        "value": 2802,
        "calculated": {
            "population_percent": 0.0008,
            "change_from_prior_day": -9,
            "seven_day_change_percent": -13.7,
            "seven_day_average": 2987
        }
    }
}

[int] value: The total amount of people put on a vnetilator due to Covid-19.
[float] population_percent: The percentage that the value represents over the total population living in the US.
[int] change_from_prior_day: The amount of people who are reported to be on ventilation from yesterday.
[float] seven_day_change_percent: The percentage of change calculated between a seven day period.
[int] seven_day_change_percent: The average calculated within a seven day period.

Death

The death object contains information on all those who died due to Covid-19.

1
2
3
4
5
6
7
8
9
10
11
"death": {
    "total": {
        "value": 515151,
        "calculated": {
            "population_percent": 0.1557,
            "change_from_prior_day": 842,
            "seven_day_change_percent": 2.4,
            "seven_day_average": 510267
        }
    }
}

[int] value: The total amount of people who died due to Covid-19.
[float] population_percent: The percentage that the value represents over the total population living in the US.
[int] change_from_prior_day: The difference between the amount of people who died from yesterday.
[float] seven_day_change_percent: The percentage of change calculated between a seven day period.
[int] seven_day_change_percent: The average calculated within a seven day period.

State Codes