Documentation
Platform API
Build your solution
Medical Knowledge

Medical Knowledge

Platform API offers a rich array of medical knowledge that’s easily accessed via the following endpoints:

By leveraging the comprehensive data available through these endpoints, developers can create or extend medical assessment solutions with a solid foundation that’s rooted in medical expertise.

Each of these medical knowledge endpoints is a GET endpoint that uses the query parameters listed below. Some of these query parameters are required and need to be provided in order to receive a successful response, i.e. one with an HTTP 200 status code. Others are optional, perhaps consisting of a group of 'paging params' like cursor, which sets the displayed page number, or limit, which sets the amount of objects displayed per page.

Query parameters

The list of required parameters is as follows:

  • sex - Possible values include either male or female
  • language - Text parameter with a value that corresponds to the desired language e.g. en (English), de (German), fr (French)
  • age.value- Numerical value (between 0 - 130 if age.unit is equal to year, or between 0 - 1560 if age.unit is equal to month)

Optional parameters include:

  • age.unit - Possible values include either year or month. Default value is year
  • id - ID value that represents a concept. Multiple IDs can be sent in one request e.g. ?id=s_57&id=s_1852
  • query - Text value that filters results down to the concept name contained in the query value
  • cursor - A numerical value (between 0 - XX, XX being a maximum value that depends on the amount of content and what amount is set in the limit query parameter) . Default value is 0
  • limit - A numerical value (between 1 - 50). Default value is 10

Symptoms

A paged list of symptoms is available for our clients through the /symptoms endpoint. To retrieve the list of symptoms, send a GET request to /api/mgp/v1/knowledge/symptoms.

Our /symptoms endpoint stores two different types of medical concepts, symptoms and risk factors. A symptom might be something you feel or experience that indicates a possible health condition or issue, eg. headache (id: s_21). All symptoms IDs start with a s_ On the other hand, a risk factor eg. smoking cigarettes (id: p_28) is a characteristic, behavior, or precondition that increases the likelihood of developing a certain disease or health problem. All risk factor IDs start with a p_.

Symptoms request

To retrieve the first page of symptoms for a 22-year-old male and limit the amount of symptoms to 5, you should send the request as follows:

cURL
curl "https://api.infermedica.com/api/mgp/v1/knowledge/symptoms" \
  -X "GET" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d "sex=male" \
  -d "language=en" \
  -d "age.value=22" \
  -d "age.unit=year" \
  -d "limit=5"

Symptoms response

Requests like the one above will get a response like the one below, which consists of 5 alphabetically sorted symptoms along with some additional paging attributes. These paging attributes include self (showing the currently displayed page - by default 0), first (showing the first available page), prev ( showing the previous available page - marked as 'null' in this example as the page shown is the first page), next (showing the next available page), and last (showing the last available page). These paging attributes will also be found in other responses such as when the user requests a list of chronic diseases or specialists.

JSON
{
  "self": "https://api.infermedica.com/api/mgp/v1/knowledge/symptoms?sex=male&language=en&age.value=22&age.unit=year&limit=5&cursor=0",
  "first": "https://api.infermedica.com/api/mgp/v1/knowledge/symptoms?sex=male&language=en&age.value=22&age.unit=year&limit=5&cursor=0",
  "prev": null,
  "next": "https://api.infermedica.com/api/mgp/v1/knowledge/symptoms?sex=male&language=en&age.value=22&age.unit=year&limit=5&cursor=1",
  "last": "https://api.infermedica.com/api/mgp/v1/knowledge/symptoms?sex=male&language=en&age.value=22&age.unit=year&limit=5&cursor=376",
  "items": [
    {
      "id": "s_1558",
      "name": "Abdominal guarding"
    },
    {
      "id": "s_1922",
      "name": "Abdominal pain after dropping hard on heels"
    },
    {
      "id": "s_16",
      "name": "Abdominal pain after eating"
    },
    {
      "id": "s_57",
      "name": "Abdominal pain improves after bowel movement or passing gas"
    },
    {
      "id": "s_1852",
      "name": "Abdominal pain lasting 2 to 7 days"
    }
  ]
}

