curl -X GET "https://api.omophub.com/v1/concepts/201826/ancestors?include_paths=true&include_distance=true&max_levels=5" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json"
import { OMOPHub } from '@omophub/omophub-node';
const client = new OMOPHub();
const { data: ancestorData } = await client.hierarchy.ancestors(201826, {
includePaths: true,
includeDistance: true,
maxLevels: 5,
});
console.log(
`Found ${ancestorData?.hierarchy_summary.total_ancestors} ancestors`
);
console.log('First ancestor:', ancestorData?.ancestors[0]?.concept_name);
import requests
concept_id = 201826 # Type 2 diabetes mellitus
url = f"https://api.omophub.com/v1/concepts/{concept_id}/ancestors"
params = {
"include_paths": True,
"include_distance": True,
"max_levels": 5
}
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
}
response = requests.get(url, params=params, headers=headers)
ancestor_data = response.json()
print(f"Concept: {ancestor_data['data']['concept_name']}")
print(f"Total ancestors: {ancestor_data['data']['hierarchy_summary']['total_ancestors']}")
for ancestor in ancestor_data['data']['ancestors'][:5]:
level = ancestor.get('level', 'Unknown')
print(f"Level {level}: {ancestor['concept_name']} ({ancestor['concept_id']})")
{
"success": true,
"data": {
"concept_id": 201826,
"concept_name": "Type 2 diabetes mellitus",
"vocabulary_id": "SNOMED",
"ancestors": [
{
"concept_id": 73211009,
"concept_name": "Diabetes mellitus",
"concept_code": "73211009",
"vocabulary_id": "SNOMED",
"vocabulary_name": "SNOMED Clinical Terms",
"domain_id": "Condition",
"concept_class_id": "Clinical Finding",
"standard_concept": "S",
"level": 1,
"min_levels_of_separation": 1,
"max_levels_of_separation": 1,
"relationship_id": "Is a",
"relationship_name": "Is a",
"hierarchy_level": 1,
"valid_start_date": "1970-01-01",
"valid_end_date": "2099-12-31",
"invalid_reason": null
},
{
"concept_id": 362969004,
"concept_name": "Disorder of endocrine system",
"concept_code": "362969004",
"vocabulary_id": "SNOMED",
"vocabulary_name": "SNOMED Clinical Terms",
"domain_id": "Condition",
"concept_class_id": "Clinical Finding",
"standard_concept": "S",
"level": 2,
"min_levels_of_separation": 2,
"max_levels_of_separation": 2,
"relationship_id": "Is a",
"relationship_name": "Is a",
"hierarchy_level": 2,
"valid_start_date": "2002-01-31",
"valid_end_date": "2099-12-31",
"invalid_reason": null
},
{
"concept_id": 64572001,
"concept_name": "Disease",
"concept_code": "64572001",
"vocabulary_id": "SNOMED",
"vocabulary_name": "SNOMED Clinical Terms",
"domain_id": "Condition",
"concept_class_id": "Clinical Finding",
"standard_concept": "S",
"level": 3,
"min_levels_of_separation": 3,
"max_levels_of_separation": 3,
"relationship_id": "Is a",
"relationship_name": "Is a",
"hierarchy_level": 3,
"valid_start_date": "1970-01-01",
"valid_end_date": "2099-12-31",
"invalid_reason": null
}
],
"hierarchy_summary": {
"total_ancestors": 3,
"max_hierarchy_depth": 3,
"unique_vocabularies": ["SNOMED"],
"relationship_types_used": ["Is a"],
"truncated": false,
"result_limit": 5000
}
},
"meta": {
"pagination": {
"page": 1,
"page_size": 100,
"total_items": 3,
"total_pages": 1,
"has_next": false,
"has_previous": false
},
"request_id": "req_ancestors_201826_20250104_103100",
"timestamp": "2025-01-04T10:31:00Z",
"vocab_release": "2025.1"
}
}
Get Concept Ancestors
Retrieve all ancestor OMOP concepts for a given concept - hierarchical context, classification paths, and parent terms for concept set expansion.
curl -X GET "https://api.omophub.com/v1/concepts/201826/ancestors?include_paths=true&include_distance=true&max_levels=5" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json"
import { OMOPHub } from '@omophub/omophub-node';
const client = new OMOPHub();
const { data: ancestorData } = await client.hierarchy.ancestors(201826, {
includePaths: true,
includeDistance: true,
maxLevels: 5,
});
console.log(
`Found ${ancestorData?.hierarchy_summary.total_ancestors} ancestors`
);
console.log('First ancestor:', ancestorData?.ancestors[0]?.concept_name);
import requests
concept_id = 201826 # Type 2 diabetes mellitus
url = f"https://api.omophub.com/v1/concepts/{concept_id}/ancestors"
params = {
"include_paths": True,
"include_distance": True,
"max_levels": 5
}
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
}
response = requests.get(url, params=params, headers=headers)
ancestor_data = response.json()
print(f"Concept: {ancestor_data['data']['concept_name']}")
print(f"Total ancestors: {ancestor_data['data']['hierarchy_summary']['total_ancestors']}")
for ancestor in ancestor_data['data']['ancestors'][:5]:
level = ancestor.get('level', 'Unknown')
print(f"Level {level}: {ancestor['concept_name']} ({ancestor['concept_id']})")
{
"success": true,
"data": {
"concept_id": 201826,
"concept_name": "Type 2 diabetes mellitus",
"vocabulary_id": "SNOMED",
"ancestors": [
{
"concept_id": 73211009,
"concept_name": "Diabetes mellitus",
"concept_code": "73211009",
"vocabulary_id": "SNOMED",
"vocabulary_name": "SNOMED Clinical Terms",
"domain_id": "Condition",
"concept_class_id": "Clinical Finding",
"standard_concept": "S",
"level": 1,
"min_levels_of_separation": 1,
"max_levels_of_separation": 1,
"relationship_id": "Is a",
"relationship_name": "Is a",
"hierarchy_level": 1,
"valid_start_date": "1970-01-01",
"valid_end_date": "2099-12-31",
"invalid_reason": null
},
{
"concept_id": 362969004,
"concept_name": "Disorder of endocrine system",
"concept_code": "362969004",
"vocabulary_id": "SNOMED",
"vocabulary_name": "SNOMED Clinical Terms",
"domain_id": "Condition",
"concept_class_id": "Clinical Finding",
"standard_concept": "S",
"level": 2,
"min_levels_of_separation": 2,
"max_levels_of_separation": 2,
"relationship_id": "Is a",
"relationship_name": "Is a",
"hierarchy_level": 2,
"valid_start_date": "2002-01-31",
"valid_end_date": "2099-12-31",
"invalid_reason": null
},
{
"concept_id": 64572001,
"concept_name": "Disease",
"concept_code": "64572001",
"vocabulary_id": "SNOMED",
"vocabulary_name": "SNOMED Clinical Terms",
"domain_id": "Condition",
"concept_class_id": "Clinical Finding",
"standard_concept": "S",
"level": 3,
"min_levels_of_separation": 3,
"max_levels_of_separation": 3,
"relationship_id": "Is a",
"relationship_name": "Is a",
"hierarchy_level": 3,
"valid_start_date": "1970-01-01",
"valid_end_date": "2099-12-31",
"invalid_reason": null
}
],
"hierarchy_summary": {
"total_ancestors": 3,
"max_hierarchy_depth": 3,
"unique_vocabularies": ["SNOMED"],
"relationship_types_used": ["Is a"],
"truncated": false,
"result_limit": 5000
}
},
"meta": {
"pagination": {
"page": 1,
"page_size": 100,
"total_items": 3,
"total_pages": 1,
"has_next": false,
"has_previous": false
},
"request_id": "req_ancestors_201826_20250104_103100",
"timestamp": "2025-01-04T10:31:00Z",
"vocab_release": "2025.1"
}
}
This endpoint returns the complete ancestor hierarchy for a specific concept, including parent concepts, grandparents, and all higher-level classifications up to the root of the vocabulary hierarchy.
Path Parameters
integer
required
The unique identifier of the concept to retrieve ancestors for
Example:
Example:
201826 (Type 2 diabetes mellitus)Query Parameters
string
Filter ancestors to specific vocabularies (comma-separated)
Example:
Example:
SNOMED,ICD10CMstring
Filter ancestors to specific domains (comma-separated)
Example:
Example:
Condition,Observationinteger
default:"10"
Maximum number of hierarchy levels to traverse
Range:
Range:
1-20This endpoint always traverses the
Is a hierarchy. It reads OMOP’s
precomputed concept_ancestor closure, which stores only transitive Is a
ancestry - it has no relationship column to filter on. Every ancestor is
therefore returned with relationship_id: "Is a".A relationship_types parameter is accepted for backwards compatibility but has
no effect here: passing Part of, or even a nonexistent relationship, returns
the same Is a ancestors. To traverse other relationship types, use
GET /v1/concepts/{concept_id}/relationships
or POST /v1/concepts/relationships/traverse,
which query concept_relationship directly.boolean
default:"false"
Include
hierarchy_level field for each ancestor (distance from source
concept)boolean
default:"false"
Include
path_length field for each ancestorboolean
default:"false"
Include deprecated/invalid concepts in ancestry (by default they are excluded)
integer
default:"1"
Page number for pagination (1-based)
integer
default:"5000"
Maximum size of the ancestor set to retrieve before pagination is applied.
Range:
Defaults to the maximum, so paging through the response returns every ancestor that matches this request - those within
Range:
1-5000Defaults to the maximum, so paging through the response returns every ancestor that matches this request - those within
max_levels and any
vocabulary_ids / domain_ids filters you supplied. (relationship_types is
not applied - see above.) It is not necessarily the concept’s entire ancestry:
max_levels defaults to 10, so more distant ancestors are excluded, and
truncated does not flag that (it reports the row cap only). Pass
max_levels=20 if you need the full ancestry.Results are ordered by ascending min_levels_of_separation. When
max_results truncates the set, the nearest ancestors - direct parents before
grandparents and roots - are preserved. Concepts at the same separation have
no semantic precedence over one another.integer
default:"100"
Number of ancestor concepts to return per page. Values above
200 are clamped
to 200.string
Specific vocabulary release version to query
Example:
Example:
2025.1Response
boolean
Whether hierarchy retrieval completed.
object
Source concept and ancestor list.
integer
The concept ID for which ancestors were retrieved
string
Standard name of the source concept
string
Vocabulary containing the source concept
array
Array of ancestor concepts in hierarchical order
Show Ancestor Concept Object
Show Ancestor Concept Object
integer
Unique identifier for the ancestor concept
string
Standard name of the ancestor concept
string
Original code from the vocabulary
string
Vocabulary containing this ancestor concept
string
Human-readable vocabulary name
string
Domain classification of the ancestor
string
Concept class identifier
string
Standard concept designation (‘S’, ‘C’, or null)
integer
Distance from source concept (always present)
integer
Minimum levels of separation from source concept
integer
Maximum levels of separation from source concept
string
Relationship type ID (e.g., “Is a”)
string
Relationship type name (e.g., “Is a”)
integer
Distance from source concept (only when include_distance=true, same as level)
integer
Path length from source concept (only when include_paths=true, same as level)
string
Date when concept became valid (ISO format)
string
Date when concept became invalid (ISO format)
string
Reason for concept invalidation if applicable
object
Summary statistics about the ancestor hierarchy
Show Hierarchy Summary Object
Show Hierarchy Summary Object
integer
Total number of ancestor concepts found
integer
Maximum depth of the hierarchy tree
array
List of vocabulary IDs represented in ancestors
array
List of relationship type IDs found in hierarchy
boolean
Whether the matching ancestor set exceeded
result_limit and was cut
off before pagination. This reports only the row cap; max_levels and
vocabulary/domain filters can also narrow the result without setting it.integer
The
max_results cap applied before pagination.object
Response metadata and pagination information
Show Metadata Object
Show Metadata Object
object
string
Request correlation identifier.
string
ISO 8601 response timestamp.
string
Vocabulary release used for the query.
curl -X GET "https://api.omophub.com/v1/concepts/201826/ancestors?include_paths=true&include_distance=true&max_levels=5" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json"
import { OMOPHub } from '@omophub/omophub-node';
const client = new OMOPHub();
const { data: ancestorData } = await client.hierarchy.ancestors(201826, {
includePaths: true,
includeDistance: true,
maxLevels: 5,
});
console.log(
`Found ${ancestorData?.hierarchy_summary.total_ancestors} ancestors`
);
console.log('First ancestor:', ancestorData?.ancestors[0]?.concept_name);
import requests
concept_id = 201826 # Type 2 diabetes mellitus
url = f"https://api.omophub.com/v1/concepts/{concept_id}/ancestors"
params = {
"include_paths": True,
"include_distance": True,
"max_levels": 5
}
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
}
response = requests.get(url, params=params, headers=headers)
ancestor_data = response.json()
print(f"Concept: {ancestor_data['data']['concept_name']}")
print(f"Total ancestors: {ancestor_data['data']['hierarchy_summary']['total_ancestors']}")
for ancestor in ancestor_data['data']['ancestors'][:5]:
level = ancestor.get('level', 'Unknown')
print(f"Level {level}: {ancestor['concept_name']} ({ancestor['concept_id']})")
{
"success": true,
"data": {
"concept_id": 201826,
"concept_name": "Type 2 diabetes mellitus",
"vocabulary_id": "SNOMED",
"ancestors": [
{
"concept_id": 73211009,
"concept_name": "Diabetes mellitus",
"concept_code": "73211009",
"vocabulary_id": "SNOMED",
"vocabulary_name": "SNOMED Clinical Terms",
"domain_id": "Condition",
"concept_class_id": "Clinical Finding",
"standard_concept": "S",
"level": 1,
"min_levels_of_separation": 1,
"max_levels_of_separation": 1,
"relationship_id": "Is a",
"relationship_name": "Is a",
"hierarchy_level": 1,
"valid_start_date": "1970-01-01",
"valid_end_date": "2099-12-31",
"invalid_reason": null
},
{
"concept_id": 362969004,
"concept_name": "Disorder of endocrine system",
"concept_code": "362969004",
"vocabulary_id": "SNOMED",
"vocabulary_name": "SNOMED Clinical Terms",
"domain_id": "Condition",
"concept_class_id": "Clinical Finding",
"standard_concept": "S",
"level": 2,
"min_levels_of_separation": 2,
"max_levels_of_separation": 2,
"relationship_id": "Is a",
"relationship_name": "Is a",
"hierarchy_level": 2,
"valid_start_date": "2002-01-31",
"valid_end_date": "2099-12-31",
"invalid_reason": null
},
{
"concept_id": 64572001,
"concept_name": "Disease",
"concept_code": "64572001",
"vocabulary_id": "SNOMED",
"vocabulary_name": "SNOMED Clinical Terms",
"domain_id": "Condition",
"concept_class_id": "Clinical Finding",
"standard_concept": "S",
"level": 3,
"min_levels_of_separation": 3,
"max_levels_of_separation": 3,
"relationship_id": "Is a",
"relationship_name": "Is a",
"hierarchy_level": 3,
"valid_start_date": "1970-01-01",
"valid_end_date": "2099-12-31",
"invalid_reason": null
}
],
"hierarchy_summary": {
"total_ancestors": 3,
"max_hierarchy_depth": 3,
"unique_vocabularies": ["SNOMED"],
"relationship_types_used": ["Is a"],
"truncated": false,
"result_limit": 5000
}
},
"meta": {
"pagination": {
"page": 1,
"page_size": 100,
"total_items": 3,
"total_pages": 1,
"has_next": false,
"has_previous": false
},
"request_id": "req_ancestors_201826_20250104_103100",
"timestamp": "2025-01-04T10:31:00Z",
"vocab_release": "2025.1"
}
}
Usage Examples
Basic Ancestor Retrieval
Get all ancestors for a specific concept:TypeScript
const { data: ancestors } = await client.hierarchy.ancestors(201826);
Limited Hierarchy Depth
Retrieve ancestors up to a specific number of levels:TypeScript
const { data: nearAncestors } = await client.hierarchy.ancestors(201826, {
maxLevels: 3,
});
Classification Path Analysis
Get complete classification paths from concept to root:TypeScript
const { data: pathData } = await client.hierarchy.ancestors(201826, {
includePaths: true,
includeDistance: true,
});
Cross-Vocabulary Hierarchy
Analyze ancestors within specific vocabulary:TypeScript
const { data: snomedAncestors } = await client.hierarchy.ancestors(201826, {
vocabularyIds: ['SNOMED'],
});
Multiple Relationship Types
Follow different types of hierarchical relationships:TypeScript
const { data: extendedHierarchy } = await client.hierarchy.ancestors(201826, {
relationshipTypes: ['Is a', 'Part of'],
});
Related Endpoints
- Get Concept Descendants - Retrieve child concepts
- Get Concept Hierarchy - Complete hierarchy view
- Get Concept Relationships - All concept relationships
- Get Concept Details - Complete concept information
Notes
- Hierarchy traversal follows “Is a” relationships by default, but can be customized
- Some concepts may have multiple classification paths to different root concepts
- Cross-vocabulary concepts may have ancestors in different vocabularies
- Standard concepts are prioritized in hierarchy traversal unless explicitly disabled
- Deprecated concepts are excluded from ancestry unless specifically requested
- Maximum hierarchy depth is typically 6-8 levels for most medical vocabularies
Was this page helpful?