Skip to content

FHIR_VZD_HOWTO_Search.adoc

Latest commit

 

History

History
704 lines (509 loc) · 27.4 KB

FHIR_VZD_HOWTO_Search.adoc

File metadata and controls

704 lines (509 loc) · 27.4 KB

FHIR VZD HOWTO Search

gematik
Version: 1.1.1

Referencing:

gemILF_FHIR_VZD

Document history

Version
 Stand
 Chap./ Page
 Change reason, special instructions
 Editing

1.0.0

28.07.23

Initial document

gematik

1.1.0

27.10.23

Full-text search

Added chapter full-text search

gematik

1.1.1

21.06.24

Full-text search
"near" Search parameter

Added full-text search attribute pharmacyType
Added description for "near" Search parameter for Location.position

gematik
Table of Contents

1. Classification of the document

1.1. Objective

This document gives a brief overview and examples for the FHIR search API that is provided by the VZD-FHIR-Directory.

1.2. Target group

The document is aimed at software developers who are involved in implementing search functionality for a client of the FHIR directory service.

1.3. Scope

Intellectual property/patent notice

The following specification was created by gematik solely from a technical point of view. In individual cases, it cannot be ruled out that the implementation of the specification will interfere with the technical property rights of third parties. It is solely up to the supplier or manufacturer to take suitable measures to ensure that the products and/or services offered by him on the basis of the specification do not infringe third-party property rights and, if necessary, to obtain the necessary permits/licenses from the property right holders concerned. In this respect, gematik GmbH assumes no liability whatsoever.

2. API Documentation

2.1. FHIRDirectorySearchAPI: Search for Practitioners and Organizations

To access the search API a valid searchaccess_token is needed that can be obtained by authenticating via Authenticate for search

2.1.1. FHIR Search Basics

The REST interface /search allows you to search for practitioners and organizations. The standard FHIR search operation is used https://build.fhir.org/search.html

GET [baseUrl]/[resourceType]?[optional parameters]

As resourceType are supported

  • HealthcareService (search for organizations)

  • PractitionerRole (search for practitioners)

The overview about the supported data model can be found here: https://simplifier.net/vzd-fhir-directory

Only resources with the status "active" may be displayed. For this reason, the [resource].active=true parameter must be specified for all search operations. The minimal variant of the search operations thus looks like this:

  • GET [baseUrl]/search/HealthcareService?organization.active=true

  • GET [baseUrl]/search/PractitionerRole?practitioner.active=true

As result, the client receives a FHIR Bundle resource with the search result.


In addition to the HL7 FHIR specification, the FHIR VZD supports the following search parameters

  • practitioner.qualification

  • location.address (e.g. to search for TI-Messenger addresses)

The following HL7 FHIR search parameters are not yet support (but are in work):

Important
 For all search operations a valid searchaccess_token is needed that can be achieved by following the authentication flow: Get search token

2.1.2. FHIR Search Organizations

To search for organizations, use "HealthcareService" as the resource type and at least "organization.active=true" as the parameter:

GET [baseUrl]/search/HealthcareService?organization.active=true

Additional parameters can be added to refine the search.

2.1.3. FHIR Search Practitioners

To search for people, use "PractitionerRole" as the resource type and at least "practitioner.active=true" as the parameter:

GET [baseUrl]/search/PractitionerRole?practitioner.active=true

Additional parameters can be added to refine the search.

2.1.4. FHIR Search Parameters - Overview

FHIR defines which search parameters can be used for each resource. For each resource the is a "Search Parameters" section. Examples:

An overview about all resources with its search parameters can be found here: https://www.hl7.org/fhir/searchparameter-registry.html

The behavior of the search parameter depends from the parameter type and is documented here: https://www.hl7.org/fhir/search.html#ptypes

2.1.5. FHIR Search Parameters - Custom Search Parameters

The following custom search parameters are supported in addition to the standard FHIR search parameters

  • Endpoint.address

  • Practitioner.qualification

    • Practitioner.qualification.code.coding.code

    • Practitioner.qualification.code.coding.display

2.1.6. FHIR VZD Search - "practitioner.name" attribute

To search a resource the "name" attribute of it can be used in the search operation:

