Get Domain Hierarchy

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

GET

domains

{domain_id}

hierarchy

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

Show Domain Information Object

domain_id

string

Domain identifier

domain_name

string

Human-readable domain name

description

string

Domain description

total_concepts_in_domain

integer

Total concepts in the domain

hierarchy

object

The hierarchical structure of the domain

Show Hierarchy Structure Object

root_concepts

array

Top-level concepts in the domain hierarchy

Show Hierarchy Node Object

concept_id

integer

Unique concept identifier

concept_name

string

Standard name of the concept

concept_code

string

Original code from the vocabulary

vocabulary_id

string

Vocabulary containing this concept

vocabulary_name

string

Human-readable vocabulary name

concept_class_id

string

Concept class identifier

concept_class_name

string

Human-readable concept class name

standard_concept

string

Standard concept designation (‘S’, ‘C’, or null)

hierarchy_level

integer

Level in the hierarchy (0 = root)

path_from_root

array

Array of concept IDs representing path from domain root

descendant_count

integer

Number of descendant concepts (when include_concept_counts=true)

direct_children_count

integer

Number of direct child concepts

children

array

Array of child concepts (nested structure)

is_leaf

boolean

Whether this concept has no children

branch_statistics

object

Statistics about this branch of the hierarchy

Show Branch Statistics Object

max_depth_below

integer

Maximum depth of hierarchy below this node

total_descendants

integer

Total number of descendant concepts

vocabulary_distribution

object

Distribution of vocabularies in this branch

concept_class_distribution

object

Distribution of concept classes in this branch

valid_start_date

string

Date when concept became valid

valid_end_date

string

Date when concept becomes invalid

hierarchy_paths

array

All paths from root to leaf (when format=‘flat’). Note: when format=‘flat’, the root_concepts field is not included in the response and each hierarchy_paths entry contains only the listed path fields.

Show Hierarchy Path Object

path_id

string

Unique identifier for this path

concept_ids

array

Array of concept IDs in hierarchical order

concept_names

array

Array of concept names in hierarchical order

path_length

integer

Number of concepts in this path

leaf_concept

object

Information about the leaf concept at the end of this path

hierarchy_statistics

object

Statistical summary of the domain hierarchy

Show Hierarchy Statistics Object

total_nodes_in_hierarchy

integer

Total number of concepts included in hierarchy response

root_concepts_count

integer

Number of top-level root concepts

leaf_concepts_count

integer

Number of leaf concepts (no children)

max_hierarchy_depth

integer

Maximum depth of the hierarchy tree

average_branching_factor

number

Average number of children per non-leaf concept

vocabulary_distribution

object

Distribution of concepts by vocabulary in hierarchy

concept_class_distribution

object

Distribution of concepts by concept class in hierarchy

depth_distribution

object

Number of concepts at each hierarchy level

orphaned_concepts

integer

Concepts in domain without hierarchical relationships

Suggestions for UI navigation and display

Show Navigation Hints Object

meta

object

Response metadata and processing information

Show Metadata Object

applied_filters

object

Summary of filters applied to hierarchy generation

generation_time_ms

number

Time taken to generate hierarchy

data_freshness

string

Timestamp of underlying vocabulary data

truncation_applied

boolean

Whether hierarchy was truncated due to size limits

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');

Get Domains - Available domains
Get Domain Concepts - All concepts in domain
Get Concept Ancestors - Specific concept ancestry
Get Concept Descendants - Specific concept children

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

Get Class Hierarchy Get Concept Mappings

⌘I

API Reference

Concepts

Concept Hierarchy

Search

Search (Coming Soon)

Relationships

Domains & Classifications

Mappings

Vocabularies

Path Parameters

Query Parameters

Response

Usage Examples

Basic Domain Hierarchy

Limited Depth Hierarchy

SNOMED-Only Hierarchy

Flat Path Format

Specific Root Analysis

Notes

API Reference

Concepts

Concept Hierarchy

Search

Search (Coming Soon)

Relationships

Domains & Classifications

Mappings

Vocabularies

​Path Parameters

​Query Parameters

​Response

​Usage Examples

​Basic Domain Hierarchy

​Limited Depth Hierarchy

​SNOMED-Only Hierarchy

​Flat Path Format

​Specific Root Analysis

​Related Endpoints

​Notes

Path Parameters

Query Parameters

Response

Usage Examples

Basic Domain Hierarchy

Limited Depth Hierarchy

SNOMED-Only Hierarchy

Flat Path Format

Specific Root Analysis

Related Endpoints

Notes