C3.ai COVID-19 API Documentation (5.2)

Download OpenAPI specification:Download

This is the reference documentation for C3.ai COVID-19 HTTP RESTful API. The API request and responses are in JSON.

Please contribute your questions, answers and insights to the C3.ai COVID-19 Grand Challenge community.

For support, please send email to: covid@c3.ai.

Citing the C3.ai COVID-19 Data Lake

If any publications or research results are derived in full or in part from the C3.ai COVID-19 Data Lake, please make sure to credit the C3.ai COVID-19 Data Lake by referencing the case study at https://c3.ai/customers/covid-19-data-lake/.

Quickstart Guide

Get started using the C3.ai COVID-19 Data Lake with R and Python notebooks. Use the online notebooks to easily try out the C3.ai COVID-19 Data Lake APIs in the cloud without any downloads or local environment setup. Use the downloadable notebooks to edit the code and save your results locally.

R Quickstart

The R Quickstart notebook shows simple API calls and the breadth of data available in the C3.ai COVID-19 Data Lake.

Online R Notebook

To try out the C3.ai COVID-19 Data Lake without any downloads or local environment setup, run the R Notebook in your browser using Binder:

Binder

Downloadable R Notebook

To edit the notebook and save your results locally, follow these steps.

Local environment setup

Ensure that the following are installed on your computer:

Download R Notebooks

Troubleshooting

While opening the R notebook (.Rmd file), if you see the error:

Unable to locate R binary by scanning standard locations.

then you probably did not install R from CRAN. Make sure you install both R Studio and R from CRAN.

Python Quickstart

The Python Quickstart notebook shows simple API calls and the breadth of data available in the C3.ai COVID-19 Data Lake.

Online Python Jupyter Notebook

To try out the C3.ai COVID-19 Data Lake without any downloads or local environment setup, run the Python Jupyter Notebook in your browser using Binder:

Binder

Downloadable Python Jupyter Notebook

To edit the notebook and save your results locally, follow these steps.

Local environment setup

Ensure that the following are installed on your computer:

Download Python Jupyter Notebooks

Troubleshooting

  • Ensure that you have Python 3 and not Python 2.7.

  • While opening the Jupyter Notebook, if you see the error:

    "Error loading notebook: An unknown error occurred while loading this notebook. This version can load notebook formats or earlier. See the server log for details.

    then you can probably resolve this by installing Python from Anaconda.

  • If you see error messages regarding pandas functions such as json_normalize or explode, make sure that you are using a pandas version of at least 1.0.0. See the pandas installation guide for installation instructions.

R and Python Deep Dive: Mobility and Case Counts

The R and Python Deep Dive notebooks explore datasets in mobility and case counts, and provide a starting point for detailed analysis into the relationships between these datasets.

Online R Notebook

Run the Deep Dive notebook in your browser using Binder:

Binder

Downloadable R Notebook

To edit the Deep Dive notebook and save your results locally, download the zip file containing R Notebooks and library functions. For additional details, see the R Quickstart section.

Online Python Notebook

Run the Deep Dive notebook in your browser using Binder:

Binder

Downloadable Python Notebook

To edit the Deep Dive notebook and save your results locally, download the zip file containing Python Notebooks and library functions. For additional details, see the Python Quickstart section.

Python Deep Dive: Clinical and Demographic Data

The Python Deep Dive notebook explores datasets in disease spread, state-level clinical data, and demographics data and provides a starting point for detailed analysis into the relationships between these datasets.

Online Python Notebook

Run the Deep Dive notebook in your browser using Binder:

Binder

Downloadable Python Notebook

To edit the Deep Dive notebook and save your results locally, download the zip file containing Python Notebooks and library functions. For additional details, see the Python Quickstart section.

R Deep Dive: Economic Indicators

The R Deep Dive notebook explores economic indicator datasets and provides a starting point for detailed analysis into the economic impacts of the pandemic.

Online R Notebook

Run the Deep Dive notebook in your browser using Binder:

Binder

Downloadable R Notebook

To edit the Deep Dive notebook and save your results locally, download the zip file containing R Notebooks and library functions. For additional details, see the R Quickstart section.

Release Notes

Release Notes for 5.2 (October 16, 2020)

Version 5.2 provides minor documentation and data availability updates.



Release Notes for 5.1 (September 14, 2020)

Version 5.1 provides updates to data availability and adds new metrics to the following data sources:
  • Opportunity Insights: Economic Tracker
  • Corona Data Scraper



Release Notes for 5.0 (August 11, 2020)

Version 5.0 adds eight new datasets to reach 40 total datasets in C3.ai COVID-19 Data Lake.