GET [baseUrl]/search/PractitionerRole?practitioner.active=true&practitioner.name=Timjamin
Table 1. Table Used search parameters
FHIR search parameter Parameter Value Explanation

practitioner.name

Timjamin

The string "Timjamin" is searched for attribute "name" of the "practitioner" resource.
Response of this Request:

Search_PractitionerRole_name

2.1.7. FHIR VZD Search - "endpoint.payload-type" attribute (code based search)

To search a resource which supports a defined type of communication the "endpoint.payload-type" attribute can be used in the search operation:

GET [baseUrl]/search/PractitionerRole?practitioner.active=true&_include=PractitionerRole:practitioner&_include=PractitionerRole:location&_include=PractitionerRole:endpoint&endpoint.payload-type=tim-chat&endpoint.status=active
Table 2. Table Used search parameters
FHIR search parameter Parameter Value Explanation

endpoint.payload-type

tim-chat

The "payload-type" is used to search for resources, supporting the TI-Messenger chat communication. The definition of the "endpoint" is refined in simplifier for the "FHIR VZD". For the payloadType the "ValueSet EndpointPayloadTypeVS" imports all values from "EndpointDirectoryPayloadType".

_include

PractitionerRole:practitioner

"practitioner" resources, linked to the "PractitionerRole" resources of the search request are included in the search response.

_include

PractitionerRole:location

"location" resources, linked to the "PractitionerRole" resources of the search request are included in the search response.

_include

PractitionerRole:endpoint

"endpoint" resources, linked to the "PractitionerRole" resources of the search request are included in the search response.

endpoint.status

active

The search parameter "status" ensures, that only active endpoints are returned. If endpoints are needed, then only active endpoints have to be used/displayed. This has to be ensured by all clients. Please note that with this parameter resources with no active endpoints are not returned.
Response of this Request:

Search_PractitionerRole_payload-type

2.1.8. FHIR VZD Search - "endpoint.payload-type" attribute (display text based search)

For the display text of a coded attribute can be searched with the modifier ":text":

GET [baseUrl]/search/PractitionerRole?practitioner.active=true&_include=PractitionerRole:practitioner&_include=PractitionerRole:location&_include=PractitionerRole:endpoint&endpoint.payload-type:text=TI-Messenger chat&endpoint.status=active
Table 3. Table Used search parameters
FHIR search parameter Parameter Value Explanation

endpoint.payload-type:text

TI-Messenger chat

The "payload-type" is used to searched for resources, supporting the TI-Messenger chat communication. The definition of the "endpoint" is refined in simplifier for the "FHIR VZD". For the payloadType the "ValueSet EndpointPayloadTypeVS" imports all values from "EndpointDirectoryPayloadType".

_include

PractitionerRole:practitioner

"practitioner" resources, linked to the "PractitionerRole" resources of the search request are included in the search response.

_include

PractitionerRole:location

"location" resources, linked to the "PractitionerRole" resources of the search request are included in the search response.

_include

PractitionerRole:endpoint

"endpoint" resources, linked to the "PractitionerRole" resources of the search request are included in the search response.

endpoint.status

active

The search parameter "status" ensures, that only active endpoints are returned. If endpoints are needed, then only active endpoints have to be used/displayed. This has to be ensured by all clients. Please note that with this parameter resources with no active endpoints are not returned.

Response of this Request: Search_PractitionerRole_payload-type:text

2.1.9. FHIR VZD Search - complex search request

Search in a city for a practitioner with a defined qualification and offers the communication via TI-Messenger:

GET [baseUrl]/search/PractitionerRole?practitioner.active=true&_include=PractitionerRole:practitioner&_include=PractitionerRole:location&_include=PractitionerRole:endpoint&location.address-city=Gelsenkirchen&location.address=45884&practitioner.qualification=1.2.276.0.76.4.241&endpoint.payload-type=tim-chat&endpoint.status=active
Table 4. Table Used search parameters
FHIR search parameter Parameter Value Explanation

_include

PractitionerRole:practitioner

"practitioner" resources, linked to the "PractitionerRole" resources of the search request are included in the search response.

_include

PractitionerRole:location

