Access LOINC's terminology content through the HL7® FHIR® API

Great news! You can now access current LOINC content programmatically. Our server uses the terminology services defined by HL7's FHIR standard.

The service base URL is:

https://fhir.loinc.org

BETA LOINC's FHIR services are BETA status. Things may change, and we will update this documentation to stay current. They may not be available 100% of the time, so don't rely on them for production use. You can visit our dedicated User Forum to discuss this server. If you notice something not working as expected, please let us know.

If you already have a solid grasp on FHIR concepts, you may want to jump to our developer reference for LOINC in FHIR.

This primer will get you up-to-speed on LOINC's FHIR implementation

You need a LOINC login

All requests to LOINC's FHIR terminology server require a LOINC username and password. If you do not already have a LOINC account, you may sign up for free.

Your LOINC account also enables you to download LOINC files, use search.loinc.org, and participate in our Forum.

Tips on using this documentation

All provided examples will work within a browser. You will need to provide your login information upon the first request of a session. We also suggest using the free Postman software as an API client.

Each example includes a button so you may copy the URL and paste it into a browser window or within a Postman GET request. (As with the browser, you will need to provide your credentials using Postman’s Basic Auth option.)

RELATED CONTENT

LOINC and FHIR

More on how these standards go together like chips and salsa. Presented by Daniel J. Vreeman, PT, DPT, MS at FHIR DevDays 2018 in Boston on 2018-06-19.

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.

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. LOINC's CodeSystem definition is available at for download available at https://loinc.org/fhir/loinc.xml.

NOTE Over time, we do anticipate updating this canonical definition in collaboration with the FHIR and LOINC community.

The following are identifiers within the LOINC code system. All are included within the LOINC CodeSystem resource.

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

Get the specialized properties available for LOINC as a CodeSystem in FHIR

Use the canonical URI for LOINC, http://loinc.org, to retrieve all the information about LOINC as a CodeSystem in FHIR through this request:

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

The server provides the following sample response, represented in JSON:

