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) {
  cat(sprintf("%s: %s\n", 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_all() below.

Get Every Mapping

get_all() walks all pages and returns a single tibble:

all_mappings <- client$mappings$get_all(201826)
nrow(all_mappings)

It takes max_pages and progress like the other *_all() methods:

all_mappings <- client$mappings$get_all(
  201826,
  target_vocabulary = "ICD10CM",
  progress = FALSE
)

Page Through Manually

result <- client$mappings$get(201826, page = 2, page_size = 200)

# Pagination state is attached as an attribute
pagination <- attr(result, "pagination")
pagination$total_items
pagination$has_next

Filter by Target Vocabulary

Get mappings to a specific vocabulary only:

result <- client$mappings$get(
  201826,
  target_vocabulary = "ICD10CM"
)
for (mapping in result$mappings) {
  cat(sprintf("%s: %s\n", 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 = c("Maps to", "Maps to value")
)
for (mapping in result$mappings) {
  cat(mapping$relationship_id, ":", mapping$target_concept_name, "\n")
}
# 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. get_all() 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.

This parameter was accepted but not applied before 2026-08-11. The default matches what the endpoint returned then, so nothing changes unless you pass FALSE.

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 = c(201826, 4329847)  # Diabetes, MI
)
for (mapping in result$mappings) {
  source <- mapping$source_concept_id
  target <- mapping$target_concept_id
  cat(sprintf("%s -> %s\n", 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 = list(
    list(vocabulary_id = "SNOMED", concept_code = "387517004"),  # Acetaminophen
    list(vocabulary_id = "SNOMED", concept_code = "108774000")   # Anastrozole
  )
)
for (mapping in result$mappings) {
  cat(sprintf("%s -> %s\n", 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 = c(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 = list(
    list(vocabulary_id = "SNOMED", concept_code = "44054006")  # Type 2 diabetes
  )
)
for (m in result$mappings) {
  cat(sprintf("  -> %s (%s)\n", 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"
)

cat(sprintf("Mapping %s:\n", concept$concept_name))
for (m in mappings$mappings) {
  cat(sprintf("  -> %s (confidence: %s)\n", m$target_concept_name, m$confidence))
}

Working with Mapping Results

Convert mappings to a data frame for analysis:

result <- client$mappings$get(201826)

# Create a data frame from mappings
mapping_df <- do.call(rbind, lapply(result$mappings, function(m) {
  data.frame(
    source_id = m$source_concept_id,
    source_name = m$source_concept_name,
    target_id = m$target_concept_id,
    target_name = m$target_concept_name,
    relationship = m$relationship_id,
    confidence = m$confidence,
    stringsAsFactors = FALSE
  )
}))

print(mapping_df)

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

Working with Mapping Results

​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

​Working with Mapping Results

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

Working with Mapping Results