Skip to main content
curl -X GET "https://api.omophub.com/v1/domains/Condition/hierarchy?vocabulary_ids=SNOMED&max_depth=3&include_concept_counts=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

{
  "success": true,
  "data": {
    "domain": {
    "domain_id": "Condition",
    "domain_name": "Condition",
    "description": "Medical conditions, diseases, disorders, and clinical findings",
    "total_concepts_in_domain": 845672
    },
    "hierarchy": {
    "root_concepts": [
      {
        "concept_id": 404684003,
        "concept_name": "Clinical finding",
        "concept_code": "404684003",
        "vocabulary_id": "SNOMED",
        "vocabulary_name": "Systematized Nomenclature of Medicine Clinical Terms",
        "concept_class_id": "Clinical Finding",
        "concept_class_name": "Clinical Finding",
        "standard_concept": "S",
        "hierarchy_level": 0,
        "path_from_root": [404684003],
        "descendant_count": 387421,
        "direct_children_count": 23,
        "is_leaf": false,
        "children": [
          {
            "concept_id": 64572001,
            "concept_name": "Disease",
            "concept_code": "64572001",
            "vocabulary_id": "SNOMED",
            "vocabulary_name": "Systematized Nomenclature of Medicine Clinical Terms",
            "concept_class_id": "Clinical Finding",
            "concept_class_name": "Clinical Finding",
            "standard_concept": "S",
            "hierarchy_level": 1,
            "path_from_root": [404684003, 64572001],
            "descendant_count": 234567,
            "direct_children_count": 15,
            "is_leaf": false,
            "children": [
              {
                "concept_id": 362969004,
                "concept_name": "Disorder of endocrine system",
                "concept_code": "362969004",
                "vocabulary_id": "SNOMED",
                "vocabulary_name": "Systematized Nomenclature of Medicine Clinical Terms",
                "concept_class_id": "Clinical Finding",
                "concept_class_name": "Clinical Finding",
                "standard_concept": "S",
                "hierarchy_level": 2,
                "path_from_root": [404684003, 64572001, 362969004],
                "descendant_count": 12847,
                "direct_children_count": 8,
                "is_leaf": false,
                "children": [
                  {
                    "concept_id": 73211009,
                    "concept_name": "Diabetes mellitus",
                    "concept_code": "73211009",
                    "vocabulary_id": "SNOMED",
                    "vocabulary_name": "Systematized Nomenclature of Medicine Clinical Terms",
                    "concept_class_id": "Clinical Finding",
                    "concept_class_name": "Clinical Finding",
                    "standard_concept": "S",
                    "hierarchy_level": 3,
                    "path_from_root": [404684003, 64572001, 362969004, 73211009],
                    "descendant_count": 847,
                    "direct_children_count": 23,
                    "is_leaf": false,
                    "children": [],
                    "branch_statistics": {
                      "max_depth_below": 3,
                      "total_descendants": 847,
                      "vocabulary_distribution": {
                        "SNOMED": 847
                      },
                      "concept_class_distribution": {
                        "Clinical Finding": 723,
                        "Disorder": 124
                      }
                    },
                    "valid_start_date": "1970-01-01T00:00:00Z",
                    "valid_end_date": "2099-12-31T00:00:00Z"
                  }
                ]
              }
            ]
          }
        ],
        "branch_statistics": {
          "max_depth_below": 8,
          "total_descendants": 387421,
          "vocabulary_distribution": {
            "SNOMED": 387421
          },
          "concept_class_distribution": {
            "Clinical Finding": 298456,
            "Disorder": 88965
          }
        },
        "valid_start_date": "1970-01-01T00:00:00Z",
        "valid_end_date": "2099-12-31T00:00:00Z"
      }
    ]
    },
    "hierarchy_statistics": {
    "total_nodes_in_hierarchy": 4567,
    "root_concepts_count": 3,
    "leaf_concepts_count": 0,
    "max_hierarchy_depth": 8,
    "average_branching_factor": 4.2,
    "vocabulary_distribution": {
      "SNOMED": 4567
    },
    "concept_class_distribution": {
      "Clinical Finding": 3456,
      "Disorder": 1111
    },
    "depth_distribution": {
      "0": 3,
      "1": 47,
      "2": 234,
      "3": 1456
    },
    "orphaned_concepts": 12456
    },
    "navigation_hints": {
    "suggested_root_concepts": [
      {
        "concept_id": 404684003,
        "concept_name": "Clinical finding",
        "descendant_count": 387421
      },
      {
        "concept_id": 272379006,
        "concept_name": "Event",
        "descendant_count": 45678
      }
    ],
    "major_branches": [
      {
        "concept_id": 64572001,
        "concept_name": "Disease",
        "descendant_count": 234567
      },
      {
        "concept_id": 118234003,
        "concept_name": "Finding by site",
        "descendant_count": 89234
      }
    ],
    "popular_leaf_concepts": [
      {
        "concept_id": 201826,
        "concept_name": "Type 2 diabetes mellitus"
      }
    ],
    "breadcrumb_separators": [">", "→", "/"]
    }
  },
  "meta": {
    "applied_filters": {
      "vocabulary_ids": ["SNOMED"],
      "max_depth": 3,
      "standard_only": true,
      "active_only": true
    },
    "request_id": "req_domain_hierarchy_101",
    "timestamp": "2024-12-22T10:30:00Z",
    "vocab_release": "2025.2"
  }
}
This endpoint provides a comprehensive view of the hierarchical organization within a domain, showing how concepts are structured from top-level categories down to specific terms. It’s essential for understanding domain taxonomy and building navigation interfaces.

