NERL

Introduction

Cette API permet d’extraire et de lier des entités médicales à partir d’un texte, notamment des prescriptions médicales. Elle identifie les médicaments, posologies, indications, effets indésirables et d’autres entités médicales, puis les associe à des codes standardisés provenant de différentes terminologies médicales.

Point d’entrée

get/nerl/v2/nerl

En-têtes HTTP

Nom	Valeur
`Content-Type`	`application/json`
`Authorization`	`Bearer <token>`

Paramètres de requête

Nom	Type	Description
`query`	`string`	Texte à analyser pour l’extraction d’entités. Requis
`n_codes`	`number`	Nombre d’entités à renvoyer pour chaque type. `3` par défaut.
`medical_database`	`string`	Base de données médicale à utiliser. `medical_db` renvoie des entités DRUG de terminologie SHORTNAME ou INGREDIENT. `posos_medicaldb` renvoie des entités DRUG de terminologie BRAND_DRUG ou INN.
`realm`	`string`	Domaine d’application. Par défaut `default`.
`countries`	`string`	Pays des médicaments à renvoyer. `all` ou `france`. Par défaut `all`.
`lang`	`string`	Langue de la requête. `fr`, `de` ou `en`. Par défaut `fr`.
`detect_frequency`	`boolean`	Si `true`, recherche les fréquences connues de MEDDRA. Par défaut `true`.
`detect_posology`	`boolean`	Si `true`, applique des règles pour extraire les entités de posologie. Par défaut `false`.
`detect_administrative`	`boolean`	Si `true`, applique des règles manuelles pour extraire les entités administratives d’une prescription. Par défaut `false`.
`detect_patient_info`	`boolean`	Si `true`, applique des règles manuelles pour extraire les informations patient (âge, poids, taille). Par défaut `false`.
`detect_only_posology`	`boolean`	Si `true`, n’extrait que les entités de posologie. Par défaut `false`.
`detect_medical_device`	`boolean`	Si `true`, active la détection des dispositifs médicaux associés à un code. Par défaut `false`.
`include_recently_unmarketed`	`boolean`	Si `true`, inclut les médicaments récemment retirés du marché. Par défaut `false`.
`exclude_hospital_drugs`	`boolean`	Si `true`, exclut les médicaments réservés à l’usage hospitalier. Par défaut `false`.
`drug_similarity_threshold`	`number`	Seuil de similarité cosinus pour filtrer les codages DRUG. Par défaut `0`.
`debug`	`boolean`	Si `true`, ajoute les attributs `strengths` et `description` aux résultats. Par défaut `false`.
`reliability`	`boolean`	Si `true`, renvoie la fiabilité de la structuration de la posologie. Par défaut `true`.
`disable_cache`	`boolean`	Si `true`, désactive le cache. Par défaut `false`.

Request

GET

/nerl/v2/nerl

curl --request GET \
  --url "https://api.preprod.posos.co/nerl/v2/nerl?query=doliprane%201000mg%201%20comprim%C3%A9%203%20fois%20par%20jour&n_codes=3&lang=fr&detect_posology=true" \
  --header 'Authorization: Bearer <token>'

Output

