Providing initial observations is crucial for the /diagnosis endpoint to return the best possible results. There are various ways of gathering the initial evidence from a user,
with /search and /parse being the most useful. The /suggest endpoint also enhances this process by encouraging users to provide additional health information.
All evidence gathered using /suggest should be marked with a source value, for example:
Risk factors should be marked with the value suggest, 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 has 3 modes, each described in detail in the following subsections.
{"suggest_method": "symptoms"} is the default mode. It returns symptoms that have
frequently been reported by other users who have had similar symptoms and were of around the same age as well as being the same sex as the user. Suggestions provided by 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 the risk factors that are the most appropriate
to ask for after considering the 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 the risk factors that are the most appropriate to ask for after considering the 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 the risk factors that are common for the reported evidence. This mode requires that there not be any empty evidence. Evidence taken from this method during the 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 potentially alarming symptoms in the form of a list of observations related to the patient’s evidence that may be associated with possibly life-threatening conditions. Note: red flags are symptoms that are related to the most probable urgent conditions for the given evidence and patient demographics. The displayed symptoms are not necessarily emergency ones; they could also be standard symptoms that, in correlation with already present evidence, increase the probability of a illness that requires emergency treatment. This mode is the 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 to use before or instead of /search.
Please note, however, that /suggest
shouldn't be used as a replacement for /diagnosis. The /suggest endpoint cannot perform a full symptom assessment 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 works only with Infermedica's 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 and were provided 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 Infermedica API's trial access allows 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 users to better understand the purpose of a question. It expands the question with two additional fields:
explication text valueinstruction list of text valuesExplanation is an optional attribute and not every returned symptom or risk factor will 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 that gives users the possibility to exclude intimate concepts from a response e.g concepts related with sexual activity.
Disabling intimate content:
"extras": {
"disable_intimate_content": true
}
We recommend 3 approaches on how to handle suggested items:
1. (Recommendation) Send an answer to every suggested concept. It should be forced to mark every item as present, absent, or unknown without ignoring unchecked items. This approach results in the highest quality interviews.
2. Should the output from /suggest be displayed as a checklist, the best approach is to mark the unchecked concepts as unknown.
3. Alternatively, it is possible to ignore unchecked items. That said, doing so might cause questions about those items to appear again during the interview flow.
Flag enable_symptom_duration enables using a duration object for initial evidence (observations with "source": "initial") in /suggest endpoint when {"suggest_method": "symptoms"} is used.
"extras": {
"enable_symptom_duration": true
}
A duration object is composed of two fields:
value - numeric value, this attribute is requiredunit - text value, this attribute is required and the allowed values are:weekdayhourminute
{
...
"evidence": [
{
"id": "s_13",
"choice_id": "present",
"source": "initial",
"duration": {
"value": 2,
"unit": "day"
}
}
],
...
}