What's new:

  • Added eight new datasets (see C3.ai APIs for COVID-19 Unified Data):
    • US Bureau of Labor Statistics: County Unemployment Statistics
    • Realtor.com: Housing Indicators
    • Bureau of Economic Analysis: GDP and Economic Profile by County
    • Swayable and TapResearch: COVID-19 Tracker Poll
    • Opportunity Insights: Economic Tracker
    • Centers for Disease Control and Prevention: Weekly Updates by Select Demographic Characteristics
    • COVID Racial Data Tracker
    • US Census Bureau: County Population by Age, Sex, Race, and Hispanic Origin
  • Added two new C3.ai Types: LaborDetail and SurveyData.
  • Added two Deep Dive notebooks exploring economic data and medical data.
  • Revised Quickstart notebooks to include new C3.ai Types and APIs.
  • Revised document for clarity.

Release Notes for 4.0 (June 23, 2020)

Version 4.0 adds six new datasets.

What's new:

  • Added six new datasets (see C3.ai APIs for COVID-19 Unified Data):
    • The New York Times: All-Cause Mortality,
    • University of Oxford: Coronavirus Government Response Tracker,
    • US Census Bureau: International Census,
    • The World Bank: Finance Related Policy Responses to COVID-19,
    • PlaceIQ Exposure Indices,
    • IBM: Weather Company Data.
  • Added two new C3.ai Types: LocationExposure and PolicyDetail.
  • Added Deep Dive notebook exploring mobility data and case counts.
  • Revised Quickstart notebooks to include new C3.ai Types and APIs.
  • Renamed Policy Type to LocationPolicySummary for clarity. Query via Policy Type is deprecated but still supported.
  • Revised document for clarity.

Release Notes for 3.0 (June 2, 2020)

Version 3.0 adds four new datasets, dataset versioning, and online Quickstart notebooks.

What's new:

  • Added four new datasets (see C3.ai APIs for COVID-19 Unified Data):
    • Corona Data Scraper: COVID-19 Coronavirus Case Data
    • Centers for Disease Control and Prevention (CDC): VaxView
    • Cytel: Global Coronavirus COVID-19 Clinical Trial Tracker
    • Google: COVID-19 Community Mobility Reports
  • Added two new C3.ai Types: VaccineCoverage and ClinicalTrial
  • Added one new API: GetProjectionHistory
  • Revised Quickstart notebooks to include new C3.ai Types and APIs
  • Added online hosting for Quickstart notebooks
  • Revised document for clarity

Release Notes for 2.0 (May 15, 2020)

Version 2.0 doubles the number of datasets incorporated into the C3.ai COVID-19 Data Lake from 11 to 22.

What's new:

Release Notes for 1.0 (April 22, 2020)

Version 1.0 is the full release of the C3.ai COVID-19 API documentation.

What's new:

  • GetArticleMetadata now provides metadata for multiple article using "ids" rather than "id"
  • Added "Interpolated" JHU metrics for OutbreakLocation EvalMetrics API
  • Added additional clarifications and wording adjustments

Release Notes for 0.1

Version 0.1 is the initial release of the C3.ai COVID-19 API documentation.

Data from Multiple Sources

Using these APIs, you can pull together data from multiple COVID-19 data sources with a single API call. This is made possible by using C3.ai Types.

If you are new to the concept of a C3.ai Type, then it is easier to think of a C3.ai Type as an entity that holds the data. Using C3.ai Types makes it possible to programmatically interact with a unified, federated image of COVID-19 data.

On this page, entries such as OutbreakLocation, LineListRecord are the names of C3.ai Types. Each C3.ai Type holds data of a certain kind. For example:

  • OutbreakLocation stores location data such as countries, provinces, cities, where COVID-19 outbeaks are recorded, and
  • LineListRecord stores individual-level information such as symptoms, travel history, reported onset, and discharge status from laboratory-confirmed COVID-19 patients.

While each such C3.ai Type holds the data of a particular kind, you can use these APIs to connect up the data from multiple C3.ai Types. For example, you can join the data from two C3.ai Types, BiologicalAsset and Sequence. This can be accomplished by using the include option in the fetch API call.

The following is an example entity relationship diagram showing how C3.ai Types are connected. Not all fields are shown in the below diagram. Refer to the Fields table for a C3.ai Type for a full listing of the fields for that C3.ai Type. See, for example, LineListRecord.

C3.ai COVID-19 Data Model

Fetching from Multiple Sources

The include parameter is a powerful way to fetch data from multiple C3.ai Types. This parameter can also be used to fetch specific fields from a single C3.ai Type.