{
  "query": "doliprane 1000mg 1 comprimé 3 fois par jour",
  "preprocessed_query": "doliprane 1000mg 1 comprimé 3 fois par jour",
  "posology_string": "1 comprimé 3 fois par jour",
  "posology_display_string": "1 comprimé, 3 fois par jour",
  "entities": [
    {
      "begin_offset": 0,
      "end_offset": 16,
      "designation": "doliprane 1000mg",
      "entity_type": "DRUG",
      "category": "MEDICATION",
      "codings": {
        "SHORTNAME": [
          {
            "code": "doliprane",
            "cosine_similarity": 0.95,
            "label": "DOLIPRANE",
            "terminology": "SHORTNAME",
            "marketed": true,
            "ingredients": ["paracétamol"]
          }
        ],
        "INGREDIENT": [
          {
            "code": "paracetamol",
            "cosine_similarity": 0.92,
            "label": "paracétamol",
            "terminology": "INGREDIENT"
          }
        ]
      },
      "strength": [
        {
          "value": 1000,
          "unit": "mg",
          "code": "mg",
          "system": "https://ucum.org",
          "type": "STRENGTH"
        }
      ]
    },
    {
      "begin_offset": 17,
      "end_offset": 28,
      "designation": "1 comprimé",
      "entity_type": "QUANTITY",
      "category": "FREQUENCY",
      "quantity_and_rate": {
        "value": 1,
        "unit": "comprimé",
        "type": "DOSE"
      }
    },
    {
      "begin_offset": 29,
      "end_offset": 43,
      "designation": "3 fois par jour",
      "entity_type": "FREQUENCY",
      "category": "FREQUENCY",
      "timing": {
        "frequency": 3,
        "period": 1,
        "period_unit": "d"
      }
    }
  ],
  "structuration_reliability": 0.95
}

Format de la réponse

La réponse est un objet JSON de type NERLResponse contenant les attributs suivants :

Nom	Type	Description
`query`	`string`	La requête initiale.
`preprocessed_query`	`string`	La requête après prétraitement.
`posology_string`	`string \| null`	La chaîne de posologie extraite.
`posology_display_string`	`string \| null`	La chaîne de posologie formatée pour l’affichage.
`entities`	`array`	Tableau d’entités extraites. Voir la section NERLEntity.
`manual_entities_list`	`array \| null`	Liste des entités manuellement définies.
`age_groups`	`array \| null`	Groupes d’âge détectés dans la requête.
`administrative`	`object \| null`	Informations administratives extraites (requérant, date).
`observations`	`array \| null`	Observations extraites (âge, poids, taille du patient).
`structuration_reliability`	`number \| null`	Score de fiabilité de la structuration de la posologie (entre 0 et 1).

NERLEntity

Chaque entité extraite contient les attributs suivants :

Nom	Type	Description
`begin_offset`	`number`	Position de début de l’entité dans la requête.
`end_offset`	`number`	Position de fin de l’entité dans la requête.
`designation`	`string`	Texte de l’entité dans la requête.
`entity_type`	`string`	Type de l’entité. Voir Types d’entités.
`category`	`string`	Catégorie de l’entité : `CONDITION`, `FREQUENCY`, `MEDICATION`, `PATIENT_CRITERION`, `PATIENT_INFORMATION`.
`codings`	`object \| null`	Dictionnaire de codages par terminologie. Voir Codings.
`quantity_and_rate`	`QuantityOrRate`	Quantité ou taux associé à l’entité (pour les entités de type `QUANTITY`).
`strength`	`array \| null`	Liste des dosages structurés (pour les entités de type `DRUG`).
`timing`	`NERLTiming`	Informations de fréquence structurées (pour les entités de type `FREQUENCY`).
`as_needed`	`object \| null`	Indique si la prise est “si besoin” et pour quelle raison.
`max_dose_per_period`	`object \| null`	Dose maximale par période.
`observation`	`object \| null`	Observation patient (âge, poids, taille, IMC).
`substitution`	`object \| null`	Informations de substitution (autorisée ou non, raison).
`marketing_authorization_holder`	`object \| null`	Titulaire de l’autorisation de mise sur le marché.

Types d’entités

Type	Description
`ADMINISTRATIVE`	Entité administrative (numéro de prescription, date, etc.)
`BOUNDS`	Bornes temporelles
`BRANDED_DRUG`	Médicament de marque
`BRANDED_CLINICAL_DRUG`	Médicament virtuel de marque
`CLINICAL_DRUG`	Médicament virtuel
`CODIFICATION`	Codification
`CONDITION`	Condition médicale
`CONTINUOUS_CRITERION`	Critère continu patient
`DOSE_UNIT`	Unité de dose
`DRUG`	Médicament
`DURATION_INTAKE`	Durée de prise
`FORM`	Forme galénique
`FREQUENCY`	Fréquence de prise
`LAB`	Laboratoire
`MAX_QUANTITY`	Quantité maximale
`MEDICAL_DEVICE`	Dispositif médical
`CODED_MEDICAL_DEVICE`	Dispositif médical codé
`OBSERVATION`	Observation patient
`PATHWAY`	Voie d’administration
`PERIOD`	Période
`QUANTITY`	Quantité
`REASON`	Raison
`SUBSTITUTION`	Substitution
`TIMING`	Timing
`WHEN`	Moment de prise

