Skip to main content
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
​
hierarchy
object
required
Hierarchical structure of concept classes
​
cross_references
array
Equivalent classes in other vocabularies (when include_cross_references=true)
​
hierarchy_statistics
object
required
Statistics about the hierarchy structure
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
⌘I