IMPORTANT: Please note that the information on this page is no longer up-to-date. COVID-19 and its symptomatology have now been incorporated into Infermedica's main Medical Knowledge Base. To get the most recent medical information, please use our API.
As a company operating in a digital health space, we’ve mobilized all our resources to respond to the threat of SARS-CoV-2 virus. The result of our work is a new set of API endpoints dedicated solely to COVID-19 risk assessment. Our goal to help all developers out there to enable their apps and websites with a reliable COVID-19 patient screening protocol.
We hope that by working together we can play our part in containing and eventually lessening the impact of the virus on public health and economies.
As the COVID-19 pandemic is progressing, the world's knowledge about the Coronavirus keeps expanding. This has brought the World Health Organization to update its guidelines for patient screening and the diagnostic criteria of COVID-19. To keep our COVID-19 Risk Assessment tool up to date, we decided to release a new version with the adjusted flow and improved triage recommendations. What has changed?
call_doctor, recommended for patients with serious conditions but not related to COVID-19./locations endpoint for listing all countries./search endpoint - search for visited countries (find country codes by full country name)./symptoms and /risk_factors endpoints listing all available concepts in the COVID-19 API medical base.Infermedica is devoted to ensuring the highest quality of the medical content that we share with our users. Our goal is to provide the maximum level of trust and transparency regarding our medical content creation process and sources used.
The prescreening logic provided via COVID-19 endpoints is curated by our team of doctors, and strictly based on WHO protocols and daily transmission reports. Our doctors are continuously reviewing WHO guidelines and updating the prescreening questionnaire on a daily basis.
You can always review the current version of the flow chart used by our API. We recommend to open this chart in diagrams.net.
Please keep in mind that, unlike our general symptom checking endpoints, there is no AI and no machine learning involved in COVID-19 endpoints. Our goal is to strictly follow the golden standard established by WHO.
Recommendations on what to do next are solely based on a combination of WHO and CDC:
If you haven’t already, please sign up to Infermedica API.
The COVID-19 version of the Infermedica API is available at https://api.infermedica.com/covid19
It is a standard web service that accepts GET and POST requests. All responses (including error messages) use the JSON format. POST requests also take JSON inputs (make sure you include the header `Content-Type: application/json`).
Please refer to the Basics section for additional information.
Infermedica API uses a custom authentication mechanism. Each of your requests must include two non-standard HTTP headers: App-Id and App-Key. These parameters correspond to your unique application ID and the key you created when you signed up to our Developer Portal. You can manage your credentials on the Apps page.
An example of a request could look like this (please remember to replace XXX...X with your credentials):
curl "https://api.infermedica.com/covid19/diagnosis" \
-X "POST" \
-H "App-Id: XXXXXXXX" -H "App-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-H "Content-Type: application/json" -d '{
"sex": "male",
"age": 30,
"evidence": []
}'
Below you can find a list of currently supported COVID-19 endpoints:
https://api.infermedica.com/covid19/diagnosis – POST Handles the prescreening questionnaire.https://api.infermedica.com/covid19/triage – POST Returns information on how provided symptoms are classified and what to do next.https://api.infermedica.com/covid19/search – GET Search countries.https://api.infermedica.com/covid19/symptoms – GET List all symptoms.https://api.infermedica.com/covid19/risk_factors – GET List all risk factors.https://api.infermedica.com/covid19/locations – GET List all countries.COVID-19 endpoints use different concept IDs than the main Infermedica API. Make sure you don’t use Infermedica API concepts in requests to the COVID-19 API.
We are going to disable the API v4 on May 31, 2021. If you app is running on the API v4, please upgrade your API version to take advantage of new features.
In order to allow smooth transitions to new API versions in case of major changes (e.g. new triage levels), we have enabled API versioning.
Use an optional HTTP header called Version to select the API version. Version names use the following naming convention: v4, v5 etc.
curl "https://api.infermedica.com/covid19/locations" \
-X "GET" \
-H "App-Id: XXXXXXXX" -H "App-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-H "Model: infermedica-en"
-H "Version: v5"
We strongly recommend to keeping up-to-date with latest releases. It’s best to keep the default API version and use Version for testing mode only. Each old version will be disabled 4 weeks after its release.
Currently supported versions:
Please note that /diagnosis is just a name of our API endpoint. Obviously, our tool is not meant to provide any sort of clinical diagnosis nor replace any medical advice.
The most important part of our API is the /diagnosis endpoint, which accepts POST requests. Apart from sex and age, it requires a list of observed evidence (responses to questions, symptoms, and risk factors). The list of evidence can be empty at the beginning.
Let's assume we have a male patient, aged 30, and with no observations yet. Such a case can be represented with the following JSON object:
{
"sex": "male",
"age": 30,
"evidence": []
}Your first request to the API could look like this:
curl "https://api.infermedica.com/covid19/diagnosis" \
-X "POST" \
-H "App-Id: XXXXXXXX" -H "App-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-H "Content-Type: application/json" -d '{
"sex": "male",
"age": 30,
"evidence": []
}'
The response returned from /diagnosis will contain several sections:
extras - usually empty, but may contain additional (or experimental) attributes,explanation - a short optional description of the question which can be displayed as a hint to the user.{
"question": {...},
"should_stop": true / false
"conditions": [],
"extras": {},
"explanation": "..."
}The question attribute represents the next diagnostic question that can be presented to the user. Questions are follow-ups to already reported observations and can be used to build conversation-like interfaces (symptom checkers, chatbots, etc.) that resemble the way doctors interview their patients.
In our example, the API would generate a multiple-choice question on a few risk factors.
{
"conditions": [],
"extras": {},
"question": {
"explanation": null,
"extras": {},
"items": [
{
"choices": [
{
"id": "present",
"label": "Yes"
},
{
"id": "absent",
"label": "No"
}
],
"explanation": "Chronic lung diseases are disorders that affect the lung and other parts of the respiratory system. Conditions: Chronic Obstructive Pulmonary Disease, moderate and severe Asthma, and other lung conditions.",
"id": "p_16",
"name": "Diagnosed chronic lung disease"
},
{
"choices": [
{
"id": "present",
"label": "Yes"
},
{
"id": "absent",
"label": "No"
}
],
"explanation": "Congestive heart failure is a chronic progressive condition where your heart is unable to pump blood efficiently due to conditions such as coronary artery disease and hypertension.",
"id": "p_17",
"name": "History of heart failure"
},
{
"choices": [
{
"id": "present",
"label": "Yes"
},
{
"id": "absent",
"label": "No"
}
],
"explanation": null,
"id": "p_18",
"name": "Current cancer"
},
{
"choices": [
{
"id": "present",
"label": "Yes"
},
{
"id": "absent",
"label": "No"
}
],
"explanation": "A weakened immune system can be caused by many factors, e.g., cancer treatment, bone marrow or organ transplantation, poorly controlled HIV/AIDS, prolonged use of immunosuppressant drugs such as corticosteroids or drugs used for rheumatoid arthritis, and some congenital diseases.",
"id": "p_19",
"name": "Weakened immune system"
},
{
"choices": [
{
"id": "present",
"label": "Yes"
},
{
"id": "absent",
"label": "No"
}
],
"explanation": "A long-term liver disease due to alcoholism, infections or congenital diseases, leading to loss of function, cirrhosis and other complications.",
"id": "p_20",
"name": "History of chronic liver disease"
},
{
"choices": [
{
"id": "present",
"label": "Yes"
},
{
"id": "absent",
"label": "No"
}
],
"explanation": "End-stage kidney disease is a condition where kidney function is greatly reduced.",
"id": "p_21",
"name": "History of kidney failure"
},
{
"choices": [
{
"id": "present",
"label": "Yes"
},
{
"id": "absent",
"label": "No"
}
],
"explanation": null,
"id": "p_22",
"name": "Long-term stay at a care facility or nursing home"
}
],
"text": "Please check all statements that apply to you",
"type": "group_multiple"
},
"should_stop": false
}Please note that question has a null value if should_stop is true.
There are 3 types of questions, each requiring slightly different handling.
The single type represents simple Yes/No questions, e.g.
"question": {
"type": "single",
"text": "Are you breathing very fast?",
"items": [
{
"id": "s_13",
"name": "Accelerated breathing",
"choices": [
{
"id": "present",
"label": "Yes"
},
{
"id": "absent",
"label": "No"
}
]
}
],
"extras": {}
}When the user answers a question of the single type, exactly one object with the id of the item and selected choice_id should be added to the evidence list of the next request, e.g.
{
...
"evidence": [
...
{"id": "s_13", "choice_id": "present"}
]
}The group_single type represents questions about a group of related but mutually exclusive symptoms, of which the patient should choose exactly one, e.g.
"question": {
"type": "group_single",
"text": "How high is your fever?",
"items": [
{
"id": "s_3",
"name": "Between 37.5°C and 40°C (99.5°F and 104°F)",
"choices": [
{
"id": "present",
"label": "Yes"
},
{
"id": "absent",
"label": "No"
}
]
},
{
"id": "s_4",
"name": "Greater than 40°C (104°F)",
"choices": [
{
"id": "present",
"label": "Yes"
},
{
"id": "absent",
"label": "No"
}
]
},
{
"id": "s_5",
"name": "I haven’t measured",
"choices": [
{
"id": "present",
"label": "Yes"
},
{
"id": "absent",
"label": "No"
}
]
}
],
"extras": {}
}For a question of the group_single type, exactly one object with the id of the selected item and choice_id set to present should be added to the evidence list of the next request, with all other items omitted, e.g.
{
...
"evidence": [
...
{"id": "s_3", "choice_id": "present"}
]
}The group_multiple type represents questions about a group of related symptoms where any number of them can be selected, e.g.
"question": {
"type": "group_multiple",
"text": "Please select if you've got any of the following symptoms:",
"items": [
{
"id": "s_0",
"name": "Fever",
"choices": [
{
"id": "present",
"label": "Yes"
},
{
"id": "absent",
"label": "No"
}
]
},
{
"id": "s_1",
"name": "Cough",
"choices": [
{
"id": "present",
"label": "Yes"
},
{
"id": "absent",
"label": "No"
}
]
},
{
"id": "s_2",
"name": "Shortness of breath",
"choices": [
{
"id": "present",
"label": "Yes"
},
{
"id": "absent",
"label": "No"
}
]
}
],
"extras": {}
}An object should be added to the evidence list of the next request for each item of a group_multiple question. Any available choice_id is allowed. Omitting any item may cause the same question to be returned by the API again.
After you receive a question, you should answer it and send another call to /diagnosis. You repeat this process back and forth until the stop condition is met (should_stop: true).
For example, if the patient were to answer No to the question on accelerated breathing, you would need to add the following evidence:
{
"id": "s_13",
"choice_id": "absent"
}It's very important to understand that the /diagnosis endpoint is stateless. This means that the API does not track the state or progress of cases it receives so, with each request, you need to send all the information gathered about the patient to this point.
In our case, the next /diagnosis request could include the following JSON object:
{
"sex": "male",
"age": 30,
"evidence": [
{
"id": "s_13",
"choice_id": "absent"
},
{
"id": "s_1",
"choice_id": "present"
},
{
"id": "s_2",
"choice_id": "absent"
},
{
"id": "s_5",
"choice_id": "present"
}
]
}Note how you have to include the new evidence but (because of the stateless nature of /diagnosis) still keep the other data (including sex and age).
You can continue this process: ask a question, accept an answer from the user, append new evidence to the list, and make a request to /diagnosis. Each time, the API will reply with another question to ask until the stop condition is reached.
If should_stop is true, it means that the stop condition has been reached. False means that the interview should be continued.
Once the stop condition is met, it is time to call the /triage endpoint, which allows you to categorize the provided patient case and display suitable recommendations according to WHO and CDC guidelines.
The /triage endpoint responds to POST requests and accepts the same JSON object as the /diagnosis endpoint.
curl "https://api.infermedica.com/covid19/triage" \
-X "POST" \
-H "App-Id: XXXXXXXX" -H "App-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-H "Content-Type: application/json" -d '{
"sex": "male",
"age": 65,
"evidence": [
{"id": "p_16", "choice_id": "absent"},
{"id": "p_17", "choice_id": "present"},
{"id": "p_18", "choice_id": "absent"},
{"id": "p_19", "choice_id": "absent"},
{"id": "p_20", "choice_id": "absent"},
{"id": "p_21", "choice_id": "absent"},
{"id": "p_22", "choice_id": "absent"},
{"id": "s_0", "choice_id": "absent"},
{"id": "s_1", "choice_id": "absent"},
{"id": "s_2", "choice_id": "absent"},
{"id": "s_15", "choice_id": "present"},
{"id": "s_16", "choice_id": "present"},
{"id": "s_17", "choice_id": "absent"},
{"id": "s_18", "choice_id": "absent"},
{"id": "s_19", "choice_id": "absent"},
{"id": "s_20", "choice_id": "absent"},
{"id": "s_21", "choice_id": "absent"},
{"id": "p_12", "choice_id": "present"},
{"id": "p_24", "choice_id": "present"},
{"id": "p_23", "choice_id": "present"},
{"id": "s_24", "choice_id": "present"},
{"id": "p_27", "choice_id": "present"}
]
}'The response contains the following elements:
triage_level - a classification of the case provided,label - name of the recommendation e.g. “Call the emergency number. Avoid all contact.”,description - description of the recommendation e.g. “Your symptoms are very serious, and you may be infected with COVID-19.”,serious - a list of serious observations (e.g. shortness of breath).{
"description": "Your symptoms do not suggest that you may have COVID-19 infection. However, according to WHO and CDC guidelines, it is strongly recommended that you keep yourself separated from others for the next 14 days.",
"label": "Quarantine",
"serious": [
{
"common_name": "Living or caring for COVID-19 suspected person",
"id": "p_12",
"is_emergency": false,
"name": "Living or caring for COVID-19 suspected person"
}
],
"triage_level": "quarantine"
}The triage_level attribute can have one of the following values:
no_risk - Follow preventive measures.self_monitoring – Stay home and monitor your symptoms.quarantine – Quarantine.isolation_call – Consult your health care provider. Avoid all contact.call_doctor – Call a doctor, but symptoms might not be directly linked to COVID-19.isolation_ambulance – Call the emergency number. Avoid all contact.Please note that the number of triage levels may change with upcoming updates of WHO guidelines.
A phrase explaining the triage level. You can display it to the user.
A short description of the triage level. You can display it to the user.
Each listed observation has an unique id and name.
There are two possible levels of observation seriousness: all observations returned in the serious list are alarming and require consultation with a medical professional, but observations with is_emergency set to true are particularly urgent and may require immediate attention.
Using /diagnosis and /triage endpoints is sufficient for a complete COVID-19 risk assessment. However, we advise that you provide the information about the residence and/or travel to countries with a local widespread coronavirus transmission at the very beginning of the interview.
In order to do so, you should send a special kind of evidence, in the form of l_|country_code| e.g.:
{
"id": "l_fr",
"choice_id": "present"
}Country-related evidence items can be included at any point of the interview, however we recommend doing so at the beginning.
Country evidence supports two choice_id values: present or absent.
Please note that the list of countries classified as "local, widespread coronavirus transmission" is continuously updated in our API, and based on WHO's transmission reports.
To make the country evidence feature easier to use, we've included a /search endpoint to find country codes by full country name.
curl "https://api.infermedica.com/covid19/search?phrase=poland&type=country&max_results=3" \
-X "GET" \
-H "App-Id: XXXXXXXX" -H "App-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
This is a GET endpoint, consuming requests with no body and the following query parameters:
phrase [string, required] - name of the searched item (presently only countries are supported), in appropriate language (according to model header).type [string, optional, default=country] - type of searched items (presently the only supported type is country).max_results [int, optional, default=3] - maximum number of items to be returned.The output consists of a non-empty list of countries (with id and label) ordered by how well they match the given phrase (best ones first). Example of /search output:
[
{
"id": "l_pl",
"label": "Poland"
}
]The country id is already prefixed with l_, for convenient usage with the country evidence feature.
The /search endpoint supports both exact and fuzzy matching. If a correct country name is provided (ignoring the capitalization), such as “poland”, then only one item will be returned. When typos and/or truncated names are given (e.g. “polan”), multiple entires can be returned.
/locations endpoint allows you to get a list of all countries which can be recognized in evidence (see: Visited countries) and their COVID-19 transmission status according to the latest WHO reports. Possible use cases include widgets to select a country from a given list, and it can also be combined with /search.
Similar to /symptoms and /risk_factors, it is a GET endpoint with no parameters required.
{
"id": "l_ID",
"type": "country",
"name": "COUNTRY_NAME",
"extras": {
"country_iso_code": "ID_CODE_FOR_COUNTRY",
"has_local_covid_transmission": true / false
}
}COVID-19 prescreening is available in multiple languages and new languages are being added on a weekly basis:
To select a specific model, you need to send its name as a custom HTTP header called Model. Example of a request using Arabic model:
curl "https://api.infermedica.com/covid19/info" \
-X "GET" \
-H "App-Id: XXXXXXXX" -H "App-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-H "Model: infermedica-ar"