{
  "resourceType": "Bundle",
  "id": "a694d3ff-bf06-4521-8812-87ec9085ba5f",
  "meta": {
    "lastUpdated": "2018-08-29T19:35:19.796+00:00"
  },
  "type": "searchset",
  "total": 1,
  "link": [
    {
      "relation": "self",
      "url": "https://fhir.loinc.org/CodeSystem/?_format=json&url=http://loinc.org"
    }
  ],
  "entry": [
    {
      "fullUrl": "https://fhir.loinc.org/CodeSystem/loinc",
      "resource": {
        "resourceType": "CodeSystem",
        "id": "loinc",
        "meta": {
          "versionId": "1",
          "lastUpdated": "2018-06-21T22:26:26.954+00:00"
        },
        "url": "http://loinc.org",
        "identifier": {
          "system": "urn:ietf:rfc:3986",
          "value": "urn:oid:2.16.840.1.113883.6.1"
        },
        "name": "LOINC",
        "title": "LOINC Code System",
        "status": "active",
        "experimental": false,
        "publisher": "Regenstrief Institute, Inc.",
        "contact": [
          {
            "telecom": [
              {
                "value": "http://loinc.org"
              }
            ]
          }
        ],
        "description": "LOINC is a freely available international standard for tests, measurements, and observations",
        "copyright": "This content from LOINC® is copyright © 1995 Regenstrief Institute, Inc. and the LOINC Committee, and available at no cost under the license at http://loinc.org/terms-of-use",
        "caseSensitive": false,
        "valueSet": " http://loinc.org/vs",
        "compositional": false,
        "versionNeeded": false,
        "content": "not-present",
        "filter": [
          {
            "code": "parent",
            "description": "Allows for the selection of a set of codes based on their appearance in the LOINC Multiaxial Hierarchy. parent selects immediate children only. For example, the code '79190-5' has the parent 'LP203413-2'",
            "operator": [
              "="
            ],
            "value": "A Part code"
          },
          {
            "code": "child",
            "description": "Allows for the selection of a set of codes based on their appearance in the LOINC Multiaxial Hierarchy. child selects immediate children only. For example, the code 'LP203413-2' has the child '79190-5'",
            "operator": [
              "in"
            ],
            "value": "A comma separated list of Part codes"
          },
          {
            "code": "ancestor",
            "description": "Allows for the selection of a set of codes based on their appearance in the LOINC Multiaxial Hierarchy. ancestor includes parents transitively, e.g. 'LP203413-2' eventually has an ancestor 'LP14559-6', so the code '79190-5' is in the set of codes that have ancestor=LP14559-6",
            "operator": [
              "="
            ],
            "value": "A Part code"
          },
          {
            "code": "descendant",
            "description": "Allows for the selection of a set of codes based on their appearance in the LOINC Multiaxial Hierarchy. descendant includes children transitively, e.g. 'LP14559-6' eventually has a descendant 'LP203413-2', so the code '79190-5' is in the set of codes that have descendant=LP14559-6",
            "operator": [
              "in"
            ],
            "value": "A comma separated list of Part codes"
          },
          {
            "code": "copyright",
            "description": "Allows for the inclusion or exclusion of LOINC codes that include 3rd party copyright notices. LOINC = only codes with a sole copyright by Regenstrief. 3rdParty = only codes with a 3rd party copyright in addition to the one from Regenstrief",
            "operator": [
              "="
            ],
            "value": "LOINC | 3rdParty"
          }
        ],
        "property": [
          {
            "code": "parent",
            "uri": "http://hl7.org/fhir/concept-properties#parent",
            "description": "A parent code in the Multiaxial Hierarchy"
          },
          {
            "code": "child",
            "uri": "http://hl7.org/fhir/concept-properties#child",
            "description": "A child code in the Multiaxial Hierarchy"
          },
          {
            "code": "STATUS",
            "uri": "http://loinc.org/property/STATUS",
            "description": "Status of the term. Within LOINC, codes with STATUS=DEPRECATED are considered inactive. Current values: ACTIVE, TRIAL, DISCOURAGED, and DEPRECATED",
            "type": "string"
          },
          {
            "code": "COMPONENT",
            "uri": "http://loinc.org/property/COMPONENT",
            "description": "First major axis-component or analyte: Analyte Name, Analyte sub-class, Challenge",
            "type": "Coding"
          },
          {
            "code": "PROPERTY",
            "uri": "http://loinc.org/property/PROPERTY",
            "description": "Second major axis-property observed: Kind of Property (also called kind of quantity)",
            "type": "Coding"
          },
          {
            "code": "TIME_ASPCT",
            "uri": "http://loinc.org/property/TIME_ASPCT",
            "description": "Third major axis-timing of the measurement: Time Aspect (Point or moment in time vs. time interval)",
            "type": "Coding"
          },
          {
            "code": "SYSTEM",
            "uri": "http://loinc.org/property/SYSTEM",
            "description": "Fourth major axis-type of specimen or system: System (Sample) Type",
            "type": "Coding"
          },
          {
            "code": "SCALE_TYP",
            "uri": "http://loinc.org/property/SCALE_TYP",
            "description": "Fifth major axis-scale of measurement: Type of Scale",
            "type": "Coding"
          },
          {
            "code": "METHOD_TYP",
            "uri": "http://loinc.org/property/METHOD_TYP",
            "description": "Sixth major axis-method of measurement: Type of Method",
            "type": "Coding"
          },
          {
            "code": "CLASS",
            "uri": "http://loinc.org/property/CLASS",
            "description": "An arbitrary classification of the terms for grouping related observations together",
            "type": "string"
          },
          {
            "code": "VersionLastChanged",
            "uri": "http://loinc.org/property/VersionLastChanged",
            "description": "The LOINC version number in which the record has last changed. For new records, this field contains the same value as the FirstPublishedRelease property.",
            "type": "string"
          },
          {
            "code": "CONSUMER_NAME",
            "uri": "http://loinc.org/property/CONSUMER_NAME",
            "description": "An experimental (beta) consumer friendly name for this item. The intent is to provide a test name that health care consumers will recognize; it will be similar to the names that might appear on a lab report",
            "type": "string"
          },
          {
            "code": "CLASSTYPE",
            "uri": "http://loinc.org/property/CLASSTYPE",
            "description": "1=Laboratory class; 2=Clinical class; 3=Claims attachments; 4=Surveys",
            "type": "string"
          },
          {
            "code": "ORDER_OBS",
            "uri": "http://loinc.org/property/ORDER_OBS",
            "description": "Provides users with an idea of the intended use of the term by categorizing it as an order only, observation only, or both",
            "type": "string"
          },
          {
            "code": "HL7_ATTACHMENT_STRUCTURE",
            "uri": "http://loinc.org/property/HL7_ATTACHMENT_STRUCTURE",
            "description": "This property is populated in collaboration with the HL7 Attachments Work Group as described in the HL7 Attachment Specification: Supplement to Consolidated CDA Templated Guide.",
            "type": "string"
          },
          {
            "code": "VersionFirstReleased",
            "uri": "http://loinc.org/property/VersionFirstReleased",
            "description": "This is the LOINC version number in which this LOINC term was first published.",
            "type": "string"
          },
          {
            "code": "PanelType",
            "uri": "http://loinc.org/property/PanelType",
            "description": "For LOINC terms that are panels, this attribute classifies them as a 'Convenience group', 'Organizer', or 'Panel'",
            "type": "string"
          },
          {
            "code": "ValidHL7AttachmentRequest",
            "uri": "http://loinc.org/property/ValidHL7AttachmentRequest",
            "description": "A value of Y in this field indicates that this LOINC code can be sent by a payer as part of an HL7 Attachment request for additional information.",
            "type": "string"
          },
          {
            "code": "rad-modality-modality-type",
            "uri": "http://loinc.org/property/rad-modality-type",
            "description": "Modality is used to represent the device used to acquire imaging information.",
            "type": "Coding"
          },
          {
            "code": "rad-modality-modality-subtype",
            "uri": "http://loinc.org/property/rad-modality-subtype",
            "description": "Modality subtype may be optionally included to signify a particularly common or evocative configuration of the modality.",
            "type": "Coding"
          },
          {
            "code": "rad-anatomic-location-region-imaged",
            "uri": "http://loinc.org/property/rad-anatomic-location-region-imaged",
            "description": "The Anatomic Location Region Imaged attribute is used in two ways: as a coarse-grained descriptor of the area imaged and a grouper for finding related imaging exams; or, it is used just as a grouper.",
            "type": "Coding"
          },
          {
            "code": "rad-anatomic-location-imaging-focus",
            "uri": "http://loinc.org/property/rad-anatomic-location-imaging-focus",
            "description": "The Anatomic Location Imaging Focus is a more fine-grained descriptor of the specific target structure of an imaging exam. In many areas, the focus should be a specific organ.",
            "type": "Coding"
          },
          {
            "code": "rad-anatomic-location-laterality-presence",
            "uri": "http://loinc.org/property/rad-anatomic-location-laterality-presence",
            "description": "Radiology Exams that require laterality to be specified in order to be performed are signified with an Anatomic Location Laterality Presence attribute set to 'True'",
            "type": "Coding"
          },
          {
            "code": "rad-anatomic-location-laterality",
            "uri": "http://loinc.org/property/rad-anatomic-location-laterality",
            "description": "Radiology exam Laterality is specified as one of: Left, Right, Bilateral, Unilateral, Unspecified",
            "type": "Coding"
          },
          {
            "code": "rad-view-view-aggregation",
            "uri": "http://loinc.org/property/rad-view-aggregation",
            "description": "Aggregation describes the extent of the imaging performed, whether in quantitative terms (e.g., '3 or more views') or subjective terms (e.g., 'complete').",
            "type": "Coding"
          },
          {
            "code": "rad-view-view-type",
            "uri": "http://loinc.org/property/rad-view-view-type",
            "description": "View type names specific views, such as 'lateral' or 'AP'.",
            "type": "Coding"
          },
          {
            "code": "rad-maneuver-maneuver-type",
            "uri": "http://loinc.org/property/rad-maneuver-maneuver-type",
            "description": "Maneuver type indicates an action taken with the goal of elucidating or testing a dynamic aspect of the anatomy.",
            "type": "Coding"
          },
          {
            "code": "rad-timing",
            "uri": "http://loinc.org/property/rad-timing",
            "description": "The Timing/Existence property used in conjunction with pharmaceutical and manueuver properties. It specifies whether or not the imaging occurs in the presence of the administered pharmaceutical or a manuever designed to test some dynamic aspect of anatomy or physiology .",
            "type": "Coding"
          },
          {
            "code": "rad-pharmaceutical-substance-given",
            "uri": "http://loinc.org/property/rad-pharmaceutical-substance-given",
            "description": "The Pharmaceutical Substance Given specifies administered contrast agents, radiopharmaceuticals, medications, or other clinically important agents and challenges during the imaging procedure.",
            "type": "Coding"
          },
          {
            "code": "rad-pharmaceutical-route",
            "uri": "http://loinc.org/property/rad-pharmaceutical-route",
            "description": "Route specifies the route of administration of the pharmeceutical.",
            "type": "Coding"
          },
          {
            "code": "rad-reason-for-exam",
            "uri": "http://loinc.org/property/rad-reason-for-exam",
            "description": "Reason for exam is used to describe a clinical indication or a purpose for the study.",
            "type": "Coding"
          },
          {
            "code": "rad-guidance-for-presence",
            "uri": "http://loinc.org/property/rad-guidance-for-presence",
            "description": "Guidance for.Presence indicates when a procedure is guided by imaging.",
            "type": "Coding"
          },
          {
            "code": "rad-guidance-for-approach",
            "uri": "http://loinc.org/property/rad-guidance-for-approach",
            "description": "Guidance for.Approach refers to the primary route of access used, such as percutaneous, transcatheter, or transhepatic.",
            "type": "Coding"
          },
          {
            "code": "rad-guidance-for-action",
            "uri": "http://loinc.org/property/rad-guidance-for-action",
            "description": "Guidance for.Action indicates the intervention performed, such as biopsy, aspiration, or ablation.",
            "type": "Coding"
          },
          {
            "code": "rad-guidance-for-object",
            "uri": "http://loinc.org/property/rad-guidance-for-object",
            "description": "Guidance for.Object specifies the target of the action, such as mass, abscess or cyst.",
            "type": "Coding"
          },
          {
            "code": "rad-subject",
            "uri": "http://loinc.org/property/rad-subject",
            "description": "Subject is intended for use when there is a need to distinguish between the patient associated with an imaging study, and the target of the study.",
            "type": "Coding"
          },
          {
            "code": "document-kind",
            "uri": "http://loinc.org/property/document-kind",
            "description": "Characterizes the general structure of the document at a macro level.",
            "type": "Coding"
          },
          {
            "code": "document-role",
            "uri": "http://loinc.org/property/document-role",
            "description": "Characterizes the training or professional level of the author of the document, but does not break down to specialty or subspecialty..",
            "type": "Coding"
          },
          {
            "code": "document-setting",
            "uri": "http://loinc.org/property/document-setting",
            "description": "Setting is a modest extension of CMS’s coarse definition of care settings, such as outpatient, hospital, etc. Setting is not equivalent to location, which typically has more locally defined meanings.",
            "type": "Coding"
          },
          {
            "code": "document-subject-matter-domain",
            "uri": "http://loinc.org/property/document-subject-matter-domain",
            "description": "Characterizes the clinical domain that is the subject of the document. For example, Internal Medicine, Neurology, Physical Therapy, etc.",
            "type": "Coding"
          },
          {
            "code": "document-type-of-service",
            "uri": "http://loinc.org/property/document-type-of-service",
            "description": "Characterizes the kind of service or activity provided to/for the patient (or other subject of the service) that is described in the document.",
            "type": "Coding"
          },
          {
            "code": "answer-list",
            "uri": "http://loinc.org/property/answer-list",
            "description": "An answer list associated with this LOINC code (if there are matching answer lists defined). Only on normal LOINC Codes",
            "type": "Coding"
          },
          {
            "code": "answers-for",
            "uri": "http://loinc.org/property/answers-for",
            "description": "A LOINC Code for which this answer list is used. Only on normal LL- Codes",
            "type": "Coding"
          }
        ]
      },
      "search": {
        "mode": "match"
      }
    }
  ]
}