When you want to join data from two C3.ai Types, you make a fetch API call to one C3.ai Type, and use include in your request body to refer to the second C3.ai Type. The returned objects will contain fields and data from both the C3.ai Types.

See the section Using Include for detailed examples showing how to use include to combine data from multiple C3.ai Types.

C3.ai APIs for COVID-19 Unified Data

The following APIs are currently suppported:

Use POST requests to access these APIs.

NOTE: If you are new to the concept of RESTful API, this Postman Learning Center is a good place to start. All APIs described in this documentation can be verified using the Postman client.

The following table shows the APIs available for specific data sources (more data sources are being added):

Data Category Data Source C3.ai Types APIs
Daily Case Reports Johns Hopkins University: COVID-19 Data Repository (link to source data) OutbreakLocation evalmetrics
Daily Case Reports COVID Tracking Project (link to source data) OutbreakLocation evalmetrics
Daily Case Reports World Health Organization: Situation Reports OutbreakLocation evalmetrics
Daily Case Reports The New York Times: Coronavirus (Covid-19) Data in the United States OutbreakLocation evalmetrics
Daily Case Reports European Centre for Disease Prevention and Control: Situation Update Worldwide (link to source data) OutbreakLocation evalmetrics
Daily Case Reports University of Washington's Institute for Health Metrics and Evaluation: COVID-19 Projections (updated through June 13, 2020) OutbreakLocation evalmetrics, getprojectionhistory
Daily Case Reports Data Science for COVID-19: South Korea Dataset OutbreakLocation, LineListRecord, PatientRoute fetch, evalmetrics
Daily Case Reports Dipartimento della Protezione Civile – Emergenza Coronavirus: La Risposta Nazionale OutbreakLocation evalmetrics
Daily Case Reports COVID-19 India OutbreakLocation, LineListRecord fetch, evalmetrics
Daily Case Reports Corona Data Scraper: COVID-19 Coronavirus Case Data OutbreakLocation evalmetrics
Daily Case Reports COVID Racial Data Tracker OutbreakLocation evalmetrics
Case Reports The New York Times: All-Cause Mortality OutbreakLocation evalmetrics
Case Reports Centers for Disease Control and Prevention: Weekly Updates by Select Demographic Characteristics OutbreakLocation evalmetrics
Epidemiology Line Lists University of Washington's Institute for Health Metrics and Evaluation: nCoV-2019 Data (updated through April 30, 2020) LineListRecord fetch
Epidemiology Line Lists Laboratory for the Modeling of Biological Socio-technical Systems (MOBS Lab): Situation Report (link to source data) LineListRecord fetch
Genome Sequences National Center for Biotechnology Information Virus Database BiologicalAsset, Sequence, Subsequence, AminoAcidLookup, NucleotideLookup fetch
Journals Allen Institute for AI: COVID-19 Open Research Dataset (CORD-19) (updated through April 8, 2020) BiblioEntry fetch, getarticlemetadata
Clinical Milken Institute: COVID-19 Treatment and Vaccine Tracker (link to source data) TherapeuticAsset fetch
Clinical World Health Organization: COVID-19 Research & Development (link to source data) TherapeuticAsset fetch
Clinical The University of Montreal: COVID-19 Image Data Collection Diagnosis, DiagnosisDetail fetch, getimageurls
Clinical Carbon Health & Braid Health: COVID-19 Clinical Data Repository Diagnosis, DiagnosisDetail fetch
Clinical Definitive Healthcare: Hospital ICU Beds Hospital fetch
Clinical Centers for Disease Control and Prevention (CDC): VaxView VaccineCoverage fetch
Clinical Cytel: Global Coronavirus COVID-19 Clinical Trial Tracker ClinicalTrial fetch
Policy Kaiser Family Foundation: Social Distancing Policies LocationPolicySummary fetch, allversionsforpolicy
Policy University of Oxford: Coronavirus Government Response Tracker PolicyDetail fetch, evalmetrics
Policy The World Bank: Finance Related Policy Responses to COVID-19 PolicyDetail fetch
Mobility Apple: COVID-19 Mobility Trends OutbreakLocation evalmetrics
Mobility Google: COVID-19 Community Mobility Reports OutbreakLocation evalmetrics
Mobility PlaceIQ Exposure Indices OutbreakLocation, LocationExposure getlocationexposures, evalmetrics
Demographics US Census Bureau: Demographic Estimates OutbreakLocation, PopulationData fetch, evalmetrics
Demographics US Census Bureau: International Census PopulationData fetch, evalmetrics
Demographics The World Bank: Global Health Statistics OutbreakLocation, PopulationData fetch
Demographics US Census Bureau: County Population by Age, Sex, Race, and Hispanic Origin OutbreakLocation evalmetrics
Economic US Bureau of Labor Statistics: County Unemployment Statistics OutbreakLocation, LaborDetail fetch, evalmetrics
Economic Realtors.com: Housing Indicators OutbreakLocation evalmetrics
Economic Bureau of Economic Analysis: GDP and Economic Profile by County OutbreakLocation evalmetrics
Economic Opportunity Insights: Economic Tracker OutbreakLocation evalmetrics
Public Surveys Swayable and TapResearch: COVID-19 Tracker Poll SurveyData fetch
Environmental IBM: Weather Company Data OutbreakLocation evalmetrics