Symptoms request targeting a particular symptom’s ID

Using the optional parameter id in /symptoms enables users to target specific symptoms, risk factors, sets of symptoms, or sets of risk factors. This is useful if, for example, you want to verify that a particular symptom or set of symptoms is available for a patient of a particular sex and age. Let's verify if symptoms with IDs s_121 (Hair loss) and s_1089 (Prostate enlargement) are available for a 30-year-old female. We can omit cursor and limit as the default values for those query parameters are sufficient for what we want to achieve.

cURL
curl "https://api.infermedica.com/api/mgp/v1/knowledge/symptoms" \
 -X "GET" \
 -H "Authorization: Bearer <ACCESS_TOKEN>" \
 -d "sex=female" \
 -d "language=en" \
 -d "age.value=30" \
 -d "age.unit=year" \
 -d "id=s_121" \
 -d "id=s_1089"

Symptoms response targeting a particular symptom’s ID

A response to the above request will look like the one seen below. This response lacks data about s_1089 (Prostate enlargement) because the symptoms are specifically for a 30-year-old female.

JSON
{
  "self": "https://api.infermedica.com/api/mgp/v1/knowledge/symptoms?sex=female&language=en&id=s_1089&age.value=30&age.unit=year&cursor=0",
  "first": "https://api.infermedica.com/api/mgp/v1/knowledge/symptoms?sex=female&language=en&id=s_1089&age.value=30&age.unit=year&cursor=0",
  "prev": null,
  "next": null,
  "last": "https://api.infermedica.com/api/mgp/v1/knowledge/symptoms?sex=female&language=en&id=s_1089&age.value=30&age.unit=year&cursor=0",
  "items": [
    {
      "id": "s_121",
      "name": "Hair loss"
    }
  ]
}

Symptoms request with name filtering

To filter through symptoms by matching the text chosen by the user to the text found within a symptom or risk factor’s name, we should use another optional parameter, called query. For example, in order to search for the text 'headache' in every symptom’s name that is applicable to a 30-year-old female, you should prepare your request as follows:

cURL
curl "https://api.infermedica.com/api/mgp/v1/knowledge/symptoms" \
 -X "GET" \
 -H "Authorization: Bearer <ACCESS_TOKEN>" \
 -d "sex=female" \
 -d "language=en" \
 -d "age.value=30" \
 -d "age.unit=year" \
 -d "query=headache"

Symptoms response with name filtering

A response to the above filtering request is presented below and displays the first 10 symptoms - if limit is omitted then the default will be used - that had the string 'headache' as part of their name as well as the paging attributes mentioned in Symptoms response.

JSON
{
  "self": "https://api.infermedica.com/api/mgp/v1/knowledge/symptoms?sex=female&language=en&query=headache&age.value=30&age.unit=year&cursor=0",
  "first": "https://api.infermedica.com/api/mgp/v1/knowledge/symptoms?sex=female&language=en&query=headache&age.value=30&age.unit=year&cursor=0",
  "prev": null,
  "next": null,
  "last": "https://api.infermedica.com/api/mgp/v1/knowledge/symptoms?sex=female&language=en&query=headache&age.value=30&age.unit=year&cursor=0",
  "items": [
    {
      "id": "s_21",
      "name": "Headache"
    },
    {
      "id": "s_1349",
      "name": "Headache, forehead"
    },
    {
      "id": "s_1780",
      "name": "Headache, mild"
    },
    {
      "id": "s_1781",
      "name": "Headache, moderate"
    },
    {
      "id": "s_23",
      "name": "Headache, pressing"
    },
    {
      "id": "s_1912",
      "name": "Headache, recent"
    },
    {
      "id": "s_1193",
      "name": "Headache, severe"
    },
    {
      "id": "s_1905",
      "name": "Headache, sudden onset"
    }
  ]
}