Get info on an individual LOINC term, Part, Answer List, or Answer string

Use the $lookup operation to see details on any of the LOINC identifiers. As illustrated in the following examples, you can pass the canonical LOINC URI and code to the CodeSystem endpoint to perform the operation.

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

Focus the request to return just what you want

Add a third parameter, &&property, to the examples above and you can limit the response to only the property—or properties—needed. As shown in the second example below, you can specify more than one property in a single request.

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

ValueSet

FHIR's ValueSet resource specifies a set of codes drawn from one or more code systems.

In LOINC's case, we have defined three main types of value sets:

Broadly useful collections
of LOINC terms

Answer Lists

e.g. LL4700-2

LOINC Groups

e.g. LG32763-1

Return the entire ValueSet resource

The examples below show how to call the ValueSet resource directly to give back the whole resource entry. This returns all the ValueSet metadata and definition criteria (i.e. which terms it includes). For example:

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

Alternatively, you can specify the same value set as:

https://fhir.loinc.org/ValueSet/LL1162-8

Get only the list of terms in the ValueSet

Use the $expand operation to only return the terms in a given value set (called a value set "expansion").

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

Determine if a term is in a ValueSet

Use the $validate-code operation to verify if a particular term is in the given ValueSet. This example will return a valueBoolean of true.

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 ValueSets because they are useful collections for various purposes. Here are the current collections and their identifiers:

LOINC Document Ontology

More information on this collection

http://loinc.org/vs/loinc-document-ontology

LOINC/RSNA Radiology Playbook

More information on this collection

http://loinc.org/vs/loinc-rsna-radiology-playbook

LOINC Top 2000+ Lab Observations

More information on these subsets

US Version (for mass-based reporting like mg/dL)

http://loinc.org/vs/top-2000-lab-observations-us

SI Version (for substance-based reporting like mmol/L)

http://loinc.org/vs/top-2000-lab-observations-si

 

LOINC Answer Lists as Value Sets

Brief background on answer lists in LOINC

LOINC contains links between many of its observation terms and a set of possible answers that could be used as result values. Within LOINC, we have created a structured representation of these answer lists.

LOINC Answer Lists are assigned a non-semantic identifier with a “LL” prefix and a Luhn/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.

Using LOINC Answer Lists

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

Determine if a LOINC Answer is in an Answer List

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

 

LOINC Groups as Value Sets

LOINC Groups are a technique for rolling up groups of LOINC terms 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.

LOINC Group as Value Set

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

Confirm a LOINC Code as a member of a Group

https://fhir.loinc.org/ValueSet/LG9568-9/$validate-code?system=http://loinc.org&code=6785-0

ConceptMap

The ConceptMap resource in FHIR defines a mapping from a set of concepts defined in a code system to one or more concepts defined in other code systems.

