curl -X GET "https://api.omophub.com/v1/concepts/35207668/mappings?page=1&page_size=100" \
-H "Authorization: Bearer YOUR_API_KEY"
import { OMOPHub } from '@omophub/omophub-node';
const client = new OMOPHub();
// Every mapping, not just the first page
const { data, errors } = await client.mappings.getAll(35207668);
if (errors.length > 0) throw new Error(errors[0].message);
console.log(`Found ${data.length} mappings`);
from omophub import OMOPHub
client = OMOPHub()
# Every mapping, not just the first page
mappings = list(client.mappings.get_iter(35207668))
print(f"Found {len(mappings)} mappings")
{
"success": true,
"data": {
"mappings": [
{
"source_concept_id": 35207668,
"source_concept_name": "Essential (primary) hypertension",
"source_concept_code": "I10",
"source_vocabulary_id": "ICD10CM",
"target_concept_id": 320128,
"target_concept_name": "Essential hypertension",
"target_concept_code": "59621000",
"target_vocabulary_id": "SNOMED",
"target_domain_id": "Condition",
"target_standard_concept": "S",
"relationship_id": "Maps to",
"relationship_name": "Non-standard to Standard map (OMOP)",
"valid_start_date": "1969-12-31T23:00:00.000Z",
"valid_end_date": "2099-12-31T00:00:00.000Z",
"invalid_reason": null,
"mapping_type": "direct"
}
]
},
"meta": {
"request_id": "req_abc123",
"timestamp": "2025-01-05T12:00:00.000Z",
"vocab_release": "2025.2",
"pagination": {
"page": 1,
"page_size": 100,
"total_items": 1,
"total_pages": 1,
"has_next": false,
"has_previous": false
}
}
}
Get Concept Mappings
curl -X GET "https://api.omophub.com/v1/concepts/35207668/mappings?page=1&page_size=100" \
-H "Authorization: Bearer YOUR_API_KEY"
import { OMOPHub } from '@omophub/omophub-node';
const client = new OMOPHub();
// Every mapping, not just the first page
const { data, errors } = await client.mappings.getAll(35207668);
if (errors.length > 0) throw new Error(errors[0].message);
console.log(`Found ${data.length} mappings`);
from omophub import OMOPHub
client = OMOPHub()
# Every mapping, not just the first page
mappings = list(client.mappings.get_iter(35207668))
print(f"Found {len(mappings)} mappings")
{
"success": true,
"data": {
"mappings": [
{
"source_concept_id": 35207668,
"source_concept_name": "Essential (primary) hypertension",
"source_concept_code": "I10",
"source_vocabulary_id": "ICD10CM",
"target_concept_id": 320128,
"target_concept_name": "Essential hypertension",
"target_concept_code": "59621000",
"target_vocabulary_id": "SNOMED",
"target_domain_id": "Condition",
"target_standard_concept": "S",
"relationship_id": "Maps to",
"relationship_name": "Non-standard to Standard map (OMOP)",
"valid_start_date": "1969-12-31T23:00:00.000Z",
"valid_end_date": "2099-12-31T00:00:00.000Z",
"invalid_reason": null,
"mapping_type": "direct"
}
]
},
"meta": {
"request_id": "req_abc123",
"timestamp": "2025-01-05T12:00:00.000Z",
"vocab_release": "2025.2",
"pagination": {
"page": 1,
"page_size": 100,
"total_items": 1,
"total_pages": 1,
"has_next": false,
"has_previous": false
}
}
}
Overview
Retrieve mappings from a concept to equivalent or related concepts in other vocabulary systems. Each row carries the target’starget_domain_id and target_standard_concept,
so a single call is enough both to route the mapping to the right CDM table
and to verify that a Maps to target is standard. Neither previously
required a second request per target; before 2026-09-09 the response omitted
both fields and each one did.
The row shape matches
POST /v1/concepts/map field for field, plus
target_domain_id, target_standard_concept. Use this endpoint for one
concept, map for up to 100.OMOP vocabulary releases do not provide a measured probability or confidence
for each mapping, so this endpoint does not publish a confidence score. Use
relationship_id, mapping_type, invalid_reason, and
target_standard_concept to interpret and validate each mapping.Path Parameters
integer
required
The OMOP concept ID to get mappings for
Query Parameters
string
Filter mappings to a specific target vocabulary (e.g., “ICD10CM”, “SNOMED”)
string
Comma-separated relationship types to return. Defaults to
Maps to.Use Maps to,Maps to value to include the Value-as-Concept decomposition of
composite concepts. Like include_invalid, this parameter was accepted but
not applied before 2026-08-11.integer
default:"1"
Page number, 1-based
integer
default:"100"
Mappings per page. Values above 200 are clamped to 200 without an error, so
requesting more returns a smaller page than asked for.
boolean
default:"true"
Include mappings whose relationship or target concept is deprecated. Defaults
to
true - pass false to return only currently-valid mappings.Note that POST /v1/concepts/map defaults this to false. The two differ
deliberately: this endpoint lists what exists for one concept, where hiding
deprecated mappings would misrepresent the record, while map resolves sources
for downstream use. Pass the parameter explicitly on both if you need them to
agree.The source concept itself is never filtered, so a deprecated concept still
returns what it maps to.string
Specific vocabulary release version to use (e.g., “2025.1”, “2024.2”). When
not specified, uses the default/latest vocabulary version.
Response
boolean
Indicates if the request was successful
object
Contains the mapping results
Show data
Show data
array
Array of concept mappings
Show mappings
Show mappings
integer
OMOP concept ID of the source concept
string
Name of the source concept
string
The source concept’s code within its own vocabulary
string
Vocabulary the source concept belongs to (e.g., “ICD10CM”)
integer
OMOP concept ID of the mapped target concept
string
Name of the target concept
string
The target concept’s code within its own vocabulary
string
Vocabulary the target concept belongs to (e.g., “SNOMED”)
string
The target’s OMOP domain — this is what decides which CDM table the
row belongs in.
Condition goes to condition_occurrence, Drug to
drug_exposure, Measurement to measurement, Procedure to
procedure_occurrence, Observation to observation.Read it from the target, never from the source. Cross-domain maps
are ordinary: ICD10CM P09.6 is a Condition code whose two Maps to
targets are a Condition and a Measurement, so the source’s domain
does not determine the destination — and within a single response,
different rows can belong in different tables.string | null
S for a standard concept, C for a classification concept, null
otherwise.Every valid Maps to target is expected to be standard. A Maps to
row whose target_standard_concept is anything but S should not be
written to a CDM — a non-standard target silently corrupts it. This
field is what makes that check possible from the mapping response
itself, instead of one extra request per target.string
Type of relationship (e.g., “Maps to”)
string
Human-readable name of the relationship (e.g., “Non-standard to
Standard map (OMOP)”)
string
When the mapping relationship became valid, ISO 8601.These three validity fields describe the
concept_relationship row —
the mapping itself — not either concept, matching their meaning on
POST /v1/concepts/map. To exclude mappings whose target concept is
deprecated, use include_invalid=false, which filters on both the
relationship and the target.string
When the mapping relationship stops being valid, ISO 8601.
2099-12-31 means “currently valid”.string | null
D (deleted) or U (updated) if the mapping relationship has been
deprecated, null if it is current.string
direct (Maps to, Mapped from), equivalent, broader,
narrower, or related.object
Response metadata
Show meta
Show meta
string
Unique request identifier for tracing and support
string
ISO 8601 timestamp of when the request was processed
string
Vocabulary release version used for this request
object
Pagination state for this response
Examples
curl -X GET "https://api.omophub.com/v1/concepts/35207668/mappings?page=1&page_size=100" \
-H "Authorization: Bearer YOUR_API_KEY"
import { OMOPHub } from '@omophub/omophub-node';
const client = new OMOPHub();
// Every mapping, not just the first page
const { data, errors } = await client.mappings.getAll(35207668);
if (errors.length > 0) throw new Error(errors[0].message);
console.log(`Found ${data.length} mappings`);
from omophub import OMOPHub
client = OMOPHub()
# Every mapping, not just the first page
mappings = list(client.mappings.get_iter(35207668))
print(f"Found {len(mappings)} mappings")
{
"success": true,
"data": {
"mappings": [
{
"source_concept_id": 35207668,
"source_concept_name": "Essential (primary) hypertension",
"source_concept_code": "I10",
"source_vocabulary_id": "ICD10CM",
"target_concept_id": 320128,
"target_concept_name": "Essential hypertension",
"target_concept_code": "59621000",
"target_vocabulary_id": "SNOMED",
"target_domain_id": "Condition",
"target_standard_concept": "S",
"relationship_id": "Maps to",
"relationship_name": "Non-standard to Standard map (OMOP)",
"valid_start_date": "1969-12-31T23:00:00.000Z",
"valid_end_date": "2099-12-31T00:00:00.000Z",
"invalid_reason": null,
"mapping_type": "direct"
}
]
},
"meta": {
"request_id": "req_abc123",
"timestamp": "2025-01-05T12:00:00.000Z",
"vocab_release": "2025.2",
"pagination": {
"page": 1,
"page_size": 100,
"total_items": 1,
"total_pages": 1,
"has_next": false,
"has_previous": false
}
}
}
Related Endpoints
- Map Concepts - Map multiple concepts to a target vocabulary
- Batch Map Concepts - Batch mapping operations
Was this page helpful?