"location" resources, linked to the "PractitionerRole" resources of the search request are included in the search response.

_include

PractitionerRole:endpoint

"endpoint" resources, linked to the "PractitionerRole" resources of the search request are included in the search response.

location.address-city

Gelsenkirchen

Search for practitioners with search parameter "address-city" in the city "Gelsenkirchen". "address-city" limits the search to the address attribute "city", search parameter "address" searches all address attributes for the string.

location.address

45884

Search for practitioners with search parameter "address" in all address attributes for "45884".

practitioner.qualification

1.2.276.0.76.4.241

Search for practitioners with search parameter "qualification" for qualification code "1.2.276.0.76.4.241".
Note: For humans a readable text should be used for selection and display of coded attributes.

endpoint.payload-type

tim-chat

The "payload-type" is used to searched for resources, supporting the TI-Messenger chat communication. The definition of the "endpoint" is refined in simplifier for the "FHIR VZD". For the payloadType the "ValueSet EndpointPayloadTypeVS" imports all values from "EndpointDirectoryPayloadType".

endpoint.status

active

The search parameter "status" ensures, that only active endpoints are returned. If endpoints are needed, then only active endpoints have to be used/displayed. This has to be ensured by all clients. Please note that with this parameter resources with no active endpoints are not returned.

Response of this Request: Search_PractitionerRole_complex

2.1.10. FHIR VZD Search - HealtcareService by telematikID

Search an organization with a telematikID:

GET [baseUrl]/search/HealthcareService?organization.active=true&_include=*&endpoint.status=active&organization.identifier=1-2arvtst-ap000052
Table 5. Table Used search parameters
FHIR search parameter Parameter Value Explanation

_include *

All resources, linked to the "HealthcareService" resources of the search request are included in the search response.

endpoint.status

active

The search parameter "status" ensures, that only active endpoints are returned. If endpoints are needed, then only active endpoints have to be used/displayed. This has to be ensured by all clients. Please note that with this parameter resources with no active endpoints are not returned.

organization.identifier

Response of this Request: Search_HealthcareService_telematikID

2.1.11. FHIR VZD Search results

The Client can manage the content of the FHIR search response with several parameters. In this section some examples are shown. The full list of parameters for managing search results can be found here: https://www.hl7.org/fhir/search.html#return

_include Parameter

The response of the 'FHIR VZD Search with "name" attribute' contains only resources of type "PractitionerRole".
With the "_include" parameter also resources linked with the search result resources are returned:

GET [baseUrl]/search/PractitionerRole?practitioner.active=true&practitioner.name=Timjamin&_include=PractitionerRole:practitioner&_include=PractitionerRole:location&_include=PractitionerRole:endpoint&endpoint.status=active
Table 6. Table Used search parameters
FHIR search parameter Parameter Value Explanation

practitioner.name

Timjamin

The string "Timjamin" is searched for attribute "name" of the "practitioner" resource.

_include

PractitionerRole:practitioner

"practitioner" resources, linked to the "PractitionerRole" resources of the search request are included in the search response.

_include

PractitionerRole:location

"location" resources, linked to the "PractitionerRole" resources of the search request are included in the search response.

_include

PractitionerRole:endpoint

"endpoint" resources, linked to the "PractitionerRole" resources of the search request are included in the search response.

endpoint.status

active

The search parameter "status" ensures, that only active endpoints are returned. If endpoints are needed, then only active endpoints have to be used/displayed. This has to be ensured by all clients. Please note that with this parameter resources with no active endpoints are not returned.

Response of this Request: Search_PractitionerRole_name_include

_summary Parameter - count the results

Using the parameter _summary the client can request the server to return only a portion of the resources:

GET [baseUrl]/search/PractitionerRole?practitioner.active=true&_summary=count
Table 7. Table Used search parameters
FHIR search parameter Parameter Value Explanation

_summary

count

only the number of the matching resources is returned

Response of this Request: Search_Result_count

2.1.12. Full-text search

The aim of the full-text search is to replace the cumbersome parameter-based search with a simple full-text search. By entering a simple search string, a user should be shown suitable results without having to know the technical internals of the underlying FHIR resources.