We have created several sets of LOINC mappings:

LOINC terms to IEEE device codes

LOINC Parts to RadLex clinical terms (RIDs)

LOINC terms to RadLex Playbook procedure codes (RPIDs)

LOINC Parts to PubChem terms

LOINC Parts to RxNorm terms

LOINC Parts to SNOMED CT terms

Return an entire ConceptMap Resource

In the examples below, calling the ConceptMap resource directly gives you back the whole resource entry for the specified set. This will give you all the ConceptMap metadata, the mappings, etc. Each ConceptMap resource is referenced using its canonical URI. For example:

https://fhir.loinc.org/ConceptMap/?url=http://loinc.org/cm/loinc-to-ieee-device-codes
https://fhir.loinc.org/ConceptMap/?url=http://loinc.org/cm/loinc-parts-to-radlex
https://fhir.loinc.org/ConceptMap/?url=http://loinc.org/cm/loinc-to-rpids
https://fhir.loinc.org/ConceptMap/?url=http://loinc.org/cm/loinc-parts-to-pubchem
https://fhir.loinc.org/ConceptMap/?url=http://loinc.org/cm/loinc-parts-to-rxnorm
https://fhir.loinc.org/ConceptMap/?url=http://loinc.org/cm/loinc-parts-to-snomed-ct

Get the mapping for a particular LOINC Code

Use the $translate operation to find a mapping for a particular source term.

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

Mappings are one way

All mappings are from the LOINC source to the external destination. In other words, you cannot perform a reverse mapping, e.g. use RID431 to find the corresponding LOINC Part LP199943-4.

Known Issues

There several items that need to be resolved in this BETA status of the service.

  • Externally defined answer lists are not present in CodeSystem and ValueSet. These LL codes can be identified using RELMA's Answer List search tab using the query ExternallyDefined:true.
  • Expansion of large value sets such as the LOINC Document Ontology result in an error.
  • Validate code operations on larger value sets including some LOINC Parent Groups are failing.
  • The ConceptMap loinc-parts-to-radlex mistakenly includes LOINC terms to RPIDs.