Skip to main content

​
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["data"]["mappings"]:
    print(f"{mapping['relationship_id']}: {mapping['target_concept_name']}")

​
Filter by Target Vocabulary

Get mappings to a specific vocabulary only: 
result = client.mappings.get(
    201826,
    target_vocabulary="ICD10CM",
)
for mapping in result["data"]["mappings"]:
    print(f"{mapping['target_concept_id']}: {mapping['target_concept_name']}")

​
Include Invalid Mappings

Include deprecated or invalid mappings in results: 
result = client.mappings.get(
    201826,
    target_vocabulary="ICD10CM",
    include_invalid=True,
)

​
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["data"]["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["data"]["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["data"]["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["data"]["mappings"]:
    print(f"  -> {m['target_concept_name']} (confidence: {m['confidence']})")