Get Class Hierarchy

curl -X GET "https://api.omophub.com/v1/concept-classes/Clinical%20Finding/hierarchy?direction=both&max_levels=3&include_concept_counts=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

{
  "success": true,
  "data": {
    "concept_class": {
    "concept_class_id": "Clinical Finding",
    "concept_class_name": "Clinical Finding",
    "concept_class_concept_id": 404684003,
    "vocabulary_id": "SNOMED",
    "description": "A clinical finding represents a result of an observation, assessment, or judgment",
    "concept_count": 125847
    },
    "hierarchy": {
    "ancestors": [
      {
        "concept_class_id": "SNOMED CT Concept",
        "concept_class_name": "SNOMED CT Concept",
        "concept_class_concept_id": 138875005,
        "vocabulary_id": "SNOMED",
        "level": 1,
        "relationship_type": "Is a",
        "concept_count": 350000,
        "path_to_root": []
      }
    ],
    "descendants": [
      {
        "concept_class_id": "Disease",
        "concept_class_name": "Disease",
        "concept_class_concept_id": 64572001,
        "vocabulary_id": "SNOMED",
        "level": 1,
        "relationship_type": "Is a",
        "concept_count": 45892,
        "has_children": true
      },
      {
        "concept_class_id": "Sign or Symptom",
        "concept_class_name": "Sign or Symptom",
        "concept_class_concept_id": 418799008,
        "vocabulary_id": "SNOMED",
        "level": 1,
        "relationship_type": "Is a",
        "concept_count": 23456,
        "has_children": true
      },
      {
        "concept_class_id": "Disorder of body system",
        "concept_class_name": "Disorder of body system",
        "concept_class_concept_id": 362965005,
        "vocabulary_id": "SNOMED",
        "level": 2,
        "relationship_type": "Is a",
        "concept_count": 15623,
        "has_children": true
      }
    ],
    "siblings": [
      {
        "concept_class_id": "Procedure",
        "concept_class_name": "Procedure",
        "concept_count": 87234,
        "shared_parent": "SNOMED CT Concept"
      },
      {
        "concept_class_id": "Substance",
        "concept_class_name": "Substance",
        "concept_count": 45692,
        "shared_parent": "SNOMED CT Concept"
      }
    ]
    },
    "cross_references": [
    {
      "vocabulary_id": "ICD10CM",
      "equivalent_class_id": "Disease",
      "equivalent_class_name": "Disease and related health problems",
      "mapping_confidence": "broad",
      "concept_count": 8934
    },
    {
      "vocabulary_id": "ICD9CM",
      "equivalent_class_id": "Disease",
      "equivalent_class_name": "Diseases",
      "mapping_confidence": "broad",
      "concept_count": 5672
    }
    ],
    "hierarchy_statistics": {
    "total_ancestors": 1,
    "total_descendants": 15,
    "max_ancestor_level": 1,
    "max_descendant_level": 4,
    "is_root_class": false,
    "is_leaf_class": false,
    "total_concept_count": 125847,
      "vocabularies_involved": ["SNOMED"]
    }
  },
  "meta": {
    "request_id": "req_class_hierarchy_222",
    "timestamp": "2024-12-22T10:30:00Z",
    "vocab_release": "2025.2"
  }
}

GET

https://api.omophub.com

concept-classes

{classId}

hierarchy

curl -X GET "https://api.omophub.com/v1/concept-classes/Clinical%20Finding/hierarchy?direction=both&max_levels=3&include_concept_counts=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