The full-text search feature from HAPI is used and extended for the _text search parameter.

  • The HAPI/FHIR full-text search supports the search for texts in the base resource. This HAPI/FHIR full-text search can be used with the _content search parameter.

  • This HAPI/FHIR full-text search is extended in the following way to support also the full-text search for linked resources (_text search parameter).:

    1. The values of the text attributes of all linked resources are stored in the _text field of HealthcareSevice for organizations and PractitionerRole for people. This happens when indexing the attributes of all linked resources after data changes.

    2. Because of this values in _text field the HAPI full-text search will also match the values of the linked resources, which are stored in the _text field of the main ressources.

Contents of the _text attribute for organizations

The content of the _text attribute is taken into account in the full-text search.

Table 8. _text attribute for organizations
Resource Attribute Description

Organization

name

Organization name

Organization

type.display

Name of institution type /
Name of the provider type

HealthcareService

speciality.display

Name of the specialization

HealthcareService

name

Name assigned by the owner for the service

HealthcareService

type

Type of pharmacy PharmacyTypeCS

Location

address.line

Street including house number

Location

address.city

City

Location

address.postalCode

postalCode

Organization

identifier (Type Telematik_ID or DomainID)

Telematik_ID and DomainID
Contents of the _text attribute for persons

The content of the _text attribute is taken into account in the full-text search.

Table 9. _text attribute for persons
Resource Attribute Description

Practitioner

name

Practitioner name

Practitioner

qualification.display

Name of the professional group (ProfessionalOID) /
Name of the specialization

Location

address.line

Street including house number

Location

address.city

City

Location

address.postalCode

postalCode

Practitioner

identifier

Telematik_ID
Full-text search and normal search

The full-text search can be combined with normal search parameters.

The _text attribute of the main resource is used for the full-text search. That’s why the performance for full-text search is significantly better, i.e. for attributes from linked resources.
If attributes are required in the search filter - which cannot be searched using the full-text search (see tables) - then they can be combined with a full-text search using normal FHIR search parameters.

In this example the _text full-text search parameter is used to search for the telematikID and the endpoint.status search parameter for active endpoints.

{{fhir_server}}/search/HealthcareService?organization.active=true&_include=HealthcareService:organization&_include=HealthcareService:endpoint&_include=HealthcareService:location&_text="1-2arvtst-ap104233","1-2arvtst-ap051582"&endpoint.status=active
Interesting facts about indexing

  • Dot "." at the end of one word (e.g. Dr. or Str. )
    When indexing, the period is removed because it is interpreted as the end of a sentence.

  • Slash ( / ) (e.g. Arzt/Ärztin)
    When indexing, two words are generated by the slash (e.g. Arzt/Ärztin, two words Arzt and Ärztin but not the word incl. / as "Arzt/Ärztin").
    Therefore, “Arzt/Ärztin” is not found in the search.

Characters with special meaning in the full-text search

Special characters can be used to specify search queries. For example, if you put the search query in quotation marks, only the results that exactly match the string will be shown. Additional symbols can be used to exclude or combine search terms, for example. Below are the important signs:

Quotation marks ("…​")
If the search text is put in quotation marks, only results with the exact same text will be found.

Special characters (which otherwise have a special meaning) within the quotation marks are interpreted as normal characters.
For example, the telematikID should always be put in quotation marks for full-text searches. It contains characters like "-".

A full-text search with a string will match all linked resource with this string in an indexed attribute, also if the search string is a substring in an indexed attribute.
A search with _text=Berlin will e.g. match resources with "city": "Bernau bei Berlin" or "line": ["Berlingeröder Str. 13"].
A search with _text="Berlin" matches only resources with the exact string "Berlin" in the indexed attributes.

Examples where the use of Quotation marks is necessary:

  • Search parameters with hyphens "-". For example the telematikID:
    A telematikID looks like 1-1023410034573
    In the full-text search this "-" is a NOT operation. Without Quotation marks a full-text search will not match correctly such a value. Use _text="1-1023410034573"
    An othe example is the street name, e.g. Karl-Marx-Straße

  • Search parameters with special characters. For example the dot "."

AND operations (+ SPACE)
AND operations in search strings: The search strings are separated with the following characters

  • "+" (Plus) e.g. string1+string2

  • " " (Space) e.g. string1 string2

