Searching by System and Value

Some fields in FHIR, such as identifiers, codeable concepts and coded values, include both a system and a code. To query this effectively, FHIR provides options to search using both parts together.

In this tutorial we will look at,

• Searching by code
• Searching by system
• Searching by system and code together
• URL encoding for queries

Searching by code

The simplest case, is to search by code value directly.

For example, to find all Observation resources that record heart rate by its LOINC code, 8867-4, the search query will look like this,

GET /Observation?code=8867-4

This returns only Observations where the Observation.code.coding.code is 8867-4.

More generally, this can be written as,

GET /Observation?code={code}

where {code} must be replaced by the code you wish to search for.

Searching by system

It is also possible to fetch all resources that use a particular coding system, regardless of which code is chosen. For examle, to return all Observations coded in LOINC:

GET /Observation?code=http://loinc.org|

Note the | pipe character placed after the URL to indicate that it is a system.

This query retrieves all Observations that have LOINC codes.

Searching by system and code

For precise searches, it is possible to combine both system and code. This avoids ambiguity in cases if the same code is reused across different coding systems.

The general format used is system|code.

For ecample, to search for Observations that have the LOINC code 8867-4 for Heart Rate,

GET /Observation?code=http://loinc.org|8867-4

URL encoding for queries

While making queries directly in a browser, or in code that doesn’t automatically encode parameters, special characters like : and | must be URL encoded.

Here are some examples of the encoding key,

• space(” ”): %20
• colon(”:”): %3A
• forward slash(”/”): %2F

For example, this is the query before encoding,

GET /Observation?code=http://loinc.org|8867-4

And this is the full encoded query,

GET /Observation?code=http%3A%2F%2Floinc.org%7C8667-4

Most FHIR client libraries and tools like Postman take care of encoding automatically. However, in case you run into errors, you can manually encode the URL.

Summary

In this lesson, we learnt to query system and code values in FHIR, exploring code-only, system-only and combined system+code searches. Additionally, we looked at URL encoding when working with special characters in queries.

These techniques are demonstrated using the Observation resource but are applicable to others including Patient.identifier and Condition.code.