Using C3.ai APIs

POST Requests

All C3.ai APIs described in this documentation must be accessed using POST requests.

If you receive the following error:

{
  "message": "Missing Authentication Token"
}

then you are probably using GET or another request, and you should instead use POST. No authentication token is required to access the APIs.

Required Headers

All C3.ai APIs described in this documentation must be used with the following header settings:

Headers Setting
Accept application/json
Content-Type application/json

Using Fetch

The request JSON for the fetch API should be used with the filter key. This filter key can be used in the fetch call to select any combination of the fields in the data. A few examples follow:

IMPORTANT: For a list of fields available for a C3.ai Type, refer to the fields section of that C3.ai Type in this document.

To fetch the data that match the specific values of the id field of the data:

  {
    "spec" : {"filter": 'id == "Afghanistan"'}
  }

A few other examples:

  {
    "spec" : {"filter": 'id == "Afghanistan" && age == 45'}
  }

or,

  {  // See BiologicalAsset
    "spec": {
        "filter": "isolationSource == 'feces' && location == 'Japan'",
        "limit": -1
    }
  }

or, using a "contains(field, "string")" format:

  { // See LineListRecord
    "spec": {
        "filter": "gender == 'male' && lineListSource == 'OPEN' && age <= 20 && contains(relevantTravelHistoryLocation,'Wuhan')"
   }
  }

The fetch API returns two main kinds of information in its response:

  • The data from the C3.ai Type, fetched as an array of the objects.
  • Metadata, or data describing data, such as:
    • The number of objects fetched.
    • Number of rows of information.
    • An indicator if more data exists in the C3.ai Type that was not returned.
  • See the section Limits for the number of entries returned per fetch API call.

For full details on request and response JSON, see the several examples provided in the fetch API for all the C3.ai Types in this documentation.

Using Include

In a C3.ai Type, the data type of a field can be a C3.ai Type. For example, the field links in TherapeuticAsset is of the type ExternalLink. This is how these two C3.ai Types are connected.

For example, to join data from these two connected C3.ai Types, TherapeuticAsset and ExternalLink, use the include parameter as follows:

  • Make a fetch API call to TherapeuticAsset.
  • The field links in TherapeuticAsset is of ExternalLink Type. Using the dot notation on the links field, you can access any field in the ExternalLink. For example, specifying links.url will resolve into ExternalLink.url, which will obtain the url field data from the ExternalLink.
  • Notice that we have not issued a fetch call to ExternalLink. See the full fetch example, including the response objects, below.

Example 1: Join data from TherapeuticAsset and ExternalLink (click arrow to open)

Example 1: Join data from TherapeuticAsset and ExternalLink

HTTP URL: https://api.c3.ai/covid/api/1/therapeuticasset/fetch

Request JSON:

  {
    "spec": {
      "include": "productType, description, origin, links.url",
      "filter": "origin =='Milken'",
      "limit" : 3
    }
  }



