COVID-19

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 impact of the virus on public health and economies.

Changelog

April 2, 2020

API v3

The /v3 will become the default API version on April 6, 2020, but you can switch to the new version right now.

  • Updated flow of the interview - more accurate recommendation for serious situations taking into account not only COVID symptoms but also risk factors, comorbidities and other symptoms.
  • Enabled API versioning.
  • Added a new triage level call_doctor recommended for patients with serious conditions but not related to COVID-19.
  • Added /locations endpoint for listing all countries.
  • Better error messages handling.

March 25, 2020

API v2

  • Updated flow of the interview.
  • Added questions about comorbidities and COVID-19 risk factors.
  • Improved question about contact with suspected COVID-19 patient.
  • Extended interview for emergency patients.
  • Added /search endpoint - search for visited countries (find country codes by full country name).
  • Enabled reporting of visited countries in evidence - they are interpreted depending on category of local transmission of COVID-19.
  • Added explanation - a field which can be used to explain better a question, symptom or risk factor to the user.
  • Added /symptoms and /risk_factors endpoints listing all available concepts in COVID-19 API medical base.

March 20, 2020

API v1

Medical foundations

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:

How to get started

If you haven’t already, please sign up to Infermedica API. The COVID-19 endpoints are free of charge for everyone, you will not be asked to provide any payment methods.

Setup

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.

Authentication

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 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": []
}'

Available endpoints

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 Provides information on how yoy classify 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 COVID-19 API.

    Versioning

    In order to allow smooth transitions to new API versions in case of major changes (e.g. new triage levels) we enabled API versioning.

    Use an optional HTTP header called Version to select the API version. Version names use the following naming convention: v2, v3 etc.

    curl "https://api.infermedica.com/covid19/locations" \
      -X "GET" \
      -H "App-Id: XXXXXXXX" -H "App-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
      -H "Model: infermedica-en"
      -H "Version: v3"
    

    If Version is not provided, a default version of the API will be used. A new API version becomes a default one not sooner than 3 days after its release. During this time you should test your application and adapt it if needed. As usual we will inform you about any new API releases.

    We strongly recommend to keep up-to-date with latest releases. It’s best to keep default API version and use Version for testing mode only. Each old version will be disabled after 4 weeks after its release.

    Diagnosis

    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 to replace any medical advice.

    First request

    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, risk factors). The list of evidence can be empty at the beginning.

    Let's assume we have a male patient, aged 30 and no observations yet. Such case described above 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": []
    }'
    

    Output

    The response returned from /diagnosis will contain several sections:

    • the next diagnostic question to ask your user,
    • a flag indicating whether the interview should be stopped,
    • a list of conditions - this will be always empty for backwards compatibility with our general symptom checker API,
    • extras - usually empty, 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": "..."
    }

    Question

    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.

    Question types

    There are 3 types of questions, each requiring slightly different handling.

    single

    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"}
      ]
    }
    group_single

    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"}
      ]
    }
    group_multiple

    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.

    Interview flow

    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, make a request to /diagnosis. Each time the API will reply with another question to ask until the stop condition is reached.

    Stop condition

    If should_stop is true, it means that the stop condition has been reached. False means that the interview should be continued.

    Triage

    Once the stop condition is met it is time to call an endpoint called /triage which allows you to categorize the provided patient case and display suitable recommendations according to WHO and CDC guidelines.

    Request

    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"}
            ]
      }'
    

    Response

    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"
    }
    Triage level

    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 health care provider. Avoid all contact.
    • call_doctor – Call a doctor, 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.

    Label

    A phrase explaining the triage level. You can display it to the user.

    Description

    Short description of the triage level. You can display it to the user.

    Serious observations

    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.

    Visited countries

    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 inteview.

    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 continously updated in our API based on WHO's transmission reports.

    To make the country evidence feature easier to use, we've included /search endpoint for searching for 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 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 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.

    /search endpoint supports both exact and fuzzy matching. If a correct country name is provided (ignoring the capitalization), e.g. “poland”, then only one item will be returned. When typos and/or truncated names are given (e.g. “polan”) multiple entires can be returned.

    List all countries

    /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 latest WHO reports. Possible use cases include widgets to select country from a given list, 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
        }
    }

    Language versions

    COVID-19 prescreening is available in multiple languages and new languages are being added on a weekly basis:

    • infermedica-en - English (US)
    • infermedica-ar – Arabic
    • infermedica-ar-sa – Arabic (Saudi Arabia)
    • infermedica-tr - Turkish
    • infermedica-es - Spanish
    • infermedica-pt - Portuguese
    • infermedica-pt-br - Brazilian Portuguese
    • infermedica-fr - French
    • infermedica-de - German
    • infermedica-it - Italian
    • infermedica-pl - Polish
    • infermedica-cz - Czech
    • infermedica-uk - Ukrainian
    • infermedica-ch - Simplified Chinese
    • infermedica-nl - Dutch
    • infermedica-sk - Slovak
    • infermedica-es-mx - Mexican Spanish
    • infermedica-es-xl - Spanish (Latin American)
    • infermedica-ka - Georgian
    • infermedica-ru - Russian
    • infermedica-et - Estonian
    • infermedica-hr - Croatian
    • infermedica-ms - Malay
    • infermedica-ta - Tamil
    • infermedica-si-lk - Sinhala
    • infermedica-ro - Romanian
    • infermedica-hi - Hindi

    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"