curl -X GET "https://api.omophub.com/v1/concepts/73211009/hierarchy?max_levels=3" \
-H "Authorization: Bearer YOUR_API_KEY"
curl -X GET "https://api.omophub.com/v1/concepts/73211009/hierarchy?format=graph&max_levels=3" \
-H "Authorization: Bearer YOUR_API_KEY"
import requests
concept_id = 73211009 # Diabetes mellitus
url = f"https://api.omophub.com/v1/concepts/{concept_id}/hierarchy"
params = {
"max_levels": 3,
"vocabulary_ids": "SNOMED"
}
headers = {
"Authorization": "Bearer YOUR_API_KEY"
}
response = requests.get(url, params=params, headers=headers)
hierarchy_data = response.json()
print(f"Concept ID: {hierarchy_data['data']['concept_id']}")
print(f"Total ancestors: {hierarchy_data['data']['total_ancestors']}")
print(f"Total descendants: {hierarchy_data['data']['total_descendants']}")
import requests
concept_id = 73211009
url = f"https://api.omophub.com/v1/concepts/{concept_id}/hierarchy"
params = {
"format": "graph",
"max_levels": 3
}
headers = {"Authorization": "Bearer YOUR_API_KEY"}
response = requests.get(url, params=params, headers=headers)
graph_data = response.json()
# Use for D3.js or other visualization libraries
nodes = graph_data['data']['nodes']
edges = graph_data['data']['edges']
print(f"Nodes: {len(nodes)}, Edges: {len(edges)}")
import { OMOPHub } from '@omophub/omophub-node';
const client = new OMOPHub();
const { data: hierarchyData } = await client.hierarchy.get(73211009, { maxLevels: 3 });
console.log(`Ancestors: ${hierarchyData?.total_ancestors}`);
console.log(`Descendants: ${hierarchyData?.total_descendants}`);
const { data: graphData } = await client.hierarchy.get(73211009, {
format: 'graph',
maxLevels: 3,
});
// Use with D3.js force-directed graph
const { nodes, edges } = graphData ?? { nodes: [], edges: [] };
{
"success": true,
"data": {
"concept_id": 73211009,
"ancestors": [
{
"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": 1,
"min_levels_of_separation": 1,
"max_levels_of_separation": 1,
"relationship_id": "Is a",
"relationship_name": "Is a"
},
{
"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": 2,
"min_levels_of_separation": 2,
"max_levels_of_separation": 2,
"relationship_id": "Is a",
"relationship_name": "Is a"
}
],
"descendants": [
{
"concept_id": 44054006,
"concept_name": "Type 2 diabetes mellitus",
"concept_code": "44054006",
"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": "Subsumes",
"relationship_name": "Subsumes"
},
{
"concept_id": 46635009,
"concept_name": "Type 1 diabetes mellitus",
"concept_code": "46635009",
"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": "Subsumes",
"relationship_name": "Subsumes"
}
],
"level": 3,
"max_level": 5,
"total_ancestors": 2,
"total_descendants": 2
},
"meta": {
"request_id": "req_hierarchy_123",
"timestamp": "2024-12-22T10:30:00Z",
"vocab_release": "2025.2"
}
}
{
"success": true,
"data": {
"concept_id": 73211009,
"nodes": [
{
"id": 73211009,
"name": "Diabetes mellitus",
"level": 0,
"vocabulary_id": "SNOMED",
"domain_id": "Condition",
"concept_class_id": "Clinical Finding",
"standard_concept": "S"
},
{
"id": 362969004,
"name": "Disorder of endocrine system",
"level": -1,
"vocabulary_id": "SNOMED",
"domain_id": "Condition",
"concept_class_id": "Clinical Finding",
"standard_concept": "S"
},
{
"id": 44054006,
"name": "Type 2 diabetes mellitus",
"level": 1,
"vocabulary_id": "SNOMED",
"domain_id": "Condition",
"concept_class_id": "Clinical Finding",
"standard_concept": "S"
},
{
"id": 46635009,
"name": "Type 1 diabetes mellitus",
"level": 1,
"vocabulary_id": "SNOMED",
"domain_id": "Condition",
"concept_class_id": "Clinical Finding",
"standard_concept": "S"
}
],
"edges": [
{
"from": 73211009,
"to": 362969004,
"relationship_id": "Is a"
},
{
"from": 73211009,
"to": 44054006,
"relationship_id": "Subsumes"
},
{
"from": 73211009,
"to": 46635009,
"relationship_id": "Subsumes"
}
]
},
"meta": {
"request_id": "req_hierarchy_456",
"timestamp": "2024-12-22T10:30:00Z",
"vocab_release": "2025.2"
}
}
Get Concept Hierarchy
Retrieve the complete OMOP hierarchy for a concept - ancestors and descendants in one unified view for phenotype development and concept sets.
curl -X GET "https://api.omophub.com/v1/concepts/73211009/hierarchy?max_levels=3" \
-H "Authorization: Bearer YOUR_API_KEY"
curl -X GET "https://api.omophub.com/v1/concepts/73211009/hierarchy?format=graph&max_levels=3" \
-H "Authorization: Bearer YOUR_API_KEY"
import requests
concept_id = 73211009 # Diabetes mellitus
url = f"https://api.omophub.com/v1/concepts/{concept_id}/hierarchy"
params = {
"max_levels": 3,
"vocabulary_ids": "SNOMED"
}
headers = {
"Authorization": "Bearer YOUR_API_KEY"
}
response = requests.get(url, params=params, headers=headers)
hierarchy_data = response.json()
print(f"Concept ID: {hierarchy_data['data']['concept_id']}")
print(f"Total ancestors: {hierarchy_data['data']['total_ancestors']}")
print(f"Total descendants: {hierarchy_data['data']['total_descendants']}")
import requests
concept_id = 73211009
url = f"https://api.omophub.com/v1/concepts/{concept_id}/hierarchy"
params = {
"format": "graph",
"max_levels": 3
}
headers = {"Authorization": "Bearer YOUR_API_KEY"}
response = requests.get(url, params=params, headers=headers)
graph_data = response.json()
# Use for D3.js or other visualization libraries
nodes = graph_data['data']['nodes']
edges = graph_data['data']['edges']
print(f"Nodes: {len(nodes)}, Edges: {len(edges)}")
import { OMOPHub } from '@omophub/omophub-node';
const client = new OMOPHub();
const { data: hierarchyData } = await client.hierarchy.get(73211009, { maxLevels: 3 });
console.log(`Ancestors: ${hierarchyData?.total_ancestors}`);
console.log(`Descendants: ${hierarchyData?.total_descendants}`);
const { data: graphData } = await client.hierarchy.get(73211009, {
format: 'graph',
maxLevels: 3,
});
// Use with D3.js force-directed graph
const { nodes, edges } = graphData ?? { nodes: [], edges: [] };
{
"success": true,
"data": {
"concept_id": 73211009,
"ancestors": [
{
"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": 1,
"min_levels_of_separation": 1,
"max_levels_of_separation": 1,
"relationship_id": "Is a",
"relationship_name": "Is a"
},
{
"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": 2,
"min_levels_of_separation": 2,
"max_levels_of_separation": 2,
"relationship_id": "Is a",
"relationship_name": "Is a"
}
],
"descendants": [
{
"concept_id": 44054006,
"concept_name": "Type 2 diabetes mellitus",
"concept_code": "44054006",
"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": "Subsumes",
"relationship_name": "Subsumes"
},
{
"concept_id": 46635009,
"concept_name": "Type 1 diabetes mellitus",
"concept_code": "46635009",
"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": "Subsumes",
"relationship_name": "Subsumes"
}
],
"level": 3,
"max_level": 5,
"total_ancestors": 2,
"total_descendants": 2
},
"meta": {
"request_id": "req_hierarchy_123",
"timestamp": "2024-12-22T10:30:00Z",
"vocab_release": "2025.2"
}
}
{
"success": true,
"data": {
"concept_id": 73211009,
"nodes": [
{
"id": 73211009,
"name": "Diabetes mellitus",
"level": 0,
"vocabulary_id": "SNOMED",
"domain_id": "Condition",
"concept_class_id": "Clinical Finding",
"standard_concept": "S"
},
{
"id": 362969004,
"name": "Disorder of endocrine system",
"level": -1,
"vocabulary_id": "SNOMED",
"domain_id": "Condition",
"concept_class_id": "Clinical Finding",
"standard_concept": "S"
},
{
"id": 44054006,
"name": "Type 2 diabetes mellitus",
"level": 1,
"vocabulary_id": "SNOMED",
"domain_id": "Condition",
"concept_class_id": "Clinical Finding",
"standard_concept": "S"
},
{
"id": 46635009,
"name": "Type 1 diabetes mellitus",
"level": 1,
"vocabulary_id": "SNOMED",
"domain_id": "Condition",
"concept_class_id": "Clinical Finding",
"standard_concept": "S"
}
],
"edges": [
{
"from": 73211009,
"to": 362969004,
"relationship_id": "Is a"
},
{
"from": 73211009,
"to": 44054006,
"relationship_id": "Subsumes"
},
{
"from": 73211009,
"to": 46635009,
"relationship_id": "Subsumes"
}
]
},
"meta": {
"request_id": "req_hierarchy_456",
"timestamp": "2024-12-22T10:30:00Z",
"vocab_release": "2025.2"
}
}
This endpoint provides a comprehensive hierarchical view of a concept, showing its position within the medical vocabulary structure by including both ancestor (parent) and descendant (child) relationships in a single response.
Path Parameters
integer
required
The unique identifier of the concept to retrieve hierarchy for
Example:
Example:
73211009 (Diabetes mellitus)Query Parameters
string
default:"flat"
Response format for hierarchy data
Options:
Options:
flat, graphflat: Returns ancestors and descendants as separate arrays (default)graph: Returns nodes and edges for visualization (similar to OHDSI Athena)
string
Filter hierarchy to specific vocabularies (comma-separated)
Example:
Example:
SNOMED,ICD10CMstring
Filter hierarchy to specific domains (comma-separated)
Example:
Example:
Condition,Druginteger
default:"10"
Maximum number of hierarchy levels to traverse in both directions
Range:
Range:
1-20integer
default:"500"
Maximum number of results to return per direction (ancestors/descendants) for performance optimization
Range:
Recommended: Use 100-500 for interactive queries, up to 1000 for bulk analysis
Range:
1-5000Recommended: Use 100-500 for interactive queries, up to 1000 for bulk analysis
This endpoint always traverses the
Is a / Subsumes hierarchy. It reads
OMOP’s precomputed concept_ancestor closure, which has no relationship column to
filter on. 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 result. To traverse other relationship types, use
GET /v1/concepts/{concept_id}/relationships
or POST /v1/concepts/relationships/traverse.boolean
default:"false"
Include deprecated/invalid concepts in hierarchy (by default they are excluded)
string
Specific vocabulary release version to query
Example:
Example:
2025.1Response
Flat Format (default)
integer
The concept ID for which hierarchy was retrieved
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
string
Human-readable vocabulary name
string
Domain classification
string
Concept class identifier
string
Standard concept designation (‘S’, ‘C’, or null)
integer
Distance from source concept
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
array
Array of descendant concepts in hierarchical order
Show Descendant Concept Object
Show Descendant Concept Object
integer
Unique identifier for the descendant concept
string
Standard name of the descendant concept
string
Original code from the vocabulary
string
Vocabulary containing this descendant
string
Human-readable vocabulary name
string
Domain classification
string
Concept class identifier
string
Standard concept designation (‘S’, ‘C’, or null)
integer
Distance from source concept
integer
Minimum levels of separation from source concept
integer
Maximum levels of separation from source concept
string
Relationship type ID (e.g., “Subsumes”)
string
Relationship type name
integer
Current concept’s level in the hierarchy
integer
Maximum hierarchy depth
integer
Total number of ancestor concepts
integer
Total number of descendant concepts
Graph Format (format=graph)
integer
The concept ID for which hierarchy was retrieved
array
Array of concept nodes for visualization
Show Node Object
Show Node Object
integer
Unique identifier for the concept
string
Concept name
integer
Hierarchical level (0 for central concept, negative for ancestors, positive for descendants)
string
Vocabulary containing this concept
string
Domain classification
string
Concept class identifier
string
Standard concept designation (‘S’, ‘C’, or null)
array
curl -X GET "https://api.omophub.com/v1/concepts/73211009/hierarchy?max_levels=3" \
-H "Authorization: Bearer YOUR_API_KEY"
curl -X GET "https://api.omophub.com/v1/concepts/73211009/hierarchy?format=graph&max_levels=3" \
-H "Authorization: Bearer YOUR_API_KEY"
import requests
concept_id = 73211009 # Diabetes mellitus
url = f"https://api.omophub.com/v1/concepts/{concept_id}/hierarchy"
params = {
"max_levels": 3,
"vocabulary_ids": "SNOMED"
}
headers = {
"Authorization": "Bearer YOUR_API_KEY"
}
response = requests.get(url, params=params, headers=headers)
hierarchy_data = response.json()
print(f"Concept ID: {hierarchy_data['data']['concept_id']}")
print(f"Total ancestors: {hierarchy_data['data']['total_ancestors']}")
print(f"Total descendants: {hierarchy_data['data']['total_descendants']}")
import requests
concept_id = 73211009
url = f"https://api.omophub.com/v1/concepts/{concept_id}/hierarchy"
params = {
"format": "graph",
"max_levels": 3
}
headers = {"Authorization": "Bearer YOUR_API_KEY"}
response = requests.get(url, params=params, headers=headers)
graph_data = response.json()
# Use for D3.js or other visualization libraries
nodes = graph_data['data']['nodes']
edges = graph_data['data']['edges']
print(f"Nodes: {len(nodes)}, Edges: {len(edges)}")
import { OMOPHub } from '@omophub/omophub-node';
const client = new OMOPHub();
const { data: hierarchyData } = await client.hierarchy.get(73211009, { maxLevels: 3 });
console.log(`Ancestors: ${hierarchyData?.total_ancestors}`);
console.log(`Descendants: ${hierarchyData?.total_descendants}`);
const { data: graphData } = await client.hierarchy.get(73211009, {
format: 'graph',
maxLevels: 3,
});
// Use with D3.js force-directed graph
const { nodes, edges } = graphData ?? { nodes: [], edges: [] };
{
"success": true,
"data": {
"concept_id": 73211009,
"ancestors": [
{
"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": 1,
"min_levels_of_separation": 1,
"max_levels_of_separation": 1,
"relationship_id": "Is a",
"relationship_name": "Is a"
},
{
"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": 2,
"min_levels_of_separation": 2,
"max_levels_of_separation": 2,
"relationship_id": "Is a",
"relationship_name": "Is a"
}
],
"descendants": [
{
"concept_id": 44054006,
"concept_name": "Type 2 diabetes mellitus",
"concept_code": "44054006",
"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": "Subsumes",
"relationship_name": "Subsumes"
},
{
"concept_id": 46635009,
"concept_name": "Type 1 diabetes mellitus",
"concept_code": "46635009",
"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": "Subsumes",
"relationship_name": "Subsumes"
}
],
"level": 3,
"max_level": 5,
"total_ancestors": 2,
"total_descendants": 2
},
"meta": {
"request_id": "req_hierarchy_123",
"timestamp": "2024-12-22T10:30:00Z",
"vocab_release": "2025.2"
}
}
{
"success": true,
"data": {
"concept_id": 73211009,
"nodes": [
{
"id": 73211009,
"name": "Diabetes mellitus",
"level": 0,
"vocabulary_id": "SNOMED",
"domain_id": "Condition",
"concept_class_id": "Clinical Finding",
"standard_concept": "S"
},
{
"id": 362969004,
"name": "Disorder of endocrine system",
"level": -1,
"vocabulary_id": "SNOMED",
"domain_id": "Condition",
"concept_class_id": "Clinical Finding",
"standard_concept": "S"
},
{
"id": 44054006,
"name": "Type 2 diabetes mellitus",
"level": 1,
"vocabulary_id": "SNOMED",
"domain_id": "Condition",
"concept_class_id": "Clinical Finding",
"standard_concept": "S"
},
{
"id": 46635009,
"name": "Type 1 diabetes mellitus",
"level": 1,
"vocabulary_id": "SNOMED",
"domain_id": "Condition",
"concept_class_id": "Clinical Finding",
"standard_concept": "S"
}
],
"edges": [
{
"from": 73211009,
"to": 362969004,
"relationship_id": "Is a"
},
{
"from": 73211009,
"to": 44054006,
"relationship_id": "Subsumes"
},
{
"from": 73211009,
"to": 46635009,
"relationship_id": "Subsumes"
}
]
},
"meta": {
"request_id": "req_hierarchy_456",
"timestamp": "2024-12-22T10:30:00Z",
"vocab_release": "2025.2"
}
}
Usage Examples
Basic Hierarchy View
Get complete hierarchy context for a concept:TypeScript
const { data: hierarchy } = await client.hierarchy.get(73211009);
Limited Depth Hierarchy
Control the depth of ancestor and descendant traversal:TypeScript
const { data: limitedHierarchy } = await client.hierarchy.get(73211009, {
maxLevels: 2,
maxResults: 100,
});
Graph Format for Visualization
Get hierarchy in graph structure for D3.js or similar visualization libraries:TypeScript
const { data: graphData } = await client.hierarchy.get(73211009, {
format: 'graph',
maxLevels: 3,
});
Filtered Hierarchy
Filter to specific vocabularies:TypeScript
const { data: filteredHierarchy } = await client.hierarchy.get(73211009, {
vocabularyIds: ['SNOMED'],
domainIds: ['Condition'],
});
Related Endpoints
- Get Concept Ancestors - Detailed ancestor information with pagination
- Get Concept Descendants - Detailed descendant information with pagination
- Get Concept Relationships - All concept relationships
- Search Concepts - Search within hierarchies
Notes
- The hierarchy endpoint combines ancestors and descendants in a single request for convenience
- Use the
graphformat when building visualizations (compatible with D3.js, Cytoscape, etc.) - The
flatformat is better for data processing and analysis - In graph format, level 0 is the central concept, negative levels are ancestors, positive are descendants
- Large hierarchies may be limited by
max_resultsto ensure performance - Cross-vocabulary concepts may show relationships spanning multiple vocabularies
Was this page helpful?
⌘I