Ressources

Paramètres de recherche

L'API FHIR V1 est dépréciée et sera prochainement décommissionnée. Nous vous encourageons à passer sur la version 2 de l'API FHIR.

Lien vers la spécification FHIR : https://hl7.org/FHIR/search.html

Paramètres de recherche disponibles
Paramètres de type texte
Paramètres de type token
Paramètres de type date
Paramètres combinés
- Paramètre ET
- Paramètre OU
Paramètres des résultats

1) Paramètres de recherche disponibles

Pour afficher les paramètres de recherche pris en charge par l’API, vous pouvez interroger le CapabilityStatement.

Requête :

GET [base]/metadata

2) Paramètres de type texte (string)

Les recherchers de type texte peuvent s’effectuer sur les différentes ressources disponibles.

2.1) Recherche sans “modifier”

Requête :

GET [base]/Organization?name=Renard

Réponse (simplifiée) :

HTTP 200 OK
  resourceType: Bundle
  type: searchset
  Organization found: name=Renard et Renard
  Organization found: name=Renard SCOP
  Organization found: name=Renard EURL

Exemples de code :

curl -H "ESANTE-API-KEY: XXXX-XXXX-XXXX-XXXXX" "https://gateway.api.esante.gouv.fr/fhir/v1/Organization?name=Renard"

// create the client:
var client = FhirTestUtils.createClient();

// create the name search parameter :
var matchSearchClause = Organization.NAME.matches().value("Renard");

var bundle = client.search()
        .forResource(Organization.class)
        .where(matchSearchClause)
        .returnBundle(Bundle.class).execute();

for (var organizationEntry : bundle.getEntry()) {
    // cast entry :
    var organization = (Organization) organizationEntry.getResource();
    // print data :
    logger.info("Organization found: name={}", organization.getName());
}

$response = $client->request('GET', '/fhir/v1/Organization?name=Renard');
/** @var  $organizations  \DCarbone\PHPFHIRGenerated\R4\FHIRResource\FHIRBundle*/
$organizations = $parser->parse((string) $response->getBody());
foreach($organizations->getEntry() as $entry){
    /** @var  $organization  \DCarbone\PHPFHIRGenerated\R4\FHIRResource\FHIRDomainResource\FHIROrganization */
    $organization = $entry->getResource();

    echo("Organization found: name=".$organization->getName()."\n");
}

// create the client:
var client = FhirTestUtils.CreateClient();
// create the name search parameter :
var q = new SearchParams()
  .Where("name=Renard")
  .LimitTo(50);
var bundle = client.Search<Organization>(q);
foreach (var be in bundle.Entry)
{
    // print ids:
    var organization = be.Resource as Organization;
    Console.WriteLine($"Organization found: name={organization.Name}");
}

2.2) Recherche avec le “modifier” “contains”

A la différence du modifier “exact”, les performances constatées en utilisant le modifier contains et deux mots ne répondent pas dans les 30 secondes.

Requête :

GET [base]/Organization?name%3Acontains=EURL

Réponse (simplifiée) :

HTTP 200 OK
  resourceType: Bundle
  type: searchset
  Organization found: name=Perez EURL
  Organization found: name=Gautier EURL

Exemples de code :

curl -H "ESANTE-API-KEY: XXXX-XXXX-XXXX-XXXXX" "https://gateway.api.esante.gouv.fr/fhir/v1/Organization?name%3Acontains=EURL"

// create the client:
var client = FhirTestUtils.createClient();

// create the name search parameter :
var containsSearchClause = Organization.NAME.contains().value("EURL");

var bundle = client.search()
.forResource(Organization.class)
.where(containsSearchClause)
.returnBundle(Bundle.class).execute();

for (var organizationEntry : bundle.getEntry()) {
// cast entry :
var organization = (Organization) organizationEntry.getResource();
// print data :
logger.info("Organization found: name={}", organization.getName());
}

$response = $client->request('GET', '/fhir/v1/Organization?name%3Acontains=EURL');
/** @var  $organizations  \DCarbone\PHPFHIRGenerated\R4\FHIRResource\FHIRBundle*/
$organizations = $parser->parse((string) $response->getBody());
foreach($organizations->getEntry() as $entry){
    /** @var  $organization  \DCarbone\PHPFHIRGenerated\R4\FHIRResource\FHIRDomainResource\FHIROrganization */
    $organization = $entry->getResource();

    echo("Organization found: name=".$organization->getName()."\n");
}

// create the client:
var client = FhirTestUtils.CreateClient();
// create the name search parameter :
var q = new SearchParams()
  .Where("name:contains=EURL")
  .LimitTo(50);