​
Path Parameters

​
domain_id
string
required
The domain identifier to retrieve hierarchy for
Example: Condition, Drug, Procedure

​
Query Parameters

​
vocabulary_ids
string
Filter hierarchy to specific vocabularies within the domain
Example: SNOMED,ICD10CM
​
root_concept_id
integer
Start hierarchy from a specific root concept (instead of domain roots)
Example: 404684003 (Clinical finding)
​
max_depth
integer
default:"5"
Maximum hierarchy depth to traverse
Range: 1-10
​
min_children_threshold
integer
default:"1"
Minimum number of children required to include a concept in hierarchy
​
include_concept_counts
boolean
default:"true"
Include count of descendant concepts for each node
​
include_leaf_concepts
boolean
default:"false"
Include concepts with no children (leaf nodes)
​
standard_only
boolean
default:"true"
Only include standard concepts in hierarchy
​
active_only
boolean
default:"true"
Only include active (non-deprecated) concepts
​
format
string
default:"nested"
Response format for hierarchy data
Options:
  • nested - Hierarchical parent-child objects with nested structure preserved
  • flat - Flattened array of hierarchy_paths (each entry is a root→leaf path with depth implied by path length)
  • tree - One or more root-based trees (may include multiple disconnected root nodes) suitable for tree rendering
​
sort_by
string
default:"concept_name"
Sort hierarchy nodes by specified criteria
Options: concept_name, concept_id, direct_children_count
​
sort_order
string
default:"asc"
Sort order for hierarchy nodes
Options: asc, desc

​
Response

​
domain
object
Information about the domain being analyzed
​
hierarchy
object
The hierarchical structure of the domain
​
hierarchy_statistics
object
Statistical summary of the domain hierarchy
​
navigation_hints
object
Suggestions for UI navigation and display
​
meta
object
Response metadata and processing information
curl -X GET "https://api.omophub.com/v1/domains/Condition/hierarchy?vocabulary_ids=SNOMED&max_depth=3&include_concept_counts=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