{
  "success": true,
  "data": {
    "concept_class": {
    "concept_class_id": "Clinical Finding",
    "concept_class_name": "Clinical Finding",
    "concept_class_concept_id": 404684003,
    "vocabulary_id": "SNOMED",
    "description": "A clinical finding represents a result of an observation, assessment, or judgment",
    "concept_count": 125847
    },
    "hierarchy": {
    "ancestors": [
      {
        "concept_class_id": "SNOMED CT Concept",
        "concept_class_name": "SNOMED CT Concept",
        "concept_class_concept_id": 138875005,
        "vocabulary_id": "SNOMED",
        "level": 1,
        "relationship_type": "Is a",
        "concept_count": 350000,
        "path_to_root": []
      }
    ],
    "descendants": [
      {
        "concept_class_id": "Disease",
        "concept_class_name": "Disease",
        "concept_class_concept_id": 64572001,
        "vocabulary_id": "SNOMED",
        "level": 1,
        "relationship_type": "Is a",
        "concept_count": 45892,
        "has_children": true
      },
      {
        "concept_class_id": "Sign or Symptom",
        "concept_class_name": "Sign or Symptom",
        "concept_class_concept_id": 418799008,
        "vocabulary_id": "SNOMED",
        "level": 1,
        "relationship_type": "Is a",
        "concept_count": 23456,
        "has_children": true
      },
      {
        "concept_class_id": "Disorder of body system",
        "concept_class_name": "Disorder of body system",
        "concept_class_concept_id": 362965005,
        "vocabulary_id": "SNOMED",
        "level": 2,
        "relationship_type": "Is a",
        "concept_count": 15623,
        "has_children": true
      }
    ],
    "siblings": [
      {
        "concept_class_id": "Procedure",
        "concept_class_name": "Procedure",
        "concept_count": 87234,
        "shared_parent": "SNOMED CT Concept"
      },
      {
        "concept_class_id": "Substance",
        "concept_class_name": "Substance",
        "concept_count": 45692,
        "shared_parent": "SNOMED CT Concept"
      }
    ]
    },
    "cross_references": [
    {
      "vocabulary_id": "ICD10CM",
      "equivalent_class_id": "Disease",
      "equivalent_class_name": "Disease and related health problems",
      "mapping_confidence": "broad",
      "concept_count": 8934
    },
    {
      "vocabulary_id": "ICD9CM",
      "equivalent_class_id": "Disease",
      "equivalent_class_name": "Diseases",
      "mapping_confidence": "broad",
      "concept_count": 5672
    }
    ],
    "hierarchy_statistics": {
    "total_ancestors": 1,
    "total_descendants": 15,
    "max_ancestor_level": 1,
    "max_descendant_level": 4,
    "is_root_class": false,
    "is_leaf_class": false,
    "total_concept_count": 125847,
      "vocabularies_involved": ["SNOMED"]
    }
  },
  "meta": {
    "request_id": "req_class_hierarchy_222",
    "timestamp": "2024-12-22T10:30:00Z",
    "vocab_release": "2025.2"
  }
}

Overview

This endpoint returns the hierarchical structure of concept classes, showing how concept classes relate to each other through parent-child relationships. This is essential for understanding the taxonomic organization of medical terminology classification systems.

Path Parameters

classId

string

required

The concept class ID to get hierarchy for (e.g., “Clinical Finding”, “Procedure”, “Substance”)

Query Parameters

direction

string

default:"both"

Hierarchy direction: “ancestors” (parents), “descendants” (children), or “both”

max_levels

integer

default:"10"

Maximum number of hierarchy levels to traverse (1-20)

vocabulary_ids

string

Comma-separated list of vocabularies to filter hierarchy (e.g., “SNOMED,ICD10CM”)

include_concept_counts

boolean

default:"false"

Include count of concepts in each class

include_cross_references

boolean

default:"false"

Include cross-references to equivalent classes in other vocabularies

vocab_release

string

Specific vocabulary release version (e.g., “2024.1”)

Response

success

boolean

Indicates if the request was successful

concept_class

object

required

Information about the requested concept class

Show concept_class

concept_class_id

string

The concept class identifier

concept_class_name

string

Human-readable name

concept_class_concept_id

integer

Concept ID representing this class

vocabulary_id

string

Primary vocabulary defining this class

description

string

Description of the concept class

concept_count

integer

Number of concepts in this class (when include_concept_counts=true)

hierarchy

object

required

Hierarchical structure of concept classes

Show hierarchy

ancestors

array

Parent concept classes (when direction includes “ancestors”)

Show ancestors

concept_class_id

string

Parent class ID

concept_class_name

string

Parent class name

concept_class_concept_id

integer

Parent class concept ID

vocabulary_id

string

Parent class vocabulary

level

integer

Hierarchical level (1 = direct parent)

relationship_type

string

Type of hierarchical relationship

concept_count

integer

Number of concepts (when include_concept_counts=true)

path_to_root

array

Path from this class to root classes

descendants

array

Child concept classes (when direction includes “descendants”)

Show descendants

concept_class_id

string

Child class ID

concept_class_name

string

