mapping-loinc

Mapping lab/observation names to LOINC

Ground free-text lab and observation names that OpenMed surfaces to LOINC (Logical Observation Identifiers Names and Codes), the universal standard for identifying what was measured. A LOINC code is a fully specified observation — not just an analyte but the full six-axis model: Component, Property, Time, System (specimen), Scale, Method.

LOINC is free to use. It is published by the Regenstrief Institute under the LOINC license: you accept terms-of-use (and register to download the table), but there is no fee and no per-use restriction. The standard, public path for license-clean mapping is a FHIR terminology server exposing LOINC via $lookup / $validate-code, or Regenstrief's hosted fhir.loinc.org.

When to use

• A note or report contains lab/observation names ("serum potassium", "hemoglobin A1c", "blood pressure") and you need a stable LOINC code each.
• You must disambiguate by specimen/system ("glucose in serum" vs "glucose in urine") or method ("HbA1c by HPLC").
• You need UCUM units to pair with the result value, or a US Core Observation (Laboratory Result) coded with LOINC.
• You are mapping a panel (e.g. CBC, BMP) vs its individual analytes.

For diagnoses/procedures use coding-icd10; for drugs use normalizing-rxnorm; LOINC is for observations and measurements.

Quick start (real LOINC / FHIR terminology calls)

Regenstrief hosts a public FHIR terminology endpoint at https://fhir.loinc.org (HTTP Basic auth with your free LOINC account). Many sites instead point at their own server (HAPI, Ontoserver, Snowstorm-with-LOINC). The operations are the same.

import requests
from requests.auth import HTTPBasicAuth

FHIR = "https://fhir.loinc.org"
AUTH = HTTPBasicAuth("YOUR_LOINC_USER", "YOUR_LOINC_PASSWORD")  # free account
LOINC_SYSTEM = "http://loinc.org"

def lookup(code: str) -> dict:
    """$lookup: return the fully specified name + axes for a LOINC code."""
    r = requests.get(
        f"{FHIR}/CodeSystem/$lookup",
        params={"system": LOINC_SYSTEM, "code": code},
        auth=AUTH, headers={"Accept": "application/fhir+json"}, timeout=15,
    )
    r.raise_for_status()
    return r.json()

def validate(code: str, display: str) -> bool:
    r = requests.get(
        f"{FHIR}/CodeSystem/$validate-code",
        params={"url": LOINC_SYSTEM, "code": code, "display": display},
        auth=AUTH, headers={"Accept": "application/fhir+json"}, timeout=15,
    )
    r.raise_for_status()
    params = {p["name"]: p.get("valueBoolean") for p in r.json().get("parameter", [])}
    return bool(params.get("result"))

print(lookup("2823-3"))     # Potassium [Moles/volume] in Serum or Plasma