Skip to main content
GET
/
v1
/
concepts
/
{concept_id}
/
hierarchy
curl -X GET "https://api.omophub.com/v1/concepts/73211009/hierarchy?max_ancestor_levels=3&max_descendant_levels=2&include_statistics=true&format=tree" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "concept": {
      "concept_id": 73211009,
      "concept_name": "Diabetes mellitus",
      "concept_code": "73211009",
      "vocabulary_id": "SNOMED",
      "domain_id": "Condition",
      "concept_class_id": "Clinical Finding",
      "standard_concept": "S"
    },
  "ancestors": [
    {
      "concept_id": 362969004,
      "concept_name": "Disorder of endocrine system",
      "hierarchy_level": -1,
      "relationship_type": "Is a",
      "vocabulary_id": "SNOMED",
      "domain_id": "Condition",
      "concept_class_id": "Clinical Finding"
    },
    {
      "concept_id": 64572001,
      "concept_name": "Disease",
      "hierarchy_level": -2,
      "relationship_type": "Is a",
      "vocabulary_id": "SNOMED",
      "domain_id": "Condition",
      "concept_class_id": "Clinical Finding"
    },
    {
      "concept_id": 404684003,
      "concept_name": "Clinical finding",
      "hierarchy_level": -3,
      "relationship_type": "Is a",
      "vocabulary_id": "SNOMED",
      "domain_id": "Condition",
      "concept_class_id": "Clinical Finding"
    }
  ],
  "descendants": [
    {
      "concept_id": 44054006,
      "concept_name": "Type 2 diabetes mellitus",
      "hierarchy_level": 1,
      "relationship_type": "Is a",
      "parent_concept_id": 73211009,
      "vocabulary_id": "SNOMED",
      "domain_id": "Condition",
      "concept_class_id": "Clinical Finding"
    },
    {
      "concept_id": 46635009,
      "concept_name": "Type 1 diabetes mellitus",
      "hierarchy_level": 1,
      "relationship_type": "Is a",
      "parent_concept_id": 73211009,
      "vocabulary_id": "SNOMED",
      "domain_id": "Condition",
      "concept_class_id": "Clinical Finding"
    },
    {
      "concept_id": 190411009,
      "concept_name": "Type 2 diabetes mellitus with renal complications",
      "hierarchy_level": 2,
      "relationship_type": "Is a",
      "parent_concept_id": 44054006,
      "vocabulary_id": "SNOMED",
      "domain_id": "Condition",
      "concept_class_id": "Clinical Finding"
    }
  ],
  "tree_structure": {
    "root_concepts": [404684003],
    "branches": {
      "404684003": {
        "children": [64572001]
      },
      "64572001": {
        "children": [362969004]
      },
      "362969004": {
        "children": [73211009]
      },
      "73211009": {
        "children": [44054006, 46635009]
      },
      "44054006": {
        "children": [190411009]
      },
      "46635009": {
        "children": []
      },
      "190411009": {
        "children": []
      }
    },
    "leaf_concepts": [190411009, 46635009]
  },
  "hierarchy_statistics": {
    "total_ancestors": 3,
    "total_descendants": 3,
    "max_ancestor_depth": 3,
    "max_descendant_depth": 2,
    "branching_factor": 2.0,
    "hierarchy_breadth": 2,
    "domain_distribution": {
      "Condition": 7
    },
      "vocabulary_distribution": {
        "SNOMED": 7
      },
      "path_count": 1
    }
  },
  "meta": {
    "request_id": "req_hierarchy_73211009_20241222_103000",
    "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

​
vocabulary_id
string
Filter hierarchy to specific vocabulary
Example: SNOMED
​
max_ancestor_levels
integer
Maximum number of ancestor hierarchy levels to traverse (default: 5)
Range: 1-10
​
max_descendant_levels
integer
Maximum number of descendant hierarchy levels to traverse (default: 3)
Range: 1-10
​
max_levels
integer
Convenient shorthand to set both max_ancestor_levels and max_descendant_levels to the same value (default: 10)
Range: 1-20
Note: If max_levels is provided along with max_ancestor_levels or max_descendant_levels, the specific parameters take precedence
​
max_results
integer
Maximum number of results to return per query for performance optimization (applies to ancestors and descendants separately)
Default: 500
Range: 1-5000
Recommended: Use 100-500 for interactive queries, up to 1000 for bulk analysis
This parameter prevents query timeouts and ensures predictable response times. The default limit handles 95%+ of use cases while maintaining sub-second performance.
​
relationship_types
string
Comma-separated list of relationship types to follow for hierarchy traversal
Default: Is a
Example: Is a,Part of,Has part
​
include_distance
boolean
default:"true"
Include hierarchical distance (level) for each concept
​
include_paths
boolean
default:"false"
Include complete classification_paths for both ancestors and descendants when true
​
standard_only
boolean
default:"true"
Only return standard concepts in the hierarchy
​
include_deprecated
boolean
default:"false"
Include deprecated/invalid concepts in hierarchy
​
include_synonyms
boolean
default:"false"
Include synonym information for all concepts
​
include_statistics
boolean
default:"false"
Include detailed hierarchy statistics and analysis
​
format
string
default:"flat"
Response format for hierarchy data
Options: flat, tree, graph

​
Response

​
concept
object
The central concept for which hierarchy was retrieved
​
ancestors
array
Array of ancestor concepts in hierarchical order
​
descendants
array
Array of descendant concepts in hierarchical order
​
tree_structure
object
Hierarchical tree representation (when format=‘tree’)
​
graph_data
object
Graph representation with nodes and edges (when format=‘graph’)
​
hierarchy_statistics
object
Detailed hierarchy analysis (when include_statistics=true)
curl -X GET "https://api.omophub.com/v1/concepts/73211009/hierarchy?max_ancestor_levels=3&max_descendant_levels=2&include_statistics=true&format=tree" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "concept": {
      "concept_id": 73211009,
      "concept_name": "Diabetes mellitus",
      "concept_code": "73211009",
      "vocabulary_id": "SNOMED",
      "domain_id": "Condition",
      "concept_class_id": "Clinical Finding",
      "standard_concept": "S"
    },
  "ancestors": [
    {
      "concept_id": 362969004,
      "concept_name": "Disorder of endocrine system",
      "hierarchy_level": -1,
      "relationship_type": "Is a",
      "vocabulary_id": "SNOMED",
      "domain_id": "Condition",
      "concept_class_id": "Clinical Finding"
    },
    {
      "concept_id": 64572001,
      "concept_name": "Disease",
      "hierarchy_level": -2,
      "relationship_type": "Is a",
      "vocabulary_id": "SNOMED",
      "domain_id": "Condition",
      "concept_class_id": "Clinical Finding"
    },
    {
      "concept_id": 404684003,
      "concept_name": "Clinical finding",
      "hierarchy_level": -3,
      "relationship_type": "Is a",
      "vocabulary_id": "SNOMED",
      "domain_id": "Condition",
      "concept_class_id": "Clinical Finding"
    }
  ],
  "descendants": [
    {
      "concept_id": 44054006,
      "concept_name": "Type 2 diabetes mellitus",
      "hierarchy_level": 1,
      "relationship_type": "Is a",
      "parent_concept_id": 73211009,
      "vocabulary_id": "SNOMED",
      "domain_id": "Condition",
      "concept_class_id": "Clinical Finding"
    },
    {
      "concept_id": 46635009,
      "concept_name": "Type 1 diabetes mellitus",
      "hierarchy_level": 1,
      "relationship_type": "Is a",
      "parent_concept_id": 73211009,
      "vocabulary_id": "SNOMED",
      "domain_id": "Condition",
      "concept_class_id": "Clinical Finding"
    },
    {
      "concept_id": 190411009,
      "concept_name": "Type 2 diabetes mellitus with renal complications",
      "hierarchy_level": 2,
      "relationship_type": "Is a",
      "parent_concept_id": 44054006,
      "vocabulary_id": "SNOMED",
      "domain_id": "Condition",
      "concept_class_id": "Clinical Finding"
    }
  ],
  "tree_structure": {
    "root_concepts": [404684003],
    "branches": {
      "404684003": {
        "children": [64572001]
      },
      "64572001": {
        "children": [362969004]
      },
      "362969004": {
        "children": [73211009]
      },
      "73211009": {
        "children": [44054006, 46635009]
      },
      "44054006": {
        "children": [190411009]
      },
      "46635009": {
        "children": []
      },
      "190411009": {
        "children": []
      }
    },
    "leaf_concepts": [190411009, 46635009]
  },
  "hierarchy_statistics": {
    "total_ancestors": 3,
    "total_descendants": 3,
    "max_ancestor_depth": 3,
    "max_descendant_depth": 2,
    "branching_factor": 2.0,
    "hierarchy_breadth": 2,
    "domain_distribution": {
      "Condition": 7
    },
      "vocabulary_distribution": {
        "SNOMED": 7
      },
      "path_count": 1
    }
  },
  "meta": {
    "request_id": "req_hierarchy_73211009_20241222_103000",
    "timestamp": "2024-12-22T10:30:00Z",
    "vocab_release": "2025.2"
  }
}