Child class name

concept_class_concept_id

integer

Child class concept ID

vocabulary_id

string

Child class vocabulary

level

integer

Hierarchical level (1 = direct child)

relationship_type

string

Type of hierarchical relationship

concept_count

integer

Number of concepts (when include_concept_counts=true)

has_children

boolean

Whether this class has child classes

siblings

array

Sibling concept classes at the same hierarchical level

Show siblings

concept_class_id

string

Sibling class ID

concept_class_name

string

Sibling class name

concept_count

integer

Number of concepts (when include_concept_counts=true)

shared_parent

string

Common parent class

cross_references

array

Equivalent classes in other vocabularies (when include_cross_references=true)

Show cross_references

vocabulary_id

string

Target vocabulary

equivalent_class_id

string

Equivalent class ID in target vocabulary

equivalent_class_name

string

Equivalent class name

mapping_confidence

string

Confidence of equivalence: “exact”, “broad”, “narrow”

concept_count

integer

Concepts in equivalent class

hierarchy_statistics

object

required

Statistics about the hierarchy structure

Show hierarchy_statistics

total_ancestors

integer

Total number of ancestor classes

total_descendants

integer

Total number of descendant classes

max_ancestor_level

integer

Maximum ancestor level reached

max_descendant_level

integer

Maximum descendant level reached

is_root_class

boolean

Whether this is a root-level class

is_leaf_class

boolean

Whether this is a leaf-level class

total_concept_count

integer

Total concepts in hierarchy branch

vocabularies_involved

array

Vocabularies represented in hierarchy

curl -X GET "https://api.omophub.com/v1/concept-classes/Clinical%20Finding/hierarchy?direction=both&max_levels=3&include_concept_counts=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

{
  "success": true,
  "data": {
    "concept_class": {
    "concept_class_id": "Clinical Finding",
    "concept_class_name": "Clinical Finding",
    "concept_class_concept_id": 404684003,
    "vocabulary_id": "SNOMED",
    "description": "A clinical finding represents a result of an observation, assessment, or judgment",
    "concept_count": 125847
    },
    "hierarchy": {
    "ancestors": [
      {
        "concept_class_id": "SNOMED CT Concept",
        "concept_class_name": "SNOMED CT Concept",
        "concept_class_concept_id": 138875005,
        "vocabulary_id": "SNOMED",
        "level": 1,
        "relationship_type": "Is a",
        "concept_count": 350000,
        "path_to_root": []
      }
    ],
    "descendants": [
      {
        "concept_class_id": "Disease",
        "concept_class_name": "Disease",
        "concept_class_concept_id": 64572001,
        "vocabulary_id": "SNOMED",
        "level": 1,
        "relationship_type": "Is a",
        "concept_count": 45892,
        "has_children": true
      },
      {
        "concept_class_id": "Sign or Symptom",
        "concept_class_name": "Sign or Symptom",
        "concept_class_concept_id": 418799008,
        "vocabulary_id": "SNOMED",
        "level": 1,
        "relationship_type": "Is a",
        "concept_count": 23456,
        "has_children": true
      },
      {
        "concept_class_id": "Disorder of body system",
        "concept_class_name": "Disorder of body system",
        "concept_class_concept_id": 362965005,
        "vocabulary_id": "SNOMED",
        "level": 2,
        "relationship_type": "Is a",
        "concept_count": 15623,
        "has_children": true
      }
    ],
    "siblings": [
      {
        "concept_class_id": "Procedure",
        "concept_class_name": "Procedure",
        "concept_count": 87234,
        "shared_parent": "SNOMED CT Concept"
      },
      {
        "concept_class_id": "Substance",
        "concept_class_name": "Substance",
        "concept_count": 45692,
        "shared_parent": "SNOMED CT Concept"
      }
    ]
    },
    "cross_references": [
    {
      "vocabulary_id": "ICD10CM",
      "equivalent_class_id": "Disease",
      "equivalent_class_name": "Disease and related health problems",
      "mapping_confidence": "broad",
      "concept_count": 8934
    },
    {
      "vocabulary_id": "ICD9CM",
      "equivalent_class_id": "Disease",
      "equivalent_class_name": "Diseases",
      "mapping_confidence": "broad",
      "concept_count": 5672
    }
    ],
    "hierarchy_statistics": {
    "total_ancestors": 1,
    "total_descendants": 15,
    "max_ancestor_level": 1,
    "max_descendant_level": 4,
    "is_root_class": false,
    "is_leaf_class": false,
    "total_concept_count": 125847,
      "vocabularies_involved": ["SNOMED"]
    }
  },
  "meta": {
    "request_id": "req_class_hierarchy_222",
    "timestamp": "2024-12-22T10:30:00Z",
    "vocab_release": "2025.2"
  }
}

