Providing initial observations is crucial for the /diagnosis
to return best possible results. There are different ways of gathering the initial evidence from a user,
with the /search and /parse
endpoints being the most useful. The /suggest endpoint
aims to further enhance this process in interactive applications by encouraging users to provide additional health information.
All evidence gathered using /suggest should be marked with source value, for example:
Risk factors should be marked with the value predefined, e.g. “source”: “suggest”
Red flags should be marked with the value red_flags, e.g. “source”: “red_flags”
Related symptoms should be marked with the value suggest, e.g. “source”: “suggest”.
Failure to add the /suggest value could result in an incomplete interview and inaccurate results.
{
...
"evidence": [
{"id": "s_21", "choice_id": "present", "source": "suggest"},
{"id": "s_13", "choice_id": "absent", "source": "suggest"},
{"id": "s_102", "choice_id": "absent", "source": "suggest"}
]
}/suggest endpoint has 3 modes, each described in detail in the following subsections.
{"suggest_method": "symptoms"} is a default mode. It returns symptoms that have
frequently been reported by other users with similar symptoms, age, and sex. Suggestions from this mode may help
a patient in expressing their chief complaint more precisely.
{
...
"evidence": [
{
"id": "s_21",
"choice_id": "present",
"source": "suggest"
},
{
"id": "s_13",
"choice_id": "absent",
"source": "suggest"
},
{
"id": "s_102",
"choice_id": "absent",
"source": "suggest"
}
]
}{"suggest_method": "risk_factors"} returns risk factors which are the most appropriate
to ask given patient’s age and sex. This mode allows for empty evidence,
i.e. "age" : {"value": 25}, "sex" : "female", "evidence" : [] is a valid request body.
This method was deprecated with the release of API 3.5. Although risk_factors will be supported alongside the two new methods (demographic_risk_factors and evidence_based_risk_factors), we recommend updating your API instance to the newer setup.
{
...
"evidence": [
{
"id": "p_7",
"choice_id": "present",
"source": "suggest"
},
{
"id": "p_9",
"choice_id": "present",
"source": "suggest"
},
{
"id": "p_28",
"choice_id": "unknown",
"source": "suggest"
}
]
}{"suggest_method": "demographic_risk_factors"} returns risk factors which are most appropriate to ask given patient’s age and sex. This mode allows for empty evidence, i.e. "age" : {"value": 25}, "sex" : "female", "evidence" : [] is a valid request body. Evidence taken from this method during interview should be marked with source suggest:
{
...
"evidence": [
{
"id": "p_7",
"choice_id": "present",
"source": "suggest"
},
{
"id": "p_9",
"choice_id": "present",
"source": "suggest"
},
{
"id": "p_28",
"choice_id": "unknown",
"source": "suggest"
}
]
}{"suggest_method": "evidence_based_risk_factors"} returns risk factors that are common for reported evidence. This mode requires not empty evidence. Evidence taken from this method during interview should be marked with source suggest:
{
...
"evidence": [
{
"id": "p_7",
"choice_id": "present",
"source": "suggest"
},
{
"id": "p_9",
"choice_id": "present",
"source": "suggest"
},
{
"id": "p_28",
"choice_id": "unknown",
"source": "suggest"
}
]
}{"suggest_method": "red_flags"} returns alarming symptoms - a list of observations related to patient’s evidence that may be associated with potentially life-threatening conditions. This mode is an equivalent of /red_flags.
After a user of your application selects some symptoms with /search or /parse, you can use /suggest to generate suggestions of other symptoms that might be present (think of a recommendation system such as "Other users with your symptoms also reported..."). The /suggest endpoint can also be used without sending any selected symptoms, to generate a list of the most commonly reported symptoms. This can be useful before or instead of /search in some scenarios.
Please note, however, that /suggest
shouldn't be used as a replacement for /diagnosis. The /suggest endpoint cannot perform differential diagnosis and uses a different statistical engine. After you've gathered 3-6 initial symptoms, you're safe to start making calls to /diagnosis.
The /suggest
endpoint is available in all languages, but can only work with the Infermedica default model.
{
...
"evidence": [
{
"id": "s_1543",
"choice_id": "unknown",
"source": "red_flags"
},
{
"id": "s_13",
"choice_id": "unknown",
"source": "red_flags"
},
{
"id": "s_102",
"choice_id": "unknown",
"source": "red_flags"
}
]
}The /suggest
endpoint responds to POST requests of the same structure as /diagnosis:
curl "https://api.infermedica.com/v3/suggest" \
-X "POST" \
-H "App-Id: XXXXXXXX" -H "App-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-H "Content-Type: application/json" -d '{
"age" : {
"value": 25
},
"sex" : "female",
"evidence" : [
{
"choice_id" : "present",
"id" : "s_305",
"source": "initial"
}
],
"suggest_method": "symptoms"
}'The example above describes the case of a 25-year-old female patient who has already reported vomiting (represented here by the symptom ID s_305).
The response contains a list of symptoms that have often been reported together with the provided observations by other patients
of the same sex and similar age. Each returned symptom is represented by a JSON object with the following attributes:
id, name
and name_common. These values are consistent with the database of
medical concepts
understood by the Infermedica API.
[
{
"id": "s_156",
"name": "Nausea",
"common_name": "Feeling sick"
},
{
"id": "s_13",
"name": "Abdominal pain",
"common_name": "Stomach pain"
},
{
"id": "s_8",
"name": "Diarrhea",
"common_name": "Diarrhea"
}
]Please note that the free trial plan of the Infermedica API allows for only a limited number of calls to the /suggest
endpoint. Please contact us for other plan options.
The extras attribute may contain additional or experimental options that control the behavior of the inference engine. Some are only valid with custom models or selected partners.
This functionality helps to better understand sense of question. It extends question with two additional fields:
explication text valueinstruction list of text valuesExplanation is an optional attribute and not every returned symptom or risk factor would have it.
Enabling explanations:
"extras": {
"enable_explanations": true
}
Example output:
[
{
"id": "s_1543",
"name": "Loss of consciousness",
"common_name": "Loss of consciousness",
"explication": null,
"instruction": [
"Observe if they open their eyes spontaneously.",
"Check their verbal response, e.g., is it orientate and adequate to their development.",
"Observe if they move spontaneously."
]
},
{
"id": "s_261",
"name": "Tachycardia",
"common_name": "Fast heartbeat",
"explication": "A heart rate above the normal range for their age. In people over 12 year of age it's more than 100 beats per minute.",
"instruction": [
"Wait a few minutes after physical exercise.",
"Using the index and middle finger, gently press on the inside of the wrist on the side of the thumb, or press on one side of the neck next to the windpipe until the pulse is felt.",
"Count the beats for 15 seconds.",
"Multiply by 4 to get the number of beats per minute."
]
}
]
Extra gives possibility to exclude intimate concepts from response e.g concepts related with sexual activity.
Disabling intimate content:
"extras": {
"disable_intimate_content": true
}
We are recommending 3 approaches how to handle suggested items:
1. (Recommended) Send answer to every suggested concept. It should be forced to mark every item as present, absent, or unknown without ignoring unchecked items. This approach gives the best quality of interview.
2. In case the output from /suggest is displayed as checklist, the best approach is to mark unchecked concepts as unknown.
3. Alternative approach for checklist is to ignore unchecked items and don’t answer to them. Note that questions about those items could appear again during interview flow.