​
Usage Examples

​
Basic Hierarchy View

Get complete hierarchy context for a concept: 
const hierarchy = await fetch('/v1/concepts/73211009/hierarchy');

​
Limited Depth Hierarchy

Control the depth of ancestor and descendant traversal: 
const limitedHierarchy = await fetch('/v1/concepts/73211009/hierarchy?max_ancestor_levels=2&max_descendant_levels=1&max_results=500');

​
Performance-Optimized Queries

Use max_results and max_levels to limit result size for better performance: 
// Quick response for interactive UI (100-500ms) - using max_levels shorthand
const quickHierarchy = await fetch('/v1/concepts/73211009/hierarchy?max_levels=2&max_results=100');

// Balanced performance (500ms-2s) - using max_levels shorthand
const balancedHierarchy = await fetch('/v1/concepts/73211009/hierarchy?max_levels=3&max_results=500');

// Comprehensive analysis (2s-10s) - using max_levels shorthand
const fullHierarchy = await fetch('/v1/concepts/73211009/hierarchy?max_levels=5&max_results=1000');

​
Tree Format for Visualization

Get hierarchy in tree structure for UI components: 
const treeData = await fetch('/v1/concepts/73211009/hierarchy?format=tree&include_statistics=true');

​
Graph Format for Network Visualization

Get hierarchy as graph data for network diagrams: 
const graphData = await fetch('/v1/concepts/73211009/hierarchy?format=graph&max_ancestor_levels=4');

​
Detailed Analysis

Get comprehensive hierarchy with statistics and synonyms: 
const detailedHierarchy = await fetch('/v1/concepts/73211009/hierarchy?include_statistics=true&include_synonyms=true&include_paths=true');

​
Notes

  • The hierarchy endpoint is optimized for visualization and provides balanced ancestor/descendant views
  • Tree format is ideal for hierarchical UI components and taxonomy browsers
  • Graph format includes node positioning hints for network visualizations
  • Statistics provide insights into hierarchy complexity and structure
  • Performance: Use the max_results parameter to control query size. The default (500) provides optimal performance for most use cases while preventing timeouts
  • Large hierarchies are automatically limited by max_results to prevent performance issues and ensure predictable response times
  • Cross-vocabulary concepts may show relationships spanning multiple vocabularies
  • Level numbering uses negative values for ancestors and positive for descendants
  • For very large hierarchies, consider paginating through results or using more specific filters to reduce result set size