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.
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/.
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.
The R Quickstart notebook shows simple API calls and the breadth of data available in the C3.ai COVID-19 Data Lake.
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:
To edit the notebook and save your results locally, follow these steps.
Ensure that the following are installed on your computer:
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.
The Python Quickstart notebook shows simple API calls and the breadth of data available in the C3.ai COVID-19 Data Lake.
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:
To edit the notebook and save your results locally, follow these steps.
Ensure that the following are installed on your computer:
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.
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.
Run the Deep Dive notebook in your browser using Binder:
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.
Run the Deep Dive notebook in your browser using Binder:
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.
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.
Run the Deep Dive notebook in your browser using Binder:
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.
The R Deep Dive notebook explores economic indicator datasets and provides a starting point for detailed analysis into the economic impacts of the pandemic.
Run the Deep Dive notebook in your browser using Binder:
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.
What's new:
What's new:
Policy
Type to LocationPolicySummary for clarity. Query via Policy
Type is deprecated but still supported.What's new:
What's new:
What's new:
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:
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.
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.
The following APIs are currently suppported:
fetch
(for all C3.ai Types presented here)evalmetrics
(for OutbreakLocation)getprojectionhistory
(for OutbreakLocation)getarticlemetadata
(for BiblioEntry)getimageurls
(for Diagnosis)allversionsforpolicy
(for LocationPolicySummary)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):
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.
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 |
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:
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.
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:
fetch
API call to TherapeuticAsset.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. 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"