Mapping concepts across vocabularies

Get Mappings for a Concept

Find how a concept maps to other vocabularies:

result = client.mappings.get(201826)  # Type 2 diabetes mellitus
for mapping in result["mappings"]:
    print(f"{mapping['relationship_id']}: {mapping['target_concept_name']}")

get() returns one page. page_size defaults to 100 and the server caps it at 200, so a concept with more mappings than that yields a subset that looks exactly like a complete answer. When you are building a code list, use get_iter() below.

Get Every Mapping

get_iter() walks all pages and yields each mapping, so you never have to decide whether one page was the whole set:

for mapping in client.mappings.get_iter(201826):
    print(f"{mapping['relationship_id']}: {mapping['target_concept_name']}")

The async client has the same method:

async for mapping in async_client.mappings.get_iter(201826):
    ...

Page Through Manually

If you would rather control the paging yourself:

result = client.mappings.get(201826, page=2, page_size=200)

get() returns the response’s data field only, so the meta.pagination.has_next that would tell you whether more pages exist is not part of what you get back. That is why get_iter() exists - prefer it over looping on get() and guessing from the page length.

Filter by Target Vocabulary

Get mappings to a specific vocabulary only:

result = client.mappings.get(
    201826,
    target_vocabulary="ICD10CM",
)
for mapping in result["mappings"]:
    print(f"{mapping['target_concept_id']}: {mapping['target_concept_name']}")

Relationship Types

The endpoint returns Maps to relationships by default. Composite concepts decompose across two relationships, and asking only for the default gets you half the answer:

result = client.mappings.get(
    4167462,  # Allergy to penicillin G
    relationship_ids=["Maps to", "Maps to value"],
)
for mapping in result["mappings"]:
    print(f"{mapping['relationship_id']}: {mapping['target_concept_name']}")
# Maps to: Allergy to drug
# Maps to value: penicillin G

Without Maps to value you learn the patient is allergic to a drug but not which drug. This is the Value-as-Concept pattern - the target belongs in value_as_concept_id on the OMOP row, not in the main concept column. A comma-separated string works too, and get_iter() takes the same argument.

Invalid Mappings

include_invalid defaults to True on this endpoint. Pass False to return only mappings whose relationship and target concept are currently valid:

result = client.mappings.get(
    201826,
    target_vocabulary="ICD10CM",
    include_invalid=False,
)

The source concept is never filtered, so a deprecated concept still returns what it maps to - which is usually why you looked it up.

Use Specific Vocabulary Version

Query mappings from a specific vocabulary release:

result = client.mappings.get(
    201826,
    target_vocabulary="ICD10CM",
    vocab_release="2025.1",
)

Map Multiple Concepts

Map a batch of concept IDs to a target vocabulary:

result = client.mappings.map(
    target_vocabulary="ICD10CM",
    source_concepts=[201826, 4329847],  # Diabetes, MI
)
for mapping in result["mappings"]:
    source = mapping["source_concept_id"]
    target = mapping["target_concept_id"]
    print(f"{source} -> {target}")

Map Using Vocabulary Codes

Map concepts directly using vocabulary codes instead of OMOP concept IDs:

result = client.mappings.map(
    target_vocabulary="RxNorm",
    source_codes=[
        {"vocabulary_id": "SNOMED", "concept_code": "387517004"},  # Acetaminophen
        {"vocabulary_id": "SNOMED", "concept_code": "108774000"},  # Anastrozole
    ],
)
for mapping in result["mappings"]:
    print(f"{mapping['source_concept_name']} -> {mapping['target_concept_name']}")

Use source_codes when you have vocabulary-specific codes (e.g., SNOMED codes from your source system). Use source_concepts when you already have OMOP concept IDs. You cannot use both parameters in the same request.

Map with Specific Mapping Type

Filter mappings by type:

result = client.mappings.map(
    target_vocabulary="ICD10CM",
    source_concepts=[201826, 192671],
    mapping_type="direct",  # "direct", "equivalent", "broader", "narrower"
)

Common Use Case: SNOMED to ICD-10

Option 1: Direct mapping using vocabulary codes (recommended)

result = client.mappings.map(
    target_vocabulary="ICD10CM",
    source_codes=[
        {"vocabulary_id": "SNOMED", "concept_code": "44054006"},  # Type 2 diabetes
    ],
)
for m in result["mappings"]:
    print(f"  -> {m['target_concept_name']} ({m['target_concept_code']})")

Option 2: Using OMOP concept IDs

# First get the OMOP concept ID
concept = client.concepts.get_by_code("SNOMED", "44054006")

# Then map using the concept ID
mappings = client.mappings.get(
    concept["concept_id"],
    target_vocabulary="ICD10CM",
)

print(f"Mapping {concept['concept_name']}:")
for m in mappings["mappings"]:
    print(f"  -> {m['target_concept_name']} (confidence: {m['confidence']})")

Python SDK

Node.js / TypeScript SDK

R SDK

Mapping concepts across vocabularies

Get Mappings for a Concept

Get Every Mapping

Page Through Manually

Filter by Target Vocabulary

Relationship Types

Invalid Mappings

Use Specific Vocabulary Version

Map Multiple Concepts

Map Using Vocabulary Codes

Map with Specific Mapping Type

Common Use Case: SNOMED to ICD-10

​Get Mappings for a Concept

​Get Every Mapping

​Page Through Manually

​Filter by Target Vocabulary

​Relationship Types

​Invalid Mappings

​Use Specific Vocabulary Version

​Map Multiple Concepts

​Map Using Vocabulary Codes

​Map with Specific Mapping Type

​Common Use Case: SNOMED to ICD-10

Get Mappings for a Concept

Get Every Mapping

Page Through Manually

Filter by Target Vocabulary

Relationship Types

Invalid Mappings

Use Specific Vocabulary Version

Map Multiple Concepts

Map Using Vocabulary Codes

Map with Specific Mapping Type

Common Use Case: SNOMED to ICD-10