Chronic diseases

A paged list of chronic diseases is available for our clients through the /chronic_diseases endpoint. To retrieve the list, send a GET request to /api/mgp/v1/knowledge/chronic_diseases.

Chronic diseases request

To retrieve the first page of the chronic diseases list for a 20-year-old male and limit the amount of chronic diseases to 6, you should send the request as follows:

cURL
curl "https://api.infermedica.com/api/mgp/v1/knowledge/chronic_diseases" \
  -X "GET" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d "sex=male" \
  -d "language=en" \
  -d "age.value=20" \
  -d "age.unit=year" \
  -d "limit=6"

Chronic diseases response

The request will look like the one found below, with 6 alphabetically sorted chronic diseases as well as the paging attributes mentioned in Symptoms response.

JSON
{
  "self": "https://api.infermedica.com/api/mgp/v1/knowledge/chronic_diseases?sex=male&language=en&age.value=20&age.unit=year&limit=6&cursor=0",
  "first": "https://api.infermedica.com/api/mgp/v1/knowledge/chronic_diseases?sex=male&language=en&age.value=20&age.unit=year&limit=6&cursor=0",
  "prev": null,
  "next": "https://api.infermedica.com/api/mgp/v1/knowledge/chronic_diseases?sex=male&language=en&age.value=20&age.unit=year&limit=6&cursor=1",
  "last": "https://api.infermedica.com/api/mgp/v1/knowledge/chronic_diseases?sex=male&language=en&age.value=20&age.unit=year&limit=6&cursor=57",
  "items": [
    {
      "id": "c_1366",
      "name": "ADHD - hyperactive type"
    },
    {
      "id": "c_1365",
      "name": "ADHD — inattentive type"
    },
    {
      "id": "c_764",
      "name": "Abdominal aortic aneurysm"
    },
    {
      "id": "c_1",
      "name": "Achalasia"
    },
    {
      "id": "c_111",
      "name": "Acne"
    },
    {
      "id": "c_471",
      "name": "Acoustic neuroma"
    }
  ]
}

Chronic diseases request targeting particular chronic disease IDs

The optional parameter id in /chronic_diseases enables users to target a specific chronic disease or set of diseases. For example, if you want to verify if a particular chronic disease or set of chronic diseases are available for a patient of a certain sex and age. Let's verify if the chronic diseases with an id of c_820 (Skin cyst) and c_711 (Sleep apnea) are available for a 28-year-old female. We omit cursor and limit as the default values for those query parameters are sufficient for what we want to achieve. The request looks as follows:

cURL
curl "https://api.infermedica.com/api/mgp/v1/knowledge/chronic_diseases" \
 -X "GET" \
 -H "Authorization: Bearer <ACCESS_TOKEN>" \
 -d "sex=female" \
 -d "language=en" \
 -d "age.value=28" \
 -d "age.unit=year" \
 -d "id=c_820" \
 -d "id=c_711"

Chronic diseases response targeting particular chronic disease IDs

A response to the above request looks like below.

JSON
{
  "self": "https://api.infermedica.com/api/mgp/v1/knowledge/chronic_diseases?sex=female&language=en&id=c_820&age.value=28&age.unit=year&cursor=0",
  "first": "https://api.infermedica.com/api/mgp/v1/knowledge/chronic_diseases?sex=female&language=en&id=c_820&age.value=28&age.unit=year&cursor=0",
  "prev": null,
  "next": null,
  "last": "https://api.infermedica.com/api/mgp/v1/knowledge/chronic_diseases?sex=female&language=en&id=c_820&age.value=28&age.unit=year&cursor=0",
  "items": [
    {
      "id": "c_820",
      "name": "Skin cyst"
    },
    {
      "id": "c_711",
      "name": "Sleep apnea"
    }
  ]
}

Chronic diseases request with name filtering

To filter through chronic diseases by matching text to the text in their names, we should use an optional parameter named query. For example, to filter out chronic diseases with the text 'tumor' in their name for a 28-year-old male, you should prepare the request as follows:

cURL
curl "https://api.infermedica.com/api/mgp/v1/knowledge/chronic_diseases" \
 -X "GET" \
 -H "Authorization: Bearer <ACCESS_TOKEN>" \
 -d "sex=male" \
 -d "language=en" \
 -d "age.value=28" \
 -d "age.unit=year" \
 -d "query=tumor"

Chronic diseases response with name filtering

A response to the above filtering request is presented below and displays the first chronic diseases that had the string 'tumor' within their name.

JSON
{
  "self": "https://api.infermedica.com/api/mgp/v1/knowledge/chronic_diseases?sex=male&language=en&query=tumor&age.value=28&age.unit=year&cursor=0",
  "first": "https://api.infermedica.com/api/mgp/v1/knowledge/chronic_diseases?sex=male&language=en&query=tumor&age.value=28&age.unit=year&cursor=0",
  "prev": null,
  "next": null,
  "last": "https://api.infermedica.com/api/mgp/v1/knowledge/chronic_diseases?sex=male&language=en&query=tumor&age.value=28&age.unit=year&cursor=0",
  "items": [
    {
      "id": "c_333",
      "name": "Brain tumor"
    },
    {
      "id": "c_617",
      "name": "Pancoast tumor"
    },
    {
      "id": "c_334",
      "name": "Pituitary tumor"
    }
  ]
}

Specialists

A paged list of specialists is available for our clients through the /specialists endpoint. To retrieve the list of specialists, send a GET request to the /api/mgp/v1/knowledge/specialists endpoint.

Specialists request

To retrieve the first page of specialists for a 66-year-old female with a default limit of 10 specialists, the request should look as follows:

cURL
curl "https://api.infermedica.com/api/mgp/v1/knowledge/specialists" \
  -X "GET" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d "sex=female" \
  -d "language=en" \
  -d "age.value=66" \
  -d "age.unit=year"

Specialists response

The request above will have a response with 10 alphabetically sorted specialists, as shown below. It will also include those paging attributes that were mentioned in Symptoms response.

JSON
{
  "self": "https://api.infermedica.com/api/mgp/v1/knowledge/specialists?sex=female&language=en&age.value=66&age.unit=year&cursor=0",
  "first": "https://api.infermedica.com/api/mgp/v1/knowledge/specialists?sex=female&language=en&age.value=66&age.unit=year&cursor=0",
  "prev": null,
  "next": "https://api.infermedica.com/api/mgp/v1/knowledge/specialists?sex=female&language=en&age.value=66&age.unit=year&cursor=1",
  "last": "https://api.infermedica.com/api/mgp/v1/knowledge/specialists?sex=female&language=en&age.value=66&age.unit=year&cursor=2",
  "items": [
    {
      "id": "sp_23",
      "name": "Allergologist"
    },
    {
      "id": "sp_21",
      "name": "Angiologist"
    },
    {
      "id": "sp_12",
      "name": "Cardiologist"
    },
    {
      "id": "sp_18",
      "name": "Dentist"
    },
    {
      "id": "sp_9",
      "name": "Dermatologist"
    },
    {
      "id": "sp_22",
      "name": "Diabetologist"
    },
    {
      "id": "sp_14",
      "name": "ENT doctor"
    },
    {
      "id": "sp_10",
      "name": "Endocrinologist"
    },
    {
      "id": "sp_5",
      "name": "Gastroenterologist"
    },
    {
      "id": "sp_15",
      "name": "Gynecologist"
    }
  ]
}

Specialists request targeting particular symptom IDs

Using the optional parameter id via the /specialists endpoint enables users to target specific specialists. For example, you’d use this if you want to verify if a particular specialist or specialists are available for a patient of a particular sex and age. Let's verify if specialists with id sp_15 (Gynecologist) and sp_12 (Cardiologist) are available for a 66-year-old male. We’ll omit cursor and limit here as the default values for those query parameters are sufficient for what we need.

