Suggest related observations

Providing initial observations is essential for the /diagnosis endpoint to achieve the most accurate results. Gathering this initial evidence from users can be done in various ways, usually with the /search or /parse endpoints. The /suggest endpoint further enhances this process by prompting users to provide additional health information.

After a user selects several symptoms or risk factors via /search or /parse, /suggest can propose more observations that may be relevant using a prompt like "Other users with your symptoms also reported...". /suggest can also be used with certain methods to generate a list of commonly reported observations before any evidence is selected. This is useful as a preliminary step or as an alternative to /search.

It's important to remember, however, that /suggest is not a replacement for /diagnosis. The /suggest endpoint does not perform a complete symptom assessment and relies on a different statistical engine. Once 3-6 initial pieces of evidence are gathered, it is advisable to switch to using the /diagnosis endpoint.

Marking evidence source

All evidence gathered using the /suggest endpoint must include a source attribute in subsequent calls to the /diagnosis endpoint:

• related symptoms and risk factors should be marked with the suggest value, as in "source": "suggest":

  JSON

  {
    ...
    "evidence": [
      {"id": "p_9", "choice_id": "present", "source": "suggest"},
      {"id": "p_7", "choice_id": "unknown", "source": "suggest"}
    ]
  }

• red flag symptoms should be marked with the red_flags value, as in "source": "red_flags":

  JSON

  {
    ...
    "evidence": [
      {"id": "s_156", "choice_id": "present", "source": "red_flags"},
      {"id": "s_227", "choice_id": "unknown", "source": "red_flags"}
    ]
  }

Omitting the source attribute can lead to incomplete interviews and potentially inaccurate results.

Available methods

The /suggest endpoint supports different methods, each of which is described in detail in the following subsections.

Related symptoms (default)

The default method for /suggest is {"suggest_method": "symptoms"}. This method returns symptoms that are often reported together with the given evidence, considering the selected age and sex. These suggestions can help users more accurately describe their primary concerns.

Mark evidence gathered using this method with "source": "suggest".

Demographic risk factors

The method {"suggest_method": "demographic_risk_factors"} identifies the most common risk factors for patients of a particular age and sex. This method can operate with an empty evidence list, e.g., {"age": {"value": 25}, "sex": "female", "evidence": []} is a valid request.

Mark evidence from this method with "source": "suggest".

Evidence-based risk factors

Using {"suggest_method": "evidence_based_risk_factors"}, the endpoint returns risk factors related to the reported evidence. This method requires a non-empty evidence list.

Mark evidence from this method with "source": "suggest".

Relevant risk factors (deprecated)

The {"suggest_method": "risk_factors"} method, now deprecated, can return risk factors linked to both patient demographics and reported evidence.

Mark evidence from this method with "source": "suggest".

Red flags

The {"suggest_method": "red_flags"} method identifies potentially alarming symptoms related to the patient’s evidence and demographics. These 'red flags' could be emergency symptoms or symptoms that, in combination with other evidence, suggest a higher risk of a serious life-threatening illness.

This method is equivalent to the deprecated /red_flags endpoint.

Mark evidence from this method with "source": "red_flags".

Request

The /suggest endpoint responds to POST requests and requires a JSON object similar to the one used for the /diagnosis endpoint. To specify the method, add the suggest_method attribute to the request. If this attribute is not specified, the default symptoms method is used.

The number of results returned can be increased or decreased beyond the default by adding a limit via max_results. The default limit is 8. The engine will not necessarily return the maximum number of results. In the example below, the results are limited to a maximum of 12 results. In the response, only 3 results are returned as only those 3 are determined to be significant.

Below is an example of a request for a 25-year-old female patient who has reported vomiting (symptom s_305):

curl "https://api.infermedica.com/v3/suggest?max_results=12" \
  -X "POST" \
  -H "App-Id: XXXXXXXX" \
  -H "App-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -H "Interview-Id: d083e76f-3c29-44aa-8893-587f3691c0c5" \
  -d '{
    "age": {
      "value": 25
    },
    "sex": "female",
    "evidence": [
      {
        "choice_id": "present",
        "id": "s_305",
        "source": "initial"
      }
    ],
    "suggest_method": "symptoms"
  }'

Response

The response includes a list of suggested symptoms. Each symptom in the response is represented as a JSON object with attributes: id, name, and common_name. These attributes are consistent with the medical concepts recognized by the Infermedica API.

The response below shows symptoms commonly reported in conjunction with vomiting (s_305), as per the above request example:

[
  {
    "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"
  },
  ...
]

Extras

Since the /suggest endpoint accepts the same request structure as the /diagnosis endpoint, it can also accept various extra options. For a detailed description of these options, refer to the Extras section on the /diagnosis page.

The enable_explanations option can extend the /suggest response object with two additional attributes:

• explication – provides additional details about the suggested observation,
• instruction – offers a list of steps to verify the presence of the observation in the patient.

Example response with explanations:

[
  {
    "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."
    ]
  }
]

The disable_intimate_content option can be used to exclude suggestions of observations that are considered "intimate" or sensitive.

Implementation guidelines

There are several approaches to presenting a list of suggested observations to users. The method of presentation can influence the approach to collecting evidence from these suggestions, and thus the quality of the interview:

• (Recommended) Whenever appropriate, add explications and instructions to improve the quality of the interview. This is particularly important when working with red flags and suggested symptoms.

• (Recommended) Ask users to classify each suggested observation as present, absent, or unknown. Encouraging users to distinguish between absent and unknown and to respond to each suggestion ensures gathering more initial evidence and higher quality interviews.

• If presenting the suggestions as a checklist, consider marking unchecked observations as unknown.

• Alternatively, you may choose to disregard unchecked observations. However, this might result in those observations reappearing during the interview.

For more information on implementations, see the Technical Tips (opens in a new tab) section of our Help Center.