Response JSON:

  {
    "objs": [
      {
          "productType": "TAK-888, antibodies from recovered COVID-19 patients",
          "origin": "Milken",
          "links": [
              {
                  "url": "https://www.wsj.com/articles/drugmaker-takeda-is-working-on-coronavirus-drug-11583301660?mod=article_inline",
                  "therapeuticAsset": {
                      "id": "milkentreatment_001"
                  },
                  "id": "1919184b-460e-4725-8c2c-0ab225a58c1c",
                  "meta": {
                      "fetchInclude": "[id,url,therapeuticAsset,version]",
                      "fetchType": "ExternalLink"
                  },
                  "version": 1
              },
              {
                  "url": "https://phrma.org/coronavirus",
                  "therapeuticAsset": {
                      "id": "milkentreatment_001"
                  },
                  "id": "fdc646d7-eada-47af-b782-89216996b7ec",
                  "meta": {
                      "fetchInclude": "[id,url,therapeuticAsset,version]",
                      "fetchType": "ExternalLink"
                  },
                  "version": 1
              }
            ],
            "id": "milkentreatment_001",
            "meta": {
                "fetchInclude": "[productType,description,origin,{links:[id,url]},id,version]",
                "fetchType": "TherapeuticAsset"
            },
            "version": 1
        },
        {
            "productType": "Antibodies from mice, REGN3048-3051, against the spike protein",
            "origin": "Milken",
            "links": [
                {
                    "url": "https://www.statnews.com/2020/03/19/an-updated-guide-to-the-coronavirus-drugs-and-vaccines-in-development/",
                    "therapeuticAsset": {
                        "id": "milkentreatment_002"
                    },
                    "id": "154217eb-08fc-4ba8-aeb2-6ac8d93710a1",
                    "meta": {
                        "fetchInclude": "[id,url,therapeuticAsset,version]",
                        "fetchType": "ExternalLink"
                    },
                    "version": 1
                },
                {
                    "url": "https://www.bnnbloomberg.ca/gilead-s-drug-leads-global-race-to-find-coronavirus-treatment-1.1395231",
                    "therapeuticAsset": {
                        "id": "milkentreatment_002"
                    },
                    "id": "2984da95-4e96-4e27-9365-0b17ee04c091",
                    "meta": {
                        "fetchInclude": "[id,url,therapeuticAsset,version]",
                        "fetchType": "ExternalLink"
                    },
                    "version": 1
                },
                {
                    "url": "https://uk.reuters.com/article/uk-china-health-treatments-factbox/factbox-global-efforts-to-develop-vaccines-drugs-to-fight-the-coronavirus-idUKKBN20D2MD?rpc=401&",
                    "therapeuticAsset": {
                        "id": "milkentreatment_002"
                    },
                    "id": "61d19389-fe0b-4e7a-84dc-07dbca2d20c3",
                    "meta": {
                        "fetchInclude": "[id,url,therapeuticAsset,version]",
                        "fetchType": "ExternalLink"
                    },
                    "version": 1
                },
                {
                    "url": "https://www.marketwatch.com/story/these-nine-companies-are-working-on-coronavirus-treatments-or-vaccines-heres-where-things-stand-2020-03-06",
                    "therapeuticAsset": {
                        "id": "milkentreatment_002"
                    },
                    "id": "812e1849-5403-4940-8d46-0d372dc94bbd",
                    "meta": {
                        "fetchInclude": "[id,url,therapeuticAsset,version]",
                        "fetchType": "ExternalLink"
                    },
                    "version": 1
                },
                {
                    "url": "https://www.fiercebiotech.com/research/fast-moving-regeneron-eyes-summer-clinical-trial-for-covid-19-antibody-cocktail-therapy",
                    "therapeuticAsset": {
                        "id": "milkentreatment_002"
                    },
                    "id": "b583ddb9-68e3-4896-b8b8-bb4d283c5b79",
                    "meta": {
                        "fetchInclude": "[id,url,therapeuticAsset,version]",
                        "fetchType": "ExternalLink"
                    },
                    "version": 1
                },
                {
                    "url": "https://www.fiercepharma.com/pharma/regeneron-s-r-d-war-room-sleepless-nights-and-esprit-de-corps-hunt-for-covid-19-therapy?mkt_tok=eyJpIjoiTUROaFpUYzJOVE14TjJNMSIsInQiOiJRT0YxZVBYWHJQQVlNYzFcL3JUSUdac1Zqa0VXMGk2MHpQS3kxZXdmaWhyQlJ2MWFuR1wvb0FGb1pDWExGQ0pYQzYrN1dGMW9BRlFMUlo2WE1XOVZQN2pxaE1MUUFQSHFlYlVCc0xKdmJoTm1xdHdcL0hPeXJKS0llODJTTGR5aHZjQ2Z3ZE1KU1BFZ013R0JyeU9qTkxSZmc9PSJ9&mrkid=72869502",
                    "therapeuticAsset": {
                        "id": "milkentreatment_002"
                    },
                    "id": "f09ff2a3-2ca0-48cd-b373-6bd0a396d221",
                    "meta": {
                        "fetchInclude": "[id,url,therapeuticAsset,version]",
                        "fetchType": "ExternalLink"
                    },
                    "version": 1
                }
            ],
            "id": "milkentreatment_002",
            "meta": {
                "fetchInclude": "[productType,description,origin,{links:[id,url]},id,version]",
                "fetchType": "TherapeuticAsset"
            },
            "version": 1
        },
        {
            "productType": "Antibodies from recovered COVID-19 patients",
            "origin": "Milken"