Regenstrief Institute has recently launched web services that make much of LOINC’s terminology content available through the HL7 FHIR API. These services open up a whole new way to interact with LOINC programmatically.

This tutorial will help you get started with LOINC’s FHIR terminology services.

Note: the FHIR terminology services hosted by Regenstrief are still under development and should be considered “beta” at this point. We are working with the team at SmileCDR to implement these services in HAPI, an open source FHIR library in Java.

Related Content

More on how LOINC and FHIR go together like chips and salsa.

Prerequisites

In order to get started with LOINC’s FHIR terminology services, there are just a couple of prerequisites.

Creating a LOINC user account

To access LOINC’s FHIR terminology services (and other LOINC goodness), you’ll need an account on loinc.org.

If you already have an account, you’re good to go. If not, signing up is easy. Just visit the signup page and enter the required info:

Using an API development environment

I find that the easiest way to explore things with FHIR is to use an app like Postman as an API client. The free Postman software is available for Windows, MacOS, Linux, and Chrome.

I recommend that you download and install Postman for these exercises.

Using authentication

Whether you are accessing the FHIR terminology services via a browser or using an API development environment like Postman, you’ll need to provide your loinc.org login credentials.

In the browser, you’ll probably get a pop-up window like this the first time you access the service:

 

In Postman, you’ll first have to set the Authorization TYPE to “Basic Auth”:

And then providing your LOINC login information:

Executing calls to the server using Postman

Throughout this tutorial, you can execute calls to the FHIR server with the Postman app. After setting Postman to use Basic Auth, you can execute a request by:

  1. Copying the URLs provided (and the URLs you create as you explore on your own)
  2. Pasting them into the GET request of Postman
  3. Hitting SEND

Blank Postman window before executing a API request:

After entering a request URL and hitting SEND you’ll see the response body in the lower part of the window:

Exercises to explore LOINC’s Terminology Services

The following examples will introduce you to LOINC content represented in three FHIR Terminology Services resources: CodeSystem, ValueSet, and ConceptMap.

Base URL for LOINC FHIR Server

As you explore LOINC’s FHIR services, this will be the base URL:

https://fhir.loinc.org

1. CodeSystem

The CodeSystem resource specifies a set of codes drawn from one or more code systems. Code systems define which codes (symbols and/or expressions) exist, and how they are understood. In LOINC’s case, we have created a canonical definition of how to represent LOINC as a CodeSystem in FHIR that extends its representation to include more LOINC-specific features. The LOINC code system defines several kinds of identifiers:

  • LOINC Codes (e.g. 21176-3)
  • LOINC Parts (e.g. LP31755-9)
  • LOINC Answer Lists (e.g. LL715-4)
  • LOINC Answers (e.g. LA11165-0)

All of these codes are included in the LOINC CodeSystem resource.

See all the specialized properties available for LOINC as a CodeSystem in FHIR

