Mapping concepts across vocabularies

Get Mappings for a Concept

Find how a concept maps to other vocabularies:

const { data, error } = await client.mappings.get(201826); // Type 2 diabetes mellitus
if (error) throw new Error(error.message);

for (const mapping of data.mappings) {
  console.log(`${mapping.relationship_id}: ${mapping.target_concept_name}`);
}

get() returns one page. pageSize 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 getAll() or getIter() below.

Get Every Mapping

getAll() walks all pages and collects them. Errors are accumulated rather than thrown, so a partial result is distinguishable from a complete one:

const { data, errors, pagesFetched } = await client.mappings.getAll(201826);
if (errors.length > 0) throw new Error(errors[0].message);

console.log(`${data.length} mappings across ${pagesFetched} pages`);

getIter() is the streaming equivalent - it yields one mapping at a time and throws OMOPHubIteratorError on the first failed page:

for await (const mapping of client.mappings.getIter(201826)) {
  console.log(`${mapping.relationship_id}: ${mapping.target_concept_name}`);
}

Both accept the same filters as get(), plus pageSize and maxPages:

const { data } = await client.mappings.getAll(201826, {
  targetVocabulary: 'ICD10CM',
  pageSize: 200,
});

Page Through Manually

const { data, meta } = await client.mappings.get(201826, {
  page: 2,
  pageSize: 200,
});

console.log(meta?.pagination?.total_items, meta?.pagination?.has_next);

Filter by Target Vocabulary

const { data } = await client.mappings.get(201826, {
  targetVocabulary: 'ICD10CM',
});

for (const mapping of data?.mappings ?? []) {
  console.log(`${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:

const { data } = await client.mappings.get(4167462, {
  relationshipIds: ['Maps to', 'Maps to value'],
});
for (const mapping of data.mappings) {
  console.log(`${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. getIter() and getAll() take the same option.

Invalid Mappings

includeInvalid defaults to true on this endpoint. Pass false to return only mappings whose relationship and target concept are currently valid:

await client.mappings.get(201826, {
  targetVocabulary: 'ICD10CM',
  includeInvalid: 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

await client.mappings.get(201826, {
  targetVocabulary: 'ICD10CM',
  vocabRelease: '2025.1',
});

Map Multiple Concepts

Map a batch of concept IDs to a target vocabulary:

const { data } = await client.mappings.map({
  targetVocabulary: 'ICD10CM',
  sourceConcepts: [201826, 4329847], // Diabetes, MI
});

for (const mapping of data?.mappings ?? []) {
  console.log(`${mapping.source_concept_id} → ${mapping.target_concept_id}`);
}

Map Using Vocabulary Codes

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

const { data } = await client.mappings.map({
  targetVocabulary: 'RxNorm',
  sourceCodes: [
    { vocabulary_id: 'SNOMED', concept_code: '387517004' }, // Acetaminophen
    { vocabulary_id: 'SNOMED', concept_code: '108774000' }, // Anastrozole
  ],
});

for (const mapping of data?.mappings ?? []) {
  console.log(
    `${mapping.source_concept_name} → ${mapping.target_concept_name}`
  );
}

Use sourceCodes when you have vocabulary-specific codes (e.g. SNOMED codes from your source system). Use sourceConcepts when you already have OMOP concept IDs. You cannot use both in the same request - the SDK enforces this at the type level via a discriminated union and re-validates at runtime so JS callers also get a structured missing_required_field error rather than a wire 400.

Map with Specific Mapping Type

Filter mappings by type:

await client.mappings.map({
  targetVocabulary: 'ICD10CM',
  sourceConcepts: [201826, 192671],
  mappingType: 'direct', // 'direct' | 'equivalent' | 'broader' | 'narrower'
});

Vocabulary Release Pinning

vocabRelease is sent as a query-string parameter, not in the JSON body - matches the Python SDK convention:

await client.mappings.map({
  targetVocabulary: 'SNOMED',
  sourceConcepts: [201826],
  vocabRelease: '2025.1',
});
// → POST /concepts/map?vocab_release=2025.1

Procedure-Domain Vocabulary Priority

For Procedure-domain sources, the API applies a fallback vocabulary priority when targetVocabulary is left to “best fit” semantics:

SNOMED → LOINC → CPT4 → HCPCS → ICD10PCS → ICD9Proc → OPCS4 → OMOP Extension

Common Use Case: SNOMED → ICD-10

Option 1: Direct mapping using vocabulary codes (recommended)

const { data } = await client.mappings.map({
  targetVocabulary: 'ICD10CM',
  sourceCodes: [
    { vocabulary_id: 'SNOMED', concept_code: '44054006' }, // Type 2 diabetes
  ],
});

for (const m of data?.mappings ?? []) {
  console.log(`  → ${m.target_concept_name} (${m.target_concept_code})`);
}

Option 2: Using OMOP concept IDs

// First resolve the OMOP concept ID
const lookup = await client.concepts.getByCode('SNOMED', '44054006');
if (lookup.error || !lookup.data) throw new Error('Concept not found');

// Then map using the concept ID
const { data } = await client.mappings.get(lookup.data.concept_id, {
  targetVocabulary: 'ICD10CM',
});

console.log(`Mappings for ${lookup.data.concept_name}:`);
for (const m of data?.mappings ?? []) {
  console.log(`  → ${m.target_concept_name}`);
}

Idempotency

POST endpoints (mappings.map) only retry on transient failures when an Idempotency-Key is provided:

await client.mappings.map({
  targetVocabulary: 'SNOMED',
  sourceConcepts: [201826],
  idempotencyKey: 'my-pipeline-run-2026-05-30-batch-1',
});

Parameters

Parameter	Type	Default	Description
`targetVocabulary`	string	required	Target vocabulary ID (e.g. `'SNOMED'`, `'RxNorm'`)
`sourceConcepts`	number[]	XOR with `sourceCodes`	OMOP concept IDs to map
`sourceCodes`	`{ vocabulary_id, concept_code }[]`	XOR with `sourceConcepts`	Native vocabulary codes
`mappingType`	`'direct' \| 'equivalent' \| 'broader' \| 'narrower'`	-	Filter mappings by type
`includeInvalid`	boolean	false	Include deprecated mappings
`vocabRelease`	string	-	Pin to a vocabulary release (sent as query param)
`idempotencyKey`	string	-	Per-call `Idempotency-Key` header (enables retry on 5xx)

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

Vocabulary Release Pinning

Procedure-Domain Vocabulary Priority

Common Use Case: SNOMED → ICD-10

Idempotency

Parameters

​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

​Vocabulary Release Pinning

​Procedure-Domain Vocabulary Priority

​Common Use Case: SNOMED → ICD-10

​Idempotency

​Parameters

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

Vocabulary Release Pinning

Procedure-Domain Vocabulary Priority

Common Use Case: SNOMED → ICD-10

Idempotency

Parameters