Skip to main content
curl -X GET "https://api.omophub.com/v1/concepts/73211009/hierarchy?max_levels=3" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "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"
  }
}
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

​
concept_id
integer
required
The unique identifier of the concept to retrieve hierarchy for
Example: 73211009 (Diabetes mellitus)

​
Query Parameters

​
format
string
default:"flat"
Response format for hierarchy data
Options: flat, graph
  • flat: Returns ancestors and descendants as separate arrays (default)
  • graph: Returns nodes and edges for visualization (similar to OHDSI Athena)
​
vocabulary_ids
string
Filter hierarchy to specific vocabularies (comma-separated)
Example: SNOMED,ICD10CM
​
domain_ids
string
Filter hierarchy to specific domains (comma-separated)
Example: Condition,Drug
​
max_levels
integer
default:"10"
Maximum number of hierarchy levels to traverse in both directions
Range: 1-20
​
max_results
integer
default:"500"
Maximum number of results to return per direction (ancestors/descendants) for performance optimization
Range: 1-5000
Recommended: Use 100-500 for interactive queries, up to 1000 for bulk analysis
​
relationship_types
string
default:"Is a"
Comma-separated list of relationship types to follow for hierarchy traversal
Example: Is a,Part of
​
include_invalid
boolean
default:"true"
Include deprecated/invalid concepts in hierarchy
​
vocab_release
string
Specific vocabulary release version to query
Example: 2025.1

​
Response

​
Flat Format (default)

​
concept_id
integer
The concept ID for which hierarchy was retrieved
​
ancestors
array
Array of ancestor concepts in hierarchical order
​
descendants
array
Array of descendant concepts in hierarchical order
​
level
integer
Current concept’s level in the hierarchy
​
max_level
integer
Maximum hierarchy depth
​
total_ancestors
integer
Total number of ancestor concepts
​
total_descendants
integer
Total number of descendant concepts

​
Graph Format (format=graph)

​
concept_id
integer
The concept ID for which hierarchy was retrieved
​
nodes
array
Array of concept nodes for visualization
​
edges
array
Array of relationship edges between concepts
curl -X GET "https://api.omophub.com/v1/concepts/73211009/hierarchy?max_levels=3" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "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"
  }
}

​
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'],
});

​
Notes

  • The hierarchy endpoint combines ancestors and descendants in a single request for convenience
  • Use the graph format when building visualizations (compatible with D3.js, Cytoscape, etc.)
  • The flat format 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_results to ensure performance
  • Cross-vocabulary concepts may show relationships spanning multiple vocabularies