Terminology - Standardize

The Standardize Terminology API takes an input coding and finds matching reference codings from several standard code systems. It can also find codings using plain-text inputs from uncoded data.

Contents

Overview
- Mapping Methods
Operations
Inputs and Outputs
- Body Parameters
- Response Fields
Batch Operations

Overview

Each domain has its own standardize operation, but they all work in a similar manner. In the body parameters of the request, you provide what information you have about the input coding. You must provide either a code or display value (i.e., the plain-text description of the code you’re looking for). You may optionally provide a source code system (if known), and a target code system (to limit results to codes from a specific system).

Based on the domain, the Terminology service will search for matching codings from well-known reference code systems. Each domain uses different reference code systems. For example, medication codes may be standardized using codings from RxNorm and NDC, while report types may use LOINC and SNOMED. Consult the details of the individual standardize operations for a complete list of which reference code systems are used for each domain.

For example, you may start with only some free text:

Sample Standardize Input

{
    "display": "severe asthma"
}

The Terminology service will then find matching conditions in the appropriate reference code systems:

Sample Standardize Output

{
    "coding": [
        {
            "system": "http://snomed.info/sct",
            "code": "370221004",
            "display": "Severe asthma (disorder)",
            "mapMethod": "NLP"
        },
        {
            "system": "http://hl7.org/fhir/sid/icd-10-cm",
            "code": "J45.50",
            "display": "Severe persistent asthma, uncomplicated",
            "mapMethod": "Crosswalk"
        }
    ]
}

You could also start with just a code (e.g., "code": "370221004") and find matching conditions for that code (and comparable ones), even if you didn’t know the code system.

Tip
The system parameter is optional, but it is suggested that you provide it when possible. Some codes exist in multiple code systems with very different meanings, and providing context for the code you’re looking for helps the Terminology service to determine the most appropriate matches.

Mapping Methods

The mapMethod parameter in the output of Standardize API calls describes how each coding was determined from the original value. Possible mapping methods are:

Mapping Method	Description
`ExactCode`	The input `code` field exactly matched the coding.
`ParsedCode`	A value extracted from the input `code` field matched the coding. For example, in CPT/HCPCS codes with a modifier or suffix, the system could match `97140-97` to `97140`.
`ExactName`	The input display field exactly matches one of the unique reference display names for the coding.
`CodeInName`	The input `display` field actually contained a code that matched the coding.
`DataDictionary`	The input contained a commonly recognized alias for the coding.
`Crosswalk`	This is used when the same clinical concept exists in multiple code systems. For example, if the input is matched to an ICD-10-CM condition, the system can then include the corresponding SNOMED condition as well.
`NLP`	The match was determined using natural language processing of the input fields.

Operations

The following standardize operations are available:

Operation	Reference Code Systems
Condition Including problems and diagnoses.	ICD-10-CM ICD-9-CM-Diagnosis SNOMED
Medication Including immunizations.	RxNorm NDC CVX
Observation Including labs, radiology, and other observations.	LOINC SNOMED
Labs Including lab observations, panels, and reports (For mixed data, use Observation operation).	LOINC SNOMED
Radiology Including radiology observations and reports (For mixed data, use Observation operation).	LOINC SNOMED
Procedure Including services found in claims and clinical data.	ICD-10-PCS ICD-9-CM-Procedure HCPCS CDT SNOMED
UnitsOfMeasure	UCUM

Alternatively, you can use the $translate operation which is a superset of the individual domain-specific standardize operations.

Inputs and Outputs

The following fields are common to all standardize operations.

Body Parameters

code string

Code value. Either code or display is required.

display string

Display string. Either code or display is required.

system string

The source code system (as a name or URL).

targetSystem string

The desired code system (as a name or URL).

Response Fields

coding collection

List of matching code values.

Child Fields

coding.code string

Code value.

coding.system string

The source code system (as a URL).

coding.display string

Display string.

coding.mapMethod string

Describes how the coding was determined from the original field value. See Mapping Methods.

Batch Operations

Every standardize operation supports a batch mode to standardize multiple terminology codings at once.

POST /terminology/v1/standardize/{type}/batch

The input data contains an items array with the codings to standardize.

The output data will then contain an items array with the usual standardize output for each item.

Tip
The output items will be in the same order as the input items.

For example: /terminology/v1/standardize/medication/batch

Sample Batch Input

{
  "items": [
    {
      "code": "59267-1000-02"
    },
    {
       "display": "Jentadueto extended (linagliptin 2.5 / metFORMIN  1000mg)"
    }
  ]
}

Sample Batch Output

{
    "items": [
        {
            "coding": [
                {
                    "system": "http://hl7.org/fhir/sid/ndc",
                    "code": "59267100002",
                    "display": "SARS-CoV-2 (COVID-19) vaccine, mRNA-BNT162b2 0.1 MG/ML Injectable Suspension"
                },
                ...
            ]
        },
        {
            "coding": [
                {
                    "system": "http://www.nlm.nih.gov/research/umls/rxnorm",
                    "code": "1796093",
                    "display": "linagliptin 2.5 MG / metformin hydrochloride 1000 MG Extended Release Oral Tablet [Jentadueto]"
                }
            ]
        }
    ]
}