var bundle = client.Search<Organization>(q);
foreach (var be in bundle.Entry)
{
    // print ids:
    var organization = be.Resource as Organization;
    Console.WriteLine($"Organization found: name={organization.Name}");
}

2.3) Recherche avec le “modifier” “exact”

Requête :

GET [base]/Organization?name%3Aexact=Gautier%20EURL

Réponse (simplifiée) :

HTTP 200 OK
  resourceType: Bundle
  type: searchset
  Organization found: id=org-183 name=Gautier EURL
  Organization found: id=org-358 name=Gautier EURL

Exemples de code :

curl -H "ESANTE-API-KEY: XXXX-XXXX-XXXX-XXXXX" "https://gateway.api.esante.gouv.fr/fhir/v1/Organization?name%3Aexact=Gautier%20EURL"

// create the client:
var client = FhirTestUtils.createClient();

// create the name search parameter :
var exactSearchClause = Organization.NAME.matchesExactly().value("Gautier EURL");

var bundle = client.search()
        .forResource(Organization.class)
        .where(exactSearchClause)
        .returnBundle(Bundle.class).execute();

for (var organizationEntry : bundle.getEntry()) {
    // cast entry :
    var organization = (Organization) organizationEntry.getResource();
    // print data :
    logger.info("Organization found: id={} name={}", organization.getIdElement().getIdPart(), organization.getName());
}

$response = $client->request('GET', '/fhir/v1/Organization?name%3Aexact=Gautier%20EURL');
/** @var  $organizations  \DCarbone\PHPFHIRGenerated\R4\FHIRResource\FHIRBundle*/
$organizations = $parser->parse((string) $response->getBody());
foreach($organizations->getEntry() as $entry){
    /** @var  $organization  \DCarbone\PHPFHIRGenerated\R4\FHIRResource\FHIRDomainResource\FHIROrganization */
    $organization = $entry->getResource();

    echo("Organization found: id=".$organization->getId()." name=".$organization->getName()."\n");
}

// create the client:
var client = FhirTestUtils.CreateClient();
// create the name search parameter :
var q = new SearchParams()
  .Where("name:exact=Gautier EURL")
  .LimitTo(50);
var bundle = client.Search<Organization>(q);
foreach (var be in bundle.Entry)
{
    // print ids:
    var organization = be.Resource as Organization;
    Console.WriteLine($"Organization found: id={organization.IdElement.Value} name={organization.Name}");
}

3) Paramètres de type token

Le serveur supporte la recherche par code, par système ou par les deux.

Recherche par code

Requête :

GET [base]/Organization?identifier=org-org-148

Réponse (simplifiée) :

HTTP 200 OK
  resourceType: Bundle
  type: searchset
  Organization found: id=org-148 name=Renard et Renard

Exemples de code :

curl -H "ESANTE-API-KEY: XXXX-XXXX-XXXX-XXXXX" "https://gateway.api.esante.gouv.fr/fhir/v1/Organization?identifier=org-org-148"

// create the client:
var client = FhirTestUtils.createClient();

// create the name search parameter :
var tokenSearchClause = Organization.IDENTIFIER.exactly().code("org-org-148");

var bundle = client.search()
.forResource(Organization.class)
.where(tokenSearchClause)
.returnBundle(Bundle.class).execute();

for (var organizationEntry : bundle.getEntry()) {
// cast entry :
var organization = (Organization) organizationEntry.getResource();
// print data :
logger.info("Organization found: id={} name={}", organization.getIdElement().getIdPart(), organization.getName());
}

$response = $client->request('GET', '/fhir/v1/Organization?identifier=org-org-148');
/** @var  $organizations  \DCarbone\PHPFHIRGenerated\R4\FHIRResource\FHIRBundle*/
$organizations = $parser->parse((string) $response->getBody());
foreach($organizations->getEntry() as $entry){
    /** @var  $organization  \DCarbone\PHPFHIRGenerated\R4\FHIRResource\FHIRDomainResource\FHIROrganization */
    $organization = $entry->getResource();

    echo("Organization found: id=".$organization->getId()." name=".$organization->getName()."\n");
}

// create the client:
var client = FhirTestUtils.CreateClient();
// create the name search parameter :
var q = new SearchParams()
  .Where("identifier=org-org-148")
  .LimitTo(50);
var bundle = client.Search<Organization>(q);
foreach (var be in bundle.Entry)
{
    // print ids:
    var organization = be.Resource as Organization;
    Console.WriteLine($"Organization found: id={organization.IdElement.Value} name={organization.Name}");
}