cURL
curl "https://api.infermedica.com/api/mgp/v1/knowledge/specialists" \
 -X "GET" \
 -H "Authorization: Bearer <ACCESS_TOKEN>" \
 -d "sex=male" \
 -d "language=en" \
 -d "age.value=66" \
 -d "age.unit=year" \
 -d "id=sp_15" \
 -d "id=sp_12"

Specialists response targeting particular symptom IDs

A response to the above request will look like the one below. It lacks information about sp_15 (Gynecologist) because this specialist is unavailable for a 66-year-old male.

JSON
{
  "self": "https://api.infermedica.com/api/mgp/v1/knowledge/specialists?sex=male&language=en&id=sp_12&age.value=66&age.unit=year&cursor=0",
  "first": "https://api.infermedica.com/api/mgp/v1/knowledge/specialists?sex=male&language=en&id=sp_12&age.value=66&age.unit=year&cursor=0",
  "prev": null,
  "next": null,
  "last": "https://api.infermedica.com/api/mgp/v1/knowledge/specialists?sex=male&language=en&id=sp_12&age.value=66&age.unit=year&cursor=0",
  "items": [
    {
      "id": "sp_12",
      "name": "Cardiologist"
    }
  ]
}

Specialists request with name filtering

To filter through specialists by matching text to the text within their names, we should use an optional parameter named query. To search for specialists with the text 'doctor' in their name for a 35-year-old male, you should prepare the request as follows:

cURL
curl 'https://api.infermedica.com/api/mgp/v1/knowledge/symptoms' \
 -X "GET" \
 -d "sex=male" \
 -d "language=en" \
 -d "age.value=35" \
 -d "age.unit=year" \
 -d "query=doctor"

Specialists response with name filtering

A response to the above filtering request is presented below. It displays any results that had the string 'doctor' within the specialist’s name, as requested.

JSON
{
  "self": "https://api.infermedica.com/api/mgp/v1/knowledge/specialists?sex=male&language=en&query=doctor&age.value=35&age.unit=year&cursor=0",
  "first": "https://api.infermedica.com/api/mgp/v1/knowledge/specialists?sex=male&language=en&query=doctor&age.value=35&age.unit=year&cursor=0",
  "prev": null,
  "next": null,
  "last": "https://api.infermedica.com/api/mgp/v1/knowledge/specialists?sex=male&language=en&query=doctor&age.value=35&age.unit=year&cursor=0",
  "items": [
    {
      "id": "sp_14",
      "name": "ENT doctor"
    }
  ]
}

Hospitalizations

A paged list of hospitalizations is available for our clients through the /hospitalizations endpoint. To retrieve a list of hospitalizations, send a GET request to the /api/mgp/v1/knowledge/hospitalizations endpoint.

Hospitalizations request

To retrieve the first page of hospitalizations for a 55-year-old male with a default limit of 10 hospitalizations, the request should look as follows:

cURL
curl "https://api.infermedica.com/api/mgp/v1/knowledge/hospitalizations" \
  -X "GET" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d "sex=male" \
  -d "language=en" \
  -d "age.value=55" \
  -d "age.unit=year"

Hospitalizations response

The request above will have a response as shown below, with 10 alphabetically sorted hospitalizations as well as the paging attributes mentioned in Symptoms response.