Examples: _text=Berlin "Organisation 1-2arvtst-ap000139"
          _text=Berlin +"Organisation 1-2arvtst-ap000139"
          _text=Berlin+"Organisation 1-2arvtst-ap000139"

All these searches match, if both strings are contained in the linked resources. In this expample "Berlin" is contained in the Location resource and "Organisation 1-2arvtst-ap000139" in the Organization name.

OR operations (,)
OR operations in search strings: The search strings are separated with the following characters

  • "|" (pipe) has to be URL-encoded e.g. string1%20%7C%20string2

  • "," (comma) e.g. string1,string2

Examples: _text="1-2arvtst-ap104233"%20%7C%20"1-2arvtst-ap051582"
          _text="1-2arvtst-ap104233","1-2arvtst-ap051582"

All these searches match, if at least one of the strings is contained in the linked resources.

NOT operations (-)
For the NOT operation, the string must begin with "-" hyphen, e.g. -string1

Example: _text=Niedersachsen -Hannover

Matches, if string Niedersachsen is contained in the linked resources but not Hannover.

Fuzzy-Search (~)
~N after a word signifies edit distance (fuzziness), e.g. string~
The optional number N is the Levenshtein Edit Distance. See Fuzziness for valid values and more information.

Example: _text=Coppenbruegge~

Matches, if string Coppenbruegge or similar strings are contained in the linked resources.
This example matches e.g.

  • Coppenbrügge

  • Coppenbruegge

  • Coppenbrüge

Full-text search examples

full-text-search-request found description

_text=Bessinger Str. 42

nothing found

Because the dot "." has a special meaning, nothing is found.

_text="Bessinger Str. 42"

Bessinger Str. 42

Found, because the string with "." is in quotation marks.

_text=Bessinger "Str." 42

Bessinger Str. 42

Found, because word with "." is in quotation marks.

_text=Bessinger Str 42

Bessinger Str. 42

Found, because all tokens of the search string are contained, no special character is used in the search string and the tokens of the search string are combined with an AND " ".

_text=Franz*+Wallraf*+Str*

Franz-Wallraff-Str. 2

_text=Franz+Wallraf+Str

Franz-Wallraff-Str. 2

Found, implicitly looking for the beginning of a word (Wallraf finds Wallraff)

_text="Franz Wallraf Str"

nothing found

Because the exact search is for “Wallraf”.

_text="Franz Wallraff Str"

Franz-Wallraff-Str. 2

_text=Franz+Wallraff+Str.

nothing found

Because the dot "." has a special meaning, nothing is found.

_text=Franz-Wallraff-Str

nothing found

Hyphen is not interpreted as a search character here. It has a special meaning.

_text="Franz-Wallraff-Str."

Franz-Wallraff-Str. 2

_text="Franz"+"Wallraff"+"Str."

Franz-Wallraff-Str. 2

_text=Aachen+Wallraf

Aachen 52078 Franz-Wallraff-Str. 2

_text="Aachen"+Wallraf

nothing found

Because of the quotation marks for the first word, the search is made for exactly for all words.

_text="Aachen"+"Wallraf"

nothing found

The search is made for exactly for all words.

_text="Aachen"+Wallraf*

Aachen 52078 Franz-Wallraff-Str. 2

The search is carried out exactly per word. With the * at the end of Wallraf also Wallraff is found.

_text="Aachen"+"Wallraf*"

nothing found

A * in quoted words is not interpreted as a wildcard.

_text="aAChen"+wALlraf*

Aachen 52078 Franz-Wallraff-Str. 2

Upper and lower case letters are ignored.

2.1.13. FHIR VZD Search - "near" search parameter for Location.position

Search for locations where the location.position is near to, or within a specified distance of, the provided coordinates expressed as [latitude]|[longitude]|[distance]|[units].

GET [baseUrl]/search/HealthcareService?organization.active=true&location.near=50.1503|8.6168|10|km&_sort=location&_include=HealthcareService:location

Please note that for the FHIR VZD "near" search all "near" search parameters ([latitude]|[longitude]|[distance]|[units]) are mandatory.
⚡