Codings

Les codages associent les entités à des terminologies médicales standardisées. Chaque terminologie est une clé du dictionnaire codings, et la valeur est un tableau de candidats de type TerminologyCandidate.

Nom	Type	Description
`code`	`string`	Code du candidat dans la terminologie.
`cosine_similarity`	`number`	Score de similarité cosinus entre l’entité et le candidat.
`label`	`string`	Libellé du candidat.
`terminology`	`string`	Nom de la terminologie.
`countries`	`array`	Pays où le médicament est disponible (pour les terminologies DRUG).
`marketed`	`boolean`	Indique si le médicament est commercialisé.
`hospital_only`	`boolean`	Indique si le médicament est réservé à l’usage hospitalier.
`inn`	`string`	Dénomination commune internationale.
`ingredients`	`array`	Liste des ingrédients du médicament.
`severity`	`string`	Sévérité (pour les effets indésirables) : `LIGHT`, `MODERATE`, `SEVERE`.

Les terminologies disponibles incluent :

Terminologie	Description
`SHORTNAME`	Nom court du médicament
`INGREDIENT`	Principe actif
`BRANDED_DRUG`	Médicament de marque
`CLINICAL_DRUG`	Médicament virtuel
`INN`	Dénomination commune internationale
`INDICATION`	Indication thérapeutique
`SIDE_EFFECT`	Effet secondaire
`ADVERSE_EFFECT`	Effet indésirable
`CONTRAINDICATION`	Contre-indication
`EXCIPIENT`	Excipient
`FREQUENCY`	Fréquence de prise
`FORM`	Forme galénique
`MEDICAL_DEVICE`	Dispositif médical

QuantityOrRate

Nom	Type	Description
`value`	`number`	Valeur numérique de la quantité.
`max_value`	`number`	Valeur maximale (si plage).
`unit`	`string`	Unité de mesure.
`code`	`string`	Code de l’unité (UCUM).
`system`	`string`	Système de codification de l’unité (`https://ucum.org`).
`type`	`string`	Type de quantité : `DOSE`, `QUANTITY`, `STRENGTH`.
`rate`	`object`	Taux (numérateur/dénominateur) pour les dosages complexes.

NERLTiming

Nom	Type	Description
`frequency`	`number`	Nombre de prises par période.
`frequency_max`	`number`	Nombre maximum de prises par période.
`period`	`number`	Durée de la période.
`period_max`	`number`	Durée maximale de la période.
`period_unit`	`string`	Unité de la période (`s`, `min`, `h`, `d`, `wk`, `mo`, `a`).
`count`	`number`	Nombre total de prises.
`count_max`	`number`	Nombre maximum total de prises.
`duration`	`number`	Durée de la prise.
`duration_unit`	`string`	Unité de durée.
`duration_max`	`number`	Durée maximale.
`bounds_duration`	`object`	Durée bornée de traitement.
`bounds_period`	`object`	Période bornée (date de début et fin).
`number_repeats_allowed`	`number`	Nombre de renouvellements autorisés.
`time_of_day`	`array`	Heures de prise dans la journée.
`day_of_week`	`array`	Jours de prise dans la semaine.
`sequence`	`number`	Numéro de séquence pour les posologies alternées.
`when`	`array`	Moments de prise : `AC` (avant repas), `PC` (après repas), etc.
`offset`	`string`	Décalage par rapport au moment de prise.

Codes de réponse

Code	Description
`200`	Succès
`400`	Un des paramètres passés dans la requête est invalide
`401`	Non autorisé - Token manquant ou invalide

Reconstruction de posologie Structuration de prescription (PREVIEW)