4) Paramètres de type date

La recherche par date supporte les préfixes suivants:

Préfix	Nom	Description
eq	equal	La valeur du paramètre dans la ressource est égale à la valeur saisie
ne	not equal	La valeur du paramètre dans la ressource n’est pas égale à la valeur saisie
gt	greater	La valeur du paramètre dans la ressource est supérieure à la valeur saisie
lt	less	La valeur du paramètre dans la ressource est inférieure à la valeur saisie
ge	greater or equal	La valeur du paramètre dans la ressource est supérieure ou égale à la valeur saisie
le	less or equal	La valeur du paramètre dans la ressource est inférieure ou égale à la valeur saisie
sa	starts after	La valeur du paramètre dans la ressource démarre après la valeur saisie
eb	ends before	La valeur du paramètre dans la ressource termine avant la valeur saisie
ap	approximately	La valeur du paramètre dans la ressource est approximativement la même que la valeur fournie. Il est à noter que la valeur recommandée pour l’approximation est de 10% de la valeur indiquée

Plus d’informations sur les [dates] (https://build.fhir.org/search.html#date)

Plusiseurs “précisions” sont supportées : yyyy par année, yyyy-MM-dd par jour, et par date complète.

Quelques exemples :

_lastUpdated=gt2020 : après 2020
_lastUpdated=ge2020 : 2020 et après (2020 inclus)
_lastUpdated=lt2022-12-15 : avant le 15 décembre 2022 exclus
_lastUpdated=lt2022-12-15T15:00:00 : avant le 15 décembre 2022 15h (GMT)
_lastUpdated=eq2021 : durant l’année 2021

Requête :

GET [base]/Organization?_lastUpdated=ge2022-08-05T14%3A51%3A04

Réponse (simplifiée) :

HTTP 200 OK
  resourceType: Bundle
  type: searchset
  Organization found: id=org-148 lastUpdate=Fri Aug 05 14:51:03 CEST 2022
  Organization found: id=org-149 lastUpdate=Fri Aug 05 14:51:03 CEST 2022
  Organization found: id=org-144 lastUpdate=Fri Aug 05 14:51:03 CEST 2022
  Organization found: id=org-386 lastUpdate=Fri Aug 05 14:51:03 CEST 2022
  Organization found: id=org-145 lastUpdate=Fri Aug 05 14:51:03 CEST 2022

Exemples de code :

curl -H "ESANTE-API-KEY: XXXX-XXXX-XXXX-XXXXX" "https://gateway.api.esante.gouv.fr/fhir/v1/Organization?_lastUpdated=ge2022-08-05T14%3A51%3A04"

// create the client:
var client = FhirTestUtils.createClient();

// create the date search parameter :
var dateParam = new DateClientParam("_lastUpdated");

var bundle = client.search()
.forResource(Organization.class)
.where(dateParam.afterOrEquals().second("2022-08-05T14:51:04"))
.returnBundle(Bundle.class).execute();

for(var organizationEntry : bundle.getEntry()){
// cast entry :
var organization = (Organization) organizationEntry.getResource();
// print update date & id :
logger.info("Organization found: id={} lastUpdate={}", organization.getIdElement().getIdPart(), organization.getMeta().getLastUpdated());
}

$response = $client->request('GET', '/fhir/v1/Organization?_lastUpdated=ge2022-08-05T14%3A51%3A04');
/** @var  $organizations  \DCarbone\PHPFHIRGenerated\R4\FHIRResource\FHIRBundle*/
$organizations = $parser->parse((string) $response->getBody());
foreach($organizations->getEntry() as $entry){
    /** @var  $organization  \DCarbone\PHPFHIRGenerated\R4\FHIRResource\FHIRDomainResource\FHIROrganization */
    $organization = $entry->getResource();

    echo("Organization found: id=".$organization->getId()." lastUpdate=".$organization->getMeta()->getLastUpdated()."\n");
}

// create the client:
var client = FhirTestUtils.CreateClient();
// create the name search parameter :
var q = new SearchParams()
  .Where("_lastUpdated=ge2022-08-05T14:51:04")
  .LimitTo(50);
var bundle = client.Search<Organization>(q);
foreach (var be in bundle.Entry)
{
    // print ids:
    var organization = be.Resource as Organization;
    Console.WriteLine($"Organization found: id={organization.IdElement.Value} lastUpdate={organization.Meta.LastUpdated.Value}");
}

7) Paramètres combinés

Les paramètres combinés permettent d’effectuer des recherches en les cumulant. Ce cumul se fait de manière inclusive ou alternative.