To get all the information about LOINC as a code system in FHIR, find it using the canonical URI for LOINC in FHIR (which is http://loinc.org).

Try this:

https://fhir.loinc.org/CodeSystem/?url=http://loinc.org

As you scroll down to the defined property section, you’ll see attributes like “VersionFirstReleased” and “VersionLastChanged”, plus some domain-specific attributes for the LOINC Document Ontology and LOINC Radiology model.

Pretty cool!

Get all the info about a LOINC code, Part, Answer List or Answer String

To get all the information about a code in a code system, use the $lookup operation.

Here are some examples to try for the different kinds of codes from LOINC:

https://fhir.loinc.org/CodeSystem/$lookup?system=http://loinc.org&code=4544-3
https://fhir.loinc.org/CodeSystem/$lookup?system=http://loinc.org&code=LP31755-9
https://fhir.loinc.org/CodeSystem/$lookup?system=http://loinc.org&code=LL2095-9
https://fhir.loinc.org/CodeSystem/$lookup?system=http://loinc.org&code=LA6751-7

Use the &&property feature to return just what you want

The previous examples returned all of the information about a particular code. Using the &&property feature, you can limit what the server returns to only the property(ies) of interest.

For example, here’s how to return just the Method for a particular term:

https://fhir.loinc.org/CodeSystem/$lookup?system=http://loinc.org&code=4544-3&&property=METHOD_TYP

Your turn.

How could you ask the server to return only one property: the version of LOINC that term 4544-3 first appeared in?
https://fhir.loinc.org/CodeSystem/$lookup?system=http://loinc.org&code=4544-3&&property=VersionFirstReleased

2. ValueSet

The ValueSet resource specifies a set of codes drawn from one or more code systems. Value Sets select a set of codes from one or more code systems to specify which codes can be used in a particular context.

In LOINC’s case, we have created three main kinds of value sets:

  • General collections of LOINC terms
  • Answer Lists (e.g. LL4700-2)
  • LOINC Groups (e.g. LG32763-1)

Return the whole ValueSet resource

In the examples below, calling the ValueSet resource directly gives you back the whole resource entry. This will give you all the ValueSet metadata, the definition criteria, etc. For example:

https://fhir.loinc.org/ValueSet/?url=http://loinc.org/vs/top-2000-lab-observations-us

Use the $expand operation to get back the list of terms in the ValueSet

Calling the ValueSet resource directly gives you back the whole resource entry. To return just the list of terms in the ValueSet, use the $expand operation. For example:

https://fhir.loinc.org/ValueSet/$expand?url=http://loinc.org/vs/LL1162-8

Use the $validate-code operation to see if a code is in a ValueSet

To see if a particular term is in the ValueSet, use the $validate-code operation. For example:

https://fhir.loinc.org/ValueSet/LG33055-1/$validate-code?system=http://loinc.org&code=8867-4

General collections of LOINC terms

We have defined several key subsets of LOINC terms as Value Sets because they are useful collections for various purposes. Here are the main collections we have defined:

 

LOINC Document Ontology

A special set of LOINC codes that are built on a framework for naming and classifying the key attributes of clinical documents.
http://loinc.org/vs/loinc-document-ontology

LOINC/RSNA Radiology Playbook

A special set of LOINC codes that are built on a framework for naming and classifying the key attributes of radiology procedures.
http://loinc.org/vs/loinc-rsna-radiology-playbook

LOINC Top 2000+ Lab Observations – US Version

This is an empirically-based subset of the most common LOINC result codes. It contains just over 2000 LOINC codes that represent about 98% of the test volume carried by three large organizations that mapped all of their lab tests to LOINC codes. This is the US Version, for those who favor reporting in mass units (e.g. mg/dL).
http://loinc.org/vs/top-2000-lab-observations-us

LOINC Top 2000+ Lab Observations – SI Version

This is an empirically-based subset of the most common LOINC result codes. It contains just over 2000 LOINC codes that represent about 98% of the test volume carried by three large organizations that mapped all of their lab tests to LOINC codes. This is the SI Version, for those who favor reporting in molar units (e.g. mmol/L).
http://loinc.org/vs/top-2000-lab-observations-si

LOINC Answer Lists as FHIR Value Sets

Across many domains, the meaning of a particular observation can be best understood in the context of the set of possible answers (result values). For example, the items in standardized assessment instruments often have highly specialized, fixed answer lists. For these reasons, LOINC has created a structured representation of answer lists in LOINC.

LOINC Answer Lists are assigned a non-semantic identifier with a “LL” prefix and a mod-10 check digit. The individual answers (called LOINC Answers) within a list are assigned a non-semantic identifier with a “LA” prefix and a mod-10 check digit. The answer codes LOINC assigns are unique by lexical string (ignoring capitalization), and by intention do not distinguish between strings that may have different meanings depending on their contextual use.

LOINC Answer Lists represent collections of coded concepts that can be used as response values to LOINC terms. The canonical URI pattern for identifying the value set defined by a LOINC Answer List is:

http://loinc.org/vs/{LOINC Answer List code}

 

Get the list of LOINC Answers in a LOINC Answer List as a FHIR Value Set expansion

https://fhir.loinc.org/ValueSet/$expand?url=http://loinc.org/vs/LL1162-8

 

Search for all Answer Lists with “Yes” in their name

https://fhir.loinc.org/ValueSet?name:in=Yes
How could you find out if LOINC Answer LA15679-6 is in LOINC Answer List LL1162-8?

Use the $validate-code operation:

https://fhir.loinc.org/ValueSet/LL1162-8/$validate-code?system=http://loinc.org&code=LA15679-6

LOINC Groups as FHIR Value Sets

LOINC Groups are a technique for rolling up groups of LOINC codes that could be treated as equivalent or useful for various purposes. For example, you may want to aggregate data for displaying on a flowsheet within an electronic health record (EHR) system, retrieve data for quality measure reporting, or process data for research.

Each LOINC Group is assigned a non-semantic identifier with a “LG” prefix. The LG codes serve as a coded value set identifier. As such, they correspond to a particular “definition” of what should be included in the group. Following best practices, LOINC Groups intend to keep the logical definition stable in meaning over time. However, the members of the group may change as the underlying terminology (LOINC) evolves. For example, new concepts may be added that fulfill a group’s definition and are thus included.

Visit the LOINC website for more information about LOINC Groups.

Note: At the present time, LOINC Group identifiers (i.e. LG* codes) are not yet loaded into the FHIR CodeSystem representation of LOINC. (They will be eventually). So they work as ValueSet identifiers, but you can’t look them up as codes in the code system.

Get a LOINC Group as a FHIR Value Set

https://fhir.loinc.org/ValueSet/?url=http://loinc.org/vs/LG9568-9

3. ConceptMap

The ConceptMap resource defines a mapping from a set of concepts defined in a code system to one or more concepts defined in other code systems. Mappings are one way: from the source to the destination.

In LOINC’s case, we have created several sets of mappings:

  • LOINC terms to IEEE device codes
  • LOINC terms to RadLex Playbook procedure codes (RPIDs)
  • LOINC Parts to RadLex clinical terms (RIDs)
  • LOINC Parts to RxNorm terms
  • LOINC Parts to SNOMED CT terms

Return the whole ConceptMap resource

In the examples below, calling the ConceptMap resource directly gives you back the whole resource entry. This will give you all the ConceptMap metadata, the mappings, etc. For example:

https://fhir.loinc.org/ConceptMap/?url=http://loinc.org/fhir/loinc-ieee-device-code-mappings

Use the $translate operation to get back a mapping for a particular code

To find a mapping for a particular source term, use the $translate operation. For example:

https://fhir.loinc.org/ConceptMap/$translate?system=http://loinc.org&code=11556-8

LOINC terms to IEEE medical device codes

The LOINC/IEEE Medical Device Code Mapping Table is distributed by Regenstrief as product of a collaboration between the IEEE-SA and Regenstrief Institute, Inc. The file contains linkages between LOINC terms and content from the IEEE 11073(TM) 10101 Standard for Health informatics – Point-of-care medical device communication – Nomenclature and 10101a Nomenclature Amendment. Variables included those produced by ventilators, anesthesia gas machines, invasive blood pressure monitoring, EEG, and some lab measurements.
http://loinc.org/fhir/loinc-ieee-device-code-mappings

 

Get the LOINC to IEEE mappings
https://fhir.loinc.org/ConceptMap/?url=http://loinc.org/fhir/loinc-ieee-device-code-mappings

Note: At the present time, LOINC Group identifiers (i.e. LG* codes) are not yet loaded into the FHIR CodeSystem representation of LOINC. (They will be eventually). So they work as ValueSet identifiers, but you can’t look them up as codes in the code system.

LOINC terms to RadLex Playbook procedure terms

The LOINC/RSNA Radiology Playbook is the product of a collaboration between the Radiological Society of North America (RSNA) and Regenstrief Institute, Inc. to develop a unified model for naming radiology procedures. The organizations agreed that a unified naming model was needed, but that perpetuating dual identifiers (LOINC codes and RPIDs) for procedures in the unified terminology would be duplicative work and introduce unnecessary confusion for users about which code to use in which circumstance. They have agreed that LOINC codes will be the primary identifiers for procedures in the unified terminology. They also agreed to map existing RRIDs to corresponding LOINC codes, but that new RPIDs would not be created.
http://loinc.org/rpid-codes

 

Get the LOINC to RPID mappings
https://fhir.loinc.org/ConceptMap/?url=http://loinc.org/rpid-codes
How could you find out if there is an RPID mapping for LOINC 24628-0?
https://fhir.loinc.org/ConceptMap/$translate?system=http://loinc.org&code=24628-0

Acknowledgments

This material contains content from LOINC® (http://loinc.org). The LOINC Table, LOINC Table Core, LOINC Panels and Forms File, LOINC Answer File, LOINC Part File, LOINC Group File, LOINC Document Ontology File, LOINC Hierarchies, LOINC Linguistic Variants File, LOINC/RSNA Radiology Playbook, and LOINC/IEEE Medical Device Code Mapping Table are copyright © 1995-2018, Regenstrief Institute, Inc. and the Logical Observation Identifiers Names and Codes (LOINC) Committee and is available at no cost under the license at http://loinc.org/license.

Learn LOINC Fast

Get the secret weapon that will jumpstart your LOINC mapping and make you a LOINCer extraordinaire in no time

$39

pdf format | 259 pages