Usage Examples

Basic Hierarchy

Get the basic hierarchical structure:

curl -X GET "https://api.omophub.com/v1/concept-classes/Procedure/hierarchy" \
  -H "Authorization: Bearer YOUR_API_KEY"

Ancestors Only

Get parent classes only:

curl -X GET "https://api.omophub.com/v1/concept-classes/Clinical%20Finding/hierarchy?direction=ancestors&max_levels=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Detailed Hierarchy with Counts

Get comprehensive hierarchy information:

curl -X GET "https://api.omophub.com/v1/concept-classes/Substance/hierarchy?include_concept_counts=true&include_cross_references=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Cross-Vocabulary Analysis

Compare class structures across vocabularies:

curl -X GET "https://api.omophub.com/v1/concept-classes/Clinical%20Finding/hierarchy?vocabulary_ids=SNOMED,ICD10CM&include_cross_references=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Building Taxonomy Trees

Use for creating interactive taxonomy browsers:

async function buildClassTree(rootClassId, maxDepth = 3) {
  const response = await fetch(`https://api.omophub.com/v1/concept-classes/${encodeURIComponent(rootClassId)}/hierarchy?direction=descendants&max_levels=${maxDepth}&include_concept_counts=true`, {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });
  const data = await response.json();
  
  // Build tree structure for UI components
  const buildTreeNode = (classData, level = 0) => ({
    id: classData.concept_class_id,
    name: classData.concept_class_name,
    conceptCount: classData.concept_count || 0,
    level: level,
    hasChildren: classData.has_children || false,
    children: []
  });
  
  const tree = buildTreeNode(data.data.concept_class, 0);

  // Add descendants to tree
  const levelGroups = {};
  data.data.hierarchy.descendants.forEach(desc => {
    if (!levelGroups[desc.level]) levelGroups[desc.level] = [];
    levelGroups[desc.level].push(buildTreeNode(desc, desc.level));
  });
  
  // Build hierarchical structure - sort levels numerically
  Object.keys(levelGroups).sort((a, b) => Number(a) - Number(b)).forEach(level => {
    if (level === '1') {
      tree.children = levelGroups[level];
    }
    // Add nested levels logic here
  });
  
  return tree;
}

Important Notes

URL encoding - Class IDs with spaces must be URL encoded
Vocabulary differences - Hierarchical structures vary significantly between vocabularies
Performance - Deep hierarchies with concept counts may take longer to process
Cross-references - Mapping confidence indicates quality of cross-vocabulary equivalences
Navigation - Use has_children flag to determine if further expansion is possible

Get Concept Classes - List all concept classes
Get Class Concepts - Get concepts within a class
Get Concept Hierarchy - Individual concept hierarchies

Get Class Concepts Get Domain Hierarchy

⌘I

API Reference

Concepts

Concept Hierarchy

Search

Search (Coming Soon)

Relationships

Domains & Classifications

Mappings

Vocabularies

Overview

Path Parameters

Query Parameters

Response

Usage Examples

Basic Hierarchy

Ancestors Only

Detailed Hierarchy with Counts

Cross-Vocabulary Analysis

Building Taxonomy Trees

Important Notes

API Reference

Concepts

Concept Hierarchy

Search

Search (Coming Soon)

Relationships

Domains & Classifications

Mappings

Vocabularies

​Overview

​Path Parameters

​Query Parameters

​Response

​Usage Examples

​Basic Hierarchy

​Ancestors Only

​Detailed Hierarchy with Counts

​Cross-Vocabulary Analysis

​Building Taxonomy Trees

​Important Notes

​Related Endpoints

Overview

Path Parameters

Query Parameters

Response

Usage Examples

Basic Hierarchy

Ancestors Only

Detailed Hierarchy with Counts

Cross-Vocabulary Analysis

Building Taxonomy Trees

Important Notes

Related Endpoints