7.1) Paramètres ET (AND)

Requête :

GET [base]/Organization?name%3Acontains=Renard&name%3Acontains=et

Réponse (simplifiée) :

HTTP 200 OK
  resourceType: Bundle
  type: searchset
  Organization found: id=org-148 | name=Renard et Renard
  Organization found: id=org-176 | name=Renard et Renard
Organization found: id=org-128 | name=Renard et Renard

Exemples de code:

curl -H# "ESANTE-API-KEY: XXXX-XXXX-XXXX-XXXXX" "https://gateway.api.esante.gouv.fr/fhir/v1/Organization?name%3Acontains=Renard&name%3Acontains=et"

// create the client:
var client = FhirTestUtils.createClient();

// create the two name search parameters :
var firstSearchClause = Organization.NAME.contains().value("Renard");
var secondSearchClause = Organization.NAME.contains().value("et");

var bundle = client.search()
        .forResource(Organization.class)
        .where(firstSearchClause)
        .and(secondSearchClause)
        .returnBundle(Bundle.class).execute();

for (var organizationEntry : bundle.getEntry()) {
    // cast entry :
    var organization = (Organization) organizationEntry.getResource();
    // print data :
    logger.info("Organization found: id={} | name={}", organization.getIdElement().getIdPart(), organization.getName());
}

$response = $client->request('GET', '/fhir/v1/Organization?name%3Acontains=Renard&name%3Acontains=et');
/** @var  $organizations  \DCarbone\PHPFHIRGenerated\R4\FHIRResource\FHIRBundle*/
$organizations = $parser->parse((string) $response->getBody());
foreach($organizations->getEntry() as $entry){
    /** @var  $organization  \DCarbone\PHPFHIRGenerated\R4\FHIRResource\FHIRDomainResource\FHIROrganization */
    $organization = $entry->getResource();

    echo("Organization found: id=".$organization->getId()." | name=".$organization->getName()."\n");
}

// create the client:
var client = FhirTestUtils.CreateClient();
// create the name search parameter :
var q = new SearchParams()
  .Where("name:contains=Renard").Add("name:contains", "et")
  .LimitTo(50);
var bundle = client.Search<Organization>(q);
foreach (var be in bundle.Entry)
{
    // print ids:
    var organization = be.Resource as Organization;
    Console.WriteLine($"Organization found: id={organization.IdElement.Value} | name={organization.Name}");
}

7.2) Paramètres OU (OR)

Requête :

GET [base]/Organization?name%3Acontains=Renard%2Cet

Réponse (simplifiée) :

HTTP 200 OK
  resourceType: Bundle
  type: searchset
  Organization found: id=org-148 | name=Renard et Renard
  Organization found: id=org-386 | name=Lopez et Lopez
  Organization found: id=org-145 | name=Maillard et Maillard

Exemples de code:

curl -H "ESANTE-API-KEY: XXXX-XXXX-XXXX-XXXXX" "https://gateway.api.esante.gouv.fr/fhir/v1/Organization?name%3Acontains=Renard%2Cet"

// create the client:
var client = FhirTestUtils.createClient();

// create the two name search parameters :
var orSearchClause = Organization.NAME.contains().values("Renard", "et");

var bundle = client.search()
        .forResource(Organization.class)
        .where(orSearchClause)
        .returnBundle(Bundle.class).execute();

for (var organizationEntry : bundle.getEntry()) {
    // cast entry :
    var organization = (Organization) organizationEntry.getResource();
    // print data :
    logger.info("Organization found: id={} | name={}", organization.getIdElement().getIdPart(), organization.getName());
}

$response = $client->request('GET', '/fhir/v1/Organization?name%3Acontains=Renard%2Cet');
/** @var  $organizations  \DCarbone\PHPFHIRGenerated\R4\FHIRResource\FHIRBundle*/
$organizations = $parser->parse((string) $response->getBody());
foreach($organizations->getEntry() as $entry){
    /** @var  $organization  \DCarbone\PHPFHIRGenerated\R4\FHIRResource\FHIRDomainResource\FHIROrganization */
    $organization = $entry->getResource();

    echo("Organization found: id=".$organization->getId()." | name=".$organization->getName()."\n");
}

// create the client:
var client = FhirTestUtils.CreateClient();
// create the name search parameter :
var q = new SearchParams()
  .Where("name:contains=Renard,et")
  .LimitTo(50);
var bundle = client.Search<Organization>(q);
foreach (var be in bundle.Entry)
{
    // print ids:
    var organization = be.Resource as Organization;
    Console.WriteLine($"Organization found: id={organization.IdElement.Value} | name={organization.Name}");
}