{
  "success": true,
  "data": {
    "domain": {
    "domain_id": "Condition",
    "domain_name": "Condition",
    "description": "Medical conditions, diseases, disorders, and clinical findings",
    "total_concepts_in_domain": 845672
    },
    "hierarchy": {
    "root_concepts": [
      {
        "concept_id": 404684003,
        "concept_name": "Clinical finding",
        "concept_code": "404684003",
        "vocabulary_id": "SNOMED",
        "vocabulary_name": "Systematized Nomenclature of Medicine Clinical Terms",
        "concept_class_id": "Clinical Finding",
        "concept_class_name": "Clinical Finding",
        "standard_concept": "S",
        "hierarchy_level": 0,
        "path_from_root": [404684003],
        "descendant_count": 387421,
        "direct_children_count": 23,
        "is_leaf": false,
        "children": [
          {
            "concept_id": 64572001,
            "concept_name": "Disease",
            "concept_code": "64572001",
            "vocabulary_id": "SNOMED",
            "vocabulary_name": "Systematized Nomenclature of Medicine Clinical Terms",
            "concept_class_id": "Clinical Finding",
            "concept_class_name": "Clinical Finding",
            "standard_concept": "S",
            "hierarchy_level": 1,
            "path_from_root": [404684003, 64572001],
            "descendant_count": 234567,
            "direct_children_count": 15,
            "is_leaf": false,
            "children": [
              {
                "concept_id": 362969004,
                "concept_name": "Disorder of endocrine system",
                "concept_code": "362969004",
                "vocabulary_id": "SNOMED",
                "vocabulary_name": "Systematized Nomenclature of Medicine Clinical Terms",
                "concept_class_id": "Clinical Finding",
                "concept_class_name": "Clinical Finding",
                "standard_concept": "S",
                "hierarchy_level": 2,
                "path_from_root": [404684003, 64572001, 362969004],
                "descendant_count": 12847,
                "direct_children_count": 8,
                "is_leaf": false,
                "children": [
                  {
                    "concept_id": 73211009,
                    "concept_name": "Diabetes mellitus",
                    "concept_code": "73211009",
                    "vocabulary_id": "SNOMED",
                    "vocabulary_name": "Systematized Nomenclature of Medicine Clinical Terms",
                    "concept_class_id": "Clinical Finding",
                    "concept_class_name": "Clinical Finding",
                    "standard_concept": "S",
                    "hierarchy_level": 3,
                    "path_from_root": [404684003, 64572001, 362969004, 73211009],
                    "descendant_count": 847,
                    "direct_children_count": 23,
                    "is_leaf": false,
                    "children": [],
                    "branch_statistics": {
                      "max_depth_below": 3,
                      "total_descendants": 847,
                      "vocabulary_distribution": {
                        "SNOMED": 847
                      },
                      "concept_class_distribution": {
                        "Clinical Finding": 723,
                        "Disorder": 124
                      }
                    },
                    "valid_start_date": "1970-01-01T00:00:00Z",
                    "valid_end_date": "2099-12-31T00:00:00Z"
                  }
                ]
              }
            ]
          }
        ],
        "branch_statistics": {
          "max_depth_below": 8,
          "total_descendants": 387421,
          "vocabulary_distribution": {
            "SNOMED": 387421
          },
          "concept_class_distribution": {
            "Clinical Finding": 298456,
            "Disorder": 88965
          }
        },
        "valid_start_date": "1970-01-01T00:00:00Z",
        "valid_end_date": "2099-12-31T00:00:00Z"
      }
    ]
    },
    "hierarchy_statistics": {
    "total_nodes_in_hierarchy": 4567,
    "root_concepts_count": 3,
    "leaf_concepts_count": 0,
    "max_hierarchy_depth": 8,
    "average_branching_factor": 4.2,
    "vocabulary_distribution": {
      "SNOMED": 4567
    },
    "concept_class_distribution": {
      "Clinical Finding": 3456,
      "Disorder": 1111
    },
    "depth_distribution": {
      "0": 3,
      "1": 47,
      "2": 234,
      "3": 1456
    },
    "orphaned_concepts": 12456
    },
    "navigation_hints": {
    "suggested_root_concepts": [
      {
        "concept_id": 404684003,
        "concept_name": "Clinical finding",
        "descendant_count": 387421
      },
      {
        "concept_id": 272379006,
        "concept_name": "Event",
        "descendant_count": 45678
      }
    ],
    "major_branches": [
      {
        "concept_id": 64572001,
        "concept_name": "Disease",
        "descendant_count": 234567
      },
      {
        "concept_id": 118234003,
        "concept_name": "Finding by site",
        "descendant_count": 89234
      }
    ],
    "popular_leaf_concepts": [
      {
        "concept_id": 201826,
        "concept_name": "Type 2 diabetes mellitus"
      }
    ],
    "breadcrumb_separators": [">", "→", "/"]
    }
  },
  "meta": {
    "applied_filters": {
      "vocabulary_ids": ["SNOMED"],
      "max_depth": 3,
      "standard_only": true,
      "active_only": true
    },
    "request_id": "req_domain_hierarchy_101",
    "timestamp": "2024-12-22T10:30:00Z",
    "vocab_release": "2025.2"
  }
}

​
Usage Examples

​
Basic Domain Hierarchy

Get the hierarchical structure of a domain: 
const hierarchy = await fetch('/v1/domains/Condition/hierarchy');

​
Limited Depth Hierarchy

Get hierarchy with limited depth for performance: 
const shallowHierarchy = await fetch('/v1/domains/Drug/hierarchy?max_depth=2&min_children_threshold=10');

​
SNOMED-Only Hierarchy

Get hierarchy for specific vocabulary: 
const snomedHierarchy = await fetch('/v1/domains/Condition/hierarchy?vocabulary_ids=SNOMED&include_concept_counts=true');

​
Flat Path Format

Get hierarchy as flat paths instead of nested structure: 
const pathHierarchy = await fetch('/v1/domains/Procedure/hierarchy?format=flat');

​
Specific Root Analysis

Start hierarchy from a specific concept: 
const diabetesHierarchy = await fetch('/v1/domains/Condition/hierarchy?root_concept_id=73211009&max_depth=5');

​
Notes

  • Domain hierarchies can be very large - use depth limits and thresholds appropriately
  • Standard concepts provide more reliable hierarchical structures
  • Some domains have multiple disconnected root nodes when using tree format
  • Navigation hints help build intuitive user interfaces
  • Orphaned concepts exist in the domain but lack hierarchical relationships
  • Vocabulary-specific hierarchies may have different organizational principles
  • Branch statistics help identify significant sub-domains for focused analysis
  • Truncation may occur for very large hierarchies to maintain performance
⌘I