ConceptMap Resource

GET /terminology/v1/fhir/r4/ConceptMap/

The ConceptMap Resource represents a set of translations between two distinct CodeSystems.

Using ConceptMaps

Typically ConceptMap resources may mean something like a SNOMED to ICD-10-CM “crosswalk”; which will provide a mapping between equivalent SNOMED and ICD-10-CM concepts.

The Terminology API also utilizes the ConceptMap Resource to represent “source to reference” mappings. These ConceptMaps are especially useful for standardizing disparate source codings. Non-standard source codings may be things like:

• Codes where a CodeSystem is not supplied (i.e. E119 with no additional information).
• Varied formattings of codes (i.e. the “dashed” NDC format versus the commonly used 11 digit one).
• Freetext strings that may be represented by a reference code (i.e. Advil 200 mg cap).

Typically, if you are unsure of your source data provenance, or unsure of the degree of adherence to reference standards, you should standardize source codes to a reference code/CodeSystem using the /ConceptMap/$translate operation before using the code in subsequent operations.

Please see the FHIR documentation for the complete specification for the ConceptMap Resource. Some common operations are summarized below.

Standardizing a Source Code ($translate)

The Terminology API uses the $translate operation on the ConceptMap Resource to standardize source codings to a reference code. The simplest way to do this is to use a GET call the $translate operation with a code parameter. The code parameter should represent your best source description of the concept. This may be things such as:

• A well formatted code without the context of a CodeSystem (i.e. E11.9).
• A code with an uncommon formatting (i.e. an NDC in the “dashed” format - 63739-434-01, or an ICD10 code with the dot omitted - E119).
• A string with a comingled text description and a code (i.e. Diabetes Type 2 E11.9).
• An uncoded string with only a text description (i.e. Advil 200mg caps).

The $translate operation will return a Parameters object as a response. The parameter named result will indicate if the Terminology service was able to standardize the code with "valueBoolean": true. If so, the standardized codes will be contained as a collection in the parameter named match, with alternate display names captured in valueCoding.extension.

GET https://api.careevolutionapi.com/terminology/v1/fhir/r4/ConceptMap/$translate?code=E119

{
  "resourceType": "Parameters",
    "parameter": [
        {
            "name": "result",
            "valueBoolean": true
        },
        {
            "name": "match",
            "part": [
                {
                    "name": "equivalence",
                    "valueCode": "equal"
                },
                {
                    "name": "concept",
                    "valueCoding": {
                        "extension": [
                            {
                                "url": "http://api.careevolutionapi.com/fhir/extensions/name#loinc-long-common-name",
                                "valueString": "Hemoglobin A1c/Hemoglobin.total in Blood"
                            },
                            {
                                "url": "http://api.careevolutionapi.com/fhir/extensions/name#loinc-display-name",
                                "valueString": "HbA1c (Bld) [Mass fraction]"
                            },
                            {
                                "url": "https://rosetta.careevolution.com/fhir/translate-dependency/domain",
                                "valueString": "Reference"
                            }
                        ],
                        "system": "http://loinc.org",
                        "code": "4548-4",
                        "display": "HbA1c MFr Bld"
                    }
                },
                {
                    "name": "source",
                    "valueString": "https://api.careevolutionapi.com/terminology/v1/fhir/r4/ConceptMap/LOINC"
                },
        ...
    ]
}

Standardizing a Code with a Known Domain ($translate)

If available, additional context such as the source domain may result in a more specific standardization of a source code. In these situations a domain parameter may be passed in with one of the available values listed below.

This form of the operation will return the same Parameters object as above, but it will typically have more specific and relevant matches.

GET https://api.careevolutionapi.com/terminology/v1/fhir/r4/ConceptMap/$translate?code=Advil 200mg caps&domain=Medication

{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "result",
            "valueBoolean": true
        },
        {
            "name": "match",
            "part": [
                {
                    "name": "equivalence",
                    "valueCode": "equal"
                },
                {
                    "name": "concept",
                    "valueCoding": {
                        "extension": [
                            {
                                "url": "https://rosetta.careevolution.com/api/translate-dependency/domain",
                                "valueString": "Reference"
                            }
                        ],
                        "system": "http://www.nlm.nih.gov/research/umls/rxnorm",
                        "code": "731533",
                        "display": "ibuprofen 200 MG Oral Capsule [Advil]"
                    }
                },
                {
                    "name": "source",
                    "valueString": "https://api.careevolutionapi.com/terminology/v1/fhir/r4/ConceptMap/RxNorm"
                }
            ]
        }
    ]
}

Please see the FHIR documentation for the complete specification of the $translate operation.

Available Domains