8) Paramètres des résultats de la recherche

Il s’agit d’un ensemble de paramètres permettant de gérer les résultats retournés par une recherche. Vous trouverez ci-dessous la liste des paramètres de résultats de recherche pris en charge dans notre contexte.

8.1) Paramètre “_count”

Il permet de contrôler le nombre maximal de ressources retournées sur une page lorsqu’une réponse de l’API est paginée. Par exemple, _count=10 renvoie un maximum de 10 ressources. La valeur par défaut est 50.

Requête:

GET [base]/Device?_count=200

8.2) Paramètre “_total”

Comme son nom l’indique, ce paramètre indique le nombre total d’éléments (ressources) qui correspondent aux critères de recherche. Ce paramètre peut prendre 3 valeurs : none, estimate ou accurate.

none : le total n’est pas affiché
estimate : le total affiché est une estimation
accurate : le total affiché est précis

Cet exemple montre comment utiliser le paramètre _total=none pour ne pas afficher le total :

Requête:

GET [base]/Device?_total=none

Par défaut, l’affichage (ou pas) du total dépend principalement du temps nécessaire à son calcul. Ainsi, si le temps de calcul est trop important, le total ne sera pas inclus dans la réponse. Dans la majorité des cas, le total est affiché sauf dans certains cas particuliers, comme les recherches textuelles (champs de type string) sur de gros volumes de données. Par exemple, rechercher tous les PractitionerRole ayant un nom d’exercice contenant « Martin ».

8.2) Paramètre “include”

Le paramètre _include permet d’afficher dans le résultat les ressources mères liées à la ressource fille. La/Les ressource(s) mère(s) es/sont récupérée(s) à partir de la ressource fille.

Exemples:

GET [base]/PractitionerRole?_include=PractitionerRole:organization

Cette requête par exemple remonte les PractitionerRole ainsi que les Oganization auxquelles ils sont rattachés.

8.2) Paramètre “revinclude”

Le paramètre _revinclude permet d’afficher dans le résultat les ressources filles liées à la ressource mère. La/Les ressource(s) filles est/sont récupérée(s) à partir de la ressource mère.

Exemples:

GET [base]/Organization?_revinclude=Organization:partof

Cette requête par exemple remonte les Entités Géographiques (EG) et les Entités Juridiques (EJ) de rattachement.

8.2) Paramètre “_elements”

Le paramètre _elements permet de préciser la liste d’attributs qui doit être retournée avec la ressource.

Exemples:

GET [base]/Practitioner?_elements=identifier,active

Dans la requête ci-dessus, la réponse retournée contiendra un lot de practitioner, mais chaque entrée n’inclura que les attributs identifier et active du practitioner.

A noter que la réponse contient également une meta.tag valeur de SUBSETTED pour indiquer que tous les attributs de la ressource ne sont pas inclus.

...
                    "tag": [
                        {
                            "system": "http://terminology.hl7.org/CodeSystem/v3-ObservationValue",
                            "code": "SUBSETTED",
                            "display": "Resource encoded in summary mode"
                        }
                    ]
                },
                "identifier": [
                    {
                        "use": "official",
                        "type": {
                            "coding": [
                                {
                                    "system": "http://interopsante.org/CodeSystem/v2-0203",
                                    "code": "IDNPS"
                                }
                            ]
                        },
                        "system": "urn:oid:1.2.250.1.71.4.2.1",
                        "value": "810000001916"
                    },
                    {
                        "use": "official",
                        "type": {
                            "coding": [
                                {
                                    "system": "http://interopsante.org/CodeSystem/v2-0203",
                                    "code": "RPPS"
                                }
                            ]
                        },
                        "system": "http://rpps.fr",
                        "value": "10000001916"
                    }
                ],
                "active": true
...

Code source des exemples

Vous retrouverez le code source de ces exemples sur notre repository git:

Options d'accessibilité

Paramètres de recherche

1) Paramètres de recherche disponibles

2) Paramètres de type texte (string)

2.1) Recherche sans “modifier”

2.2) Recherche avec le “modifier” “contains”

2.3) Recherche avec le “modifier” “exact”

3) Paramètres de type token

Recherche par code

4) Paramètres de type date

7) Paramètres combinés

7.1) Paramètres ET (AND)

7.2) Paramètres OU (OR)

8) Paramètres des résultats de la recherche

8.1) Paramètre “_count”

8.2) Paramètre “_total”

8.2) Paramètre “include”

8.2) Paramètre “revinclude”

8.2) Paramètre “_elements”

Code source des exemples