JSON
{
  "self": "https://api.infermedica.com/api/mgp/v1/knowledge/hospitalizations?sex=male&language=en&age.value=55&age.unit=year&cursor=0",
  "first": "https://api.infermedica.com/api/mgp/v1/knowledge/hospitalizations?sex=male&language=en&age.value=55&age.unit=year&cursor=0",
  "prev": null,
  "next": "https://api.infermedica.com/api/mgp/v1/knowledge/hospitalizations?sex=male&language=en&age.value=55&age.unit=year&cursor=1",
  "last": "https://api.infermedica.com/api/mgp/v1/knowledge/hospitalizations?sex=male&language=en&age.value=55&age.unit=year&cursor=1",
  "items": [
    {
      "id": "p_319",
      "name": "Coronarography"
    },
    {
      "id": "p_324",
      "name": "Hernia repair"
    },
    {
      "id": "p_321",
      "name": "Hip joint replacement"
    },
    {
      "id": "p_318",
      "name": "History of COVID infection"
    },
    {
      "id": "p_323",
      "name": "History of sepsis"
    },
    {
      "id": "p_327",
      "name": "Hypertensive crisis"
    },
    {
      "id": "p_322",
      "name": "Knee joint replacement"
    },
    {
      "id": "p_313",
      "name": "Removal of bladder"
    },
    {
      "id": "p_311",
      "name": "Removal of colon"
    },
    {
      "id": "p_314",
      "name": "Removal of kidney"
    }
  ]
}

Hospitalizations request targeting particular hospitalization IDs

Using the optional parameter id via the /hospitalizations endpoint enables users to target specific hospitalizations. For example, this could be used to verify if a particular hospitalization is available for a patient of a particular sex and age. Let's verify if hospitalizations with id p_311 (Removal of colon) and p_314 (Removal of kidney) are available for a 55-year-old male. We omit cursor and limit as the default values for those query parameters are sufficient for our aims at the moment.

cURL
curl "https://api.infermedica.com/api/mgp/v1/knowledge/hospitalizations" \
 -X "GET" \
 -H "Authorization: Bearer <ACCESS_TOKEN>" \
 -d "sex=male" \
 -d "language=en" \
 -d "age.value=55" \
 -d "age.unit=year" \
 -d "id=p_311" \
 -d "id=p_314"

Hospitalizations response targeting particular hospitalization IDs

A response to the above request will look like the one shown below.

JSON
{
  "self": "https://api.infermedica.com/api/mgp/v1/knowledge/hospitalizations?sex=male&language=en&id=p_314&age.value=55&age.unit=year&cursor=0",
  "first": "https://api.infermedica.com/api/mgp/v1/knowledge/hospitalizations?sex=male&language=en&id=p_314&age.value=55&age.unit=year&cursor=0",
  "prev": null,
  "next": null,
  "last": "https://api.infermedica.com/api/mgp/v1/knowledge/hospitalizations?sex=male&language=en&id=p_314&age.value=55&age.unit=year&cursor=0",
  "items": [
    {
      "id": "p_311",
      "name": "Removal of colon"
    },
    {
      "id": "p_314",
      "name": "Removal of kidney"
    }
  ]
}

Hospitalizations request with name filtering

To filter through hospitalizations by matching text to the text within their names, we should use an optional parameter named query. To search for hospitalizations with the text 'hip' in their name for a 55-year-old male, you should prepare the request as follows:

cURL
curl "https://api.infermedica.com/api/mgp/v1/knowledge/hospitalizations" \
 -X "GET" \
 -H "Authorization: Bearer <ACCESS_TOKEN>" \
 -d "sex=male" \
 -d "language=en" \
 -d "age.value=55" \
 -d "age.unit=year" \
 -d "query=hip"

Hospitalizations response with name filtering

A response to the above filtering request is presented below and displays results that had the string 'hip' within the hospitalizations name.

JSON
{
  "self": "https://api.infermedica.com/api/mgp/v1/knowledge/hospitalizations?sex=male&language=en&query=hip&age.value=55&age.unit=year&cursor=0",
  "first": "https://api.infermedica.com/api/mgp/v1/knowledge/hospitalizations?sex=male&language=en&query=hip&age.value=55&age.unit=year&cursor=0",
  "prev": null,
  "next": null,
  "last": "https://api.infermedica.com/api/mgp/v1/knowledge/hospitalizations?sex=male&language=en&query=hip&age.value=55&age.unit=year&cursor=0",
  "items": [
    {
      "id": "p_321",
      "name": "Hip joint replacement"
    }
  ]
}
Fetching ResultsWebhooks