Autocompletion

Introduction

This API allows you to retrieve a list of medical entities corresponding to a query. Medical entities can be of different types (active ingredients, specialties, indications, contraindications, etc.) For all entities, when a text_preprocessed attribute is returned for a given concept, it is that attribute or a subpart of that attribute that matches the query, not necessarily the name. This attribute then corresponds to the preprocessed value of one of the concept or a synonym of this concept (for example, liver tumor can return liver tumor because liver tumor is a synonym).

Entry point

get/autocomplete-api/autocomplete

HTTP headers

Name	Value
`Content-Type`	`application/json`
`Authorization`	`Bearer <token>`

Query parameters

Name	type	Description
`query`	`string`	a character string containing the text to analyze required
`entity_type`	`string`	Type of entity to complete. `DRUG` by default. Can be: `ADVERSE_EFFECT` `BRANDED_DRUG` `CLINICAL_DRUG` `CLINICAL_INDICATION` `CONTRAINDICATION_TERRAIN` `DRUG` `INGREDIENT` `SPECIALTY`.
`k`	`number`	Number of candidates to return by entity type. `10` by default
`thresh`	`number`	Candidate similarity threshold. Removes candidates below the similarity threshold. `0.4` by default
`must_contain`	`boolean`	Forces candidates to contain a given substring (usually from a previous API call)
`type`	`List[string]`	When entity_type == “DRUG”, allows filtering the drug concept level among `BRANDED_DRUG`, `CLINICAL_DRUG`, `PACKAGED_DRUG`, `EXCIPIENT` and `INGREDIENT`, by default, all five levels are returned.

Request

GET

/autocomplete-api/autocomplete

curl --request GET\
   --url "https://api.preprod.posos.co/autocomplete-api/autocomplete?query=doliprane&entity_type=DRUG&k=10&thresh=0.4&drug_concept_levels=BRANDED_DRUG" \
   --header 'Authorization: Bearer <token>'

Response

{
  "query": "doliprane",
  "entity_type": "DRUG",
  "candidates": [
    {
      "id": "60950142",
      "name": "paracetamol 1 g tablet",
      "drug_concept_level": "CLINICAL_DRUG",
      "similarity": 0.88,
      "form": {
        "code": "PDF-10219000",
        "terminology": "edqm_forms",
        "label": "Compressed"
      },
      "text_preprocessed": "doliprane 1 g tablet",
      "ingredients": [
        {
          "designation": "paracetamol",
          "inn": null
        }
      ],
      "codings": {
        "medicabase": [
          {
            "terminology": "medicabase",
            "code": "MV00002414",
            "label": "Paracetamol 1 g tablet"
          }
        ],
        "posos": [
          {
            "terminology": "posos",
            "code": "MV00002414",
            "label": "PARACETAMOL ZENTIVA LAB 1 g, tablet"
          }
        ],
        "ATC4": [
          {
            "terminology": "ATC4",
            "code": "N02B",
            "label": "other analgesics and antipyretics"
          }
        ],
        "ATC5": [
          {
            "terminology": "ATC5",
            "code": "N02BE",
            "label": "anilides"
          }
        ],
        "ATC7": [
          {
            "terminology": "ATC7",
            "code": "N02BE01",
            "label": "paracetamol"
          }
        ],
        "branded_drug_source": [
          {
            "terminology": "branded_drug_source",
            "code": "60950142",
            "label": "PARACETAMOL ZENTIVA LAB 1 g, tablet"
          }
        ]
      }
    }
    // ...
  ]
}

Response format

The response is a JSON object containing the following attributes:

Name	Type	Description
`query`	`string`	The initial query
`entity_type`	`string`	The type of entity sought.
`candidates`	`array`	An array of medical entities matching the query. See the section Candidates

Candidates

A few attributes are common to all entity types:

Name	Type	Description
`id`	`string`	Unique identifier of the entity
`name`	`string`	Entity name
`similarity`	`number`	Similarity score between query and entity

Codings

Some types return an array of codings, including the following attributes:

Name	Type	Description
`code`	`string`	Coding code
`label`	`string`	Coding Name
`terminology`	`string`	Coding terminology (`snomed`, `meddra`, `cim10`, …)

The set of possible terminologies is:

Name	Related entity types	Description	External terminology
ATC4	`CLINICAL_DRUG`, `BRANDED_DRUG`	Chemical subgroup	✓
ATC5	`CLINICAL_DRUG`, `BRANDED_DRUG`	Chemical substance subgroup	✓
ATC7	`CLINICAL_DRUG`, `BRANDED_DRUG`	Chemical subgroup	✓
branded_drug_source	`CLINICAL_DRUG`	Information from a matching `BRANDED_DRUG` entity
cip7	`PACKAGED_DRUG`	7-digit Presentation Identifier Code	✓
cip13	`PACKAGED_DRUG`	13-digit Presentation Identifier Code, containing and replacing the 7-digit code, the prefix 3400 for French medicines, 9 for medicines with MA and ending with the control key	✓
cim10	`CLINICAL_INDICATION`, `CONTRAINDICATION_TERRAIN`, `ADVERSE_EFFECT`	International Classification of Diseases - Version 10	✓
inn	`INGREDIENT`	International Nonproprietary Names, uniquely identifies pharmaceutical substances or active pharmaceutical ingredients	✓
medicabase	`CLINICAL_DRUG`	Virtual drug repository, ID defined by MV followed by CIS	✓
medra	`CLINICAL_INDICATION`, `CONTRAINDICATION_TERRAIN`, `ADVERSE_EFFECT`	Medical Dictionary for Regulatory Activities	✓
nvd	`CLINICAL_DRUG`	Virtualizable drug identifier, defined by NV followed by CIS
Posos	`CLINICAL_DRUG`	Virtual drug identifier in our database. Corresponds to the medicabase id in the case of a virtual drug, or NVD for non-virtualizable drugs	✓
snomed	`CLINICAL_INDICATION`, `CONTRAINDICATION_TERRAIN`, `ADVERSE_EFFECT`, `INGREDIENT`, `EXCIPIENT`	Systematized Nomenclature of Medicine Clinical Terms	✓
ANSM substances	`INGREDIENT`	Name of the ingredient as written in the ANSM	✓
ucd7	`BRANDED_DRUG`, `PACKAGED_DRUG`	7-character Common Dispensing Unit	✓
ucd13	`BRANDED_DRUG`, `PACKAGED_DRUG`	13-character Common Dispensing Unit	✓

Codings example

{
  "snomed": [
    {
      "code": "363346000",
      "label": "malignant neoplasia",
      "terminology": "snomed"
    }
  ],
  "cim10": [
    {
      "code": "C80",
      "label": "Malignant tumor of unspecified location",
      "terminology": "cim10"
    }
  ],
  "meddra": [
    { "code": "10028997", "label": "Malignant tumor", "terminology": "meddra" }
  ]
}

By entity type

Here is the list of specific attributes returned for each entity type.

DRUG

Returns a list of drugs matching the query, regardless of whether the search is made in DCI or in originator (brand name).

By default contains both BRANDED_DRUG type entities, including the name of the brand under which it is marketed, of type CLINICAL_DRUG, corresponding to a virtual drug, of type PACKAGED_DRUG, corresponding to a drug presentation, of type INGREDIENT, corresponding to an INN, and of type EXCIPIENT.

To filter for one or more specific concept levels, add a combination of drug_concept_levels=CLINICAL_DRUG, drug_concept_levels=BRANDED_DRUG, drug_concept_levels=PACKAGED_DRUG, drug_concept_levels=EXCIPIENT and drug_concept_levels=INGREDIENT parameters, for example drug_concept_levels=CLINICAL_DRUG&drug_concept_levels=BRANDED_DRUG.

The resulting entities are sorted by entity type (10 entities per type by default) then in alphabetical order, to have the entities closest to the query, sort by similarity.

Example for a query with xeplion 150 (brand name of paliperidone):

Response

{
  "query": "xeplion 150",
  "entity_type": "DRUG",
  "candidates": [
    {
      "id": "64760254",
      "name": "XEPLION 150 mg, prolonged release suspension for injection",
      "drug_concept_level": "BRANDED_DRUG",
      "similarity": 0.84,
      "form": {
        "code": "PDF-11208500",
        "terminology": "edqm_forms",
        "label": "Sustained-release injectable suspension"
      },
      "ingredients": [
        {
          "designation": "paliperidone (palmitate)",
          "inn": "paliperidone"
        }
      ],
      "codings": {
        "ATC4": [
          {
            "code": "N05A",
            "label": "antipsychotics",
            "terminology": "ATC4"
          }
        ],
        "ATC5": [
          {
            "code": "N05AX",
            "label": "other antipsychotics",
            "terminology": "ATC5"
          }
        ],
        "ATC7": [
          {
            "code": "N05AX13",
            "label": "paliperidone",
            "terminology": "ATC7"
          }
        ],
        "UCD13": [
          {
            "code": "3400893873830",
            "label": "XEPLION 150MG INJ LP SRG",
            "terminology": "UCD13"
          }
        ],
        "UCD7": [
          {
            "code": "9387383",
            "label": "XEPLION 150MG INJ LP SRG",
            "terminology": "UCD7"
          }
        ]
      }
    },
    {
      "id": "65907383",
      "name": "paliperidone (palmitate) 150 mg prolonged-release suspension for injection in pre-filled syringe",
      "type": "CLINICAL_DRUG",
      "similarity": 0.84,
      "form": {
        "code": "PDF-11208500",
        "terminology": "edqm_forms",
        "label": "Sustained-release injectable suspension"
      },
      "ingredients": [
        {
          "designation": "paliperidone (palmitate)",
          "inn": "paliperidone"
        }
      ],
      "codings": {
        "medicabase": [
          {
            "terminology": "medicabase",
            "code": "MV00003658",
            "label": "Paliperidone (palmitate) 150 mg prolonged-release suspension for injection in pre-filled syringe"
          }
        ],
        "posos": [
          {
            "terminology": "posos",
            "code": "MV00003658",
            "label": "PALIPERIDONE BIOGARAN 150 mg, prolonged release injectable suspension in pre-filled syringe"
          }
        ],
        "ATC4": [
          {
            "terminology": "ATC4",
            "code": "N05A",
            "label": "antipsychotics"
          }
        ],
        "ATC5": [
          {
            "terminology": "ATC5",
            "code": "N05AX",
            "label": "other antipsychotics"
          }
        ],
        "ATC7": [
          {
            "terminology": "ATC7",
            "code": "N05AX13",
            "label": "paliperidone"
          }
        ],
        "branded_drug_source": [
          {
            "terminology": "branded_drug_source",
            "code": "65907383",
            "label": "PALIPERIDONE BIOGARAN 150 mg, prolonged release injectable suspension in pre-filled syringe"
          }
        ]
      }
    }
  ]
}

Name	Type	Description
`id`	`string`	Unique identifier of the entity.
`name`	`string`	Name of the drug.
`type`	`string`	Drug type (`BRANDED_DRUG`, `CLINICAL_DRUG` or `INGREDIENT`).
`similarity`	`number`	Similarity score between query and entity.
`form`	`object`	Galenic form information in EDQM terminology: ‘code’, `terminology` and `label`. Missing for `type=INGREDIENT`
`ingredients`	`array`	List of drug ingredients, with `designation` and `inn` attributes (see `Codings`)
`codings`	`Codings`	Drug coding
`text_preprocessed`	`string`	Preprocessed text to match the drug to the query
`availability_alert`	`string`	Out of stock information, only for the type `BRANDED_DRUG`.
`labelled_strength`	`string`	Drug dosis.
`strength`	`string`	Structured drug dosis.

ADVERSE_EFFECT

Returns a list of adverse effects matching the query.

Response

{
  "query": "trembling",
  "entity_type": "ADVERSE_EFFECT",
  "candidates": [
    {
      "id": "6a8f4208fc762a36785c9fd5ad6e5903c5f7fb51ba3e4e2d71cf7b2758c9afbd",
      "name": "tremor",
      "type": "ADVERSE_EFFECT",
      "similarity": 1.0,
      "codings": {
        "snomed": [
          {
            "terminology": "snomed",
            "code": "26079004",
            "label": "tremor"
          }
        ],
        "cim10": [
          {
            "terminology": "cim10",
            "code": "R251",
            "label": "Trembling, unspecified"
          }
        ],
        "meddra": [
          {
            "terminology": "meddra",
            "code": "10044562",
            "label": "Trembling"
          }
        ]
      }
    },
    {
      "id": "d0b42330cbefe2498dcfaa082d84160be32cc040254c34efaeebe7e6098317a1",
      "name": "trembling hands",
      "type": "ADVERSE_EFFECT",
      "similarity": 0.951,
      "codings": {
        "meddra": [
          {
            "terminology": "meddra",
            "code": "10044577",
            "label": "Hands tremor"
          }
        ],
        "snomed": [
          {
            "terminology": "snomed",
            "code": "26079004",
            "label": "tremor"
          }
        ],
        "cim10": [
          {
            "terminology": "cim10",
            "code": "R251",
            "label": "Trembling, unspecified"
          }
        ]
      }
    }
  ]
}

SPECIALTY

This entity is deprecated and will be replaced by DRUG with drug_concept_levels=CLINICAL_DRUG

Returns a list of medicinal specialties corresponding to the query.

Response

{
  "query": "doliprane",
  "entity_type": "SPECIALTY",
  "candidates": [
    {
      "dci": ["paracetamol"],
      "id": "fd07dc89b0e39daad0affc90ed125567d5183a1c1f24299c15017280c773b187::drug",
      "name": "DOLIPRANE 150 mg, suppository",
      "similarity": 1,
      "text_preprocessed": "doliprane 150 mg, suppository",
      "dose": "150 mg",
      "form": "suppository",
      "atc": {
        "code": "N02BE01",
        "label": "paracetamol"
      },
      "atc_parent": {
        "code": "N02BE",
        "label": "anilides"
      },
      "clinical_drug_id": "MV00001654",
      "shortname": "doliprane"
    }
    // ...
  ]
}

Name	Type	Description
`dci`	`array`	List of drug INNs.
`dose`	`string`	Dose of the drug.
`form`	`string`	Form of the medicine.
`atc`	`object`	ATC code of the drug.
`atc.code`	`string`	ATC code of the drug.
`atc.label`	`string`	ATC label of the medicine.
`atc_parent`	`object`	Parent ATC code of the drug.
`atc_parent.code`	`string`	Parent ATC code of the drug.
`atc_parent.label`	`string`	Parent ATC label of the drug.
`clinical_drug_id`	`string`	Virtual drug identifier in the medicabase database.
`shortname`	`string`	Name of the drug.

CLINICAL_INDICATION

Name	type	Description
`name`	`string`	Name of indication
`codings`	`Codings`	Coding of the indication

Response

{
  "query": "liver tumor",
  "entity_type": "CLINICAL_INDICATION",
  "candidates": [
    {
      "id": "a2bdf4507eaed9e9f4db734b18f0794ccbe08cb84993bac45372adbc73ac5efd",
      "type": "CLINICAL_INDICATION",
      "name": "hepatocellular cancer",
      "similarity": 0.944,
      "text_preprocessed": "hepatocellular cancer liver tumor",
      "codings": {
        "meddra": [
          {
            "terminology": "meddra",
            "code": "10073071",
            "label": "Hepatocellular carcinoma"
          }
        ],
        "snomed": [
          {
            "terminology": "snomed",
            "code": "126851005",
            "label": "liver tumor"
          }
        ],
        "cim10": [
          {
            "terminology": "cim10",
            "code": "C220",
            "label": "Hepatocellular carcinoma"
          }
        ]
      }
    }
    // ...
  ]
}

LAND_CONTRAINDICATION

Apart from the recurring attributes id, type, name, similarity and text_preprocessed, the results contain the attributes origin, codings and terminology.

Name	type	Description
`origin`	`string`	Field Origin: `contraindication.condition.normalised_designation`, `contraindication.patient_criterion.adjunct_treatment.procedures`, `contraindication.patient_criterion.age_group`, `contraindication.patient_criterion.gender`
`terminology`	`string`	Field terminology: `contra_indication`, `meddra_procedures`, `age_group`, `gender`

So if you want to filter terrains by type, you must use the origin attribute.

Example of a query with the word woman:

Response

{
  "query": "woman",
  "entity_type": "CONTRAINDICATION_TERRAIN",
  "candidates": [
    {
      "id": "Woman",
      "type": "CONTRAINDICATION_TERRAIN",
      "name": "Woman",
      "origin": "contraindication.patient_criterion.gender",
      "similarity": 1,
      "text_preprocessed": "woman",
      "terminology": "gender",
      "codings": {}
    },
    {
      "id": "5cb1f1937e6b686d5374097364c09323ad44bac43248e8d93e33fc59bffb9ad1",
      "type": "CONTRAINDICATION_TERRAIN",
      "name": "Nulliparous woman",
      "origin": "contraindication.condition.normalised_designation",
      "similarity": 0.87,
      "text_preprocessed": "nulliparous woman",
      "terminology": "contra_indications",
      "codings": {
        "snomed": [
          {
            "code": "10029827",
            "label": "Nulliparous",
            "terminology": "meddra"
          },
          {
            "code": "102877006",
            "label": "pregnant wife",
            "terminology": "snomed"
          }
        ]
      }
    }
    // ...
  ]
}

Response codes

Code	Description
`200`
`400`	One of the parameters passed in the request is invalid

Conciliation Médicamenteuse Dosage structuring