Skip to main content
GET
https://api.omophub.com
/
v1
/
concepts
/
{conceptId}
/
level
curl -X GET "https://api.omophub.com/v1/concepts/201826/level?include_paths=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": {
    "concept": {
      "concept_id": 201826,
      "concept_name": "Type 2 diabetes mellitus",
      "vocabulary_id": "SNOMED",
      "domain_id": "Condition",
      "concept_class_id": "Clinical Finding"
    },
    "hierarchy_info": {
      "min_levels_from_top": 4,
      "max_levels_from_top": 6,
      "average_levels_from_top": 4.8,
      "min_levels_from_bottom": 2,
      "max_levels_from_bottom": 5,
      "is_root_concept": false,
      "is_leaf_concept": false,
      "has_children": true,
      "has_parents": true,
      "direct_children_count": 15,
      "direct_parents_count": 3
    },
    "taxonomy_context": {
      "vocabulary_max_depth": 12,
      "relative_depth_percentage": 40.0,
      "granularity_level": "moderate",
      "taxonomy_branch": "Endocrine/metabolic disorders"
    },
    "sample_paths": [
      {
        "path_to_root": [
          {
            "concept_id": 138875005,
            "concept_name": "SNOMED CT Concept",
            "level": 0,
            "relationship_type": "Is a"
          },
          {
            "concept_id": 404684003,
            "concept_name": "Clinical finding",
            "level": 1,
            "relationship_type": "Is a"
          },
          {
            "concept_id": 64572001,
            "concept_name": "Disease",
            "level": 2,
            "relationship_type": "Is a"
          },
          {
            "concept_id": 73211009,
            "concept_name": "Diabetes mellitus",
            "level": 3,
            "relationship_type": "Is a"
          },
          {
            "concept_id": 201826,
            "concept_name": "Type 2 diabetes mellitus",
            "level": 4,
            "relationship_type": null
          }
        ],
        "path_length": 5
      }
    ]
  },
  "meta": {
    "request_id": "req_concept_level_123",
    "timestamp": "2024-12-22T10:00:00Z",
    "vocab_release": "2025.2"
  }
}

​
Overview

This endpoint returns hierarchical positioning information for a concept, including its level in the taxonomy tree, distance from root concepts, and depth metrics. This is essential for understanding concept granularity and hierarchy navigation.

​
Path Parameters

​
conceptId
integer
required
The unique OMOP concept ID to get level information for

​
Query Parameters

​
vocabulary_id
string
Filter to specific vocabulary (uses concept’s primary vocabulary if not specified)
​
relationship_type
string
default:"Is a"
Relationship type to use for hierarchy calculation (e.g., “Is a”, “Subsumes”)
​
include_paths
boolean
default:"false"
Include sample paths to root concepts
​
vocab_release
string
Specific vocabulary release version (e.g., “2024.1”)

​
Response

​
success
boolean
required
Indicates whether the request was successful
​
data
object
required
Response data containing concept level information
​
meta
object
required
Response metadata and API information
curl -X GET "https://api.omophub.com/v1/concepts/201826/level?include_paths=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": {
    "concept": {
      "concept_id": 201826,
      "concept_name": "Type 2 diabetes mellitus",
      "vocabulary_id": "SNOMED",
      "domain_id": "Condition",
      "concept_class_id": "Clinical Finding"
    },
    "hierarchy_info": {
      "min_levels_from_top": 4,
      "max_levels_from_top": 6,
      "average_levels_from_top": 4.8,
      "min_levels_from_bottom": 2,
      "max_levels_from_bottom": 5,
      "is_root_concept": false,
      "is_leaf_concept": false,
      "has_children": true,
      "has_parents": true,
      "direct_children_count": 15,
      "direct_parents_count": 3
    },
    "taxonomy_context": {
      "vocabulary_max_depth": 12,
      "relative_depth_percentage": 40.0,
      "granularity_level": "moderate",
      "taxonomy_branch": "Endocrine/metabolic disorders"
    },
    "sample_paths": [
      {
        "path_to_root": [
          {
            "concept_id": 138875005,
            "concept_name": "SNOMED CT Concept",
            "level": 0,
            "relationship_type": "Is a"
          },
          {
            "concept_id": 404684003,
            "concept_name": "Clinical finding",
            "level": 1,
            "relationship_type": "Is a"
          },
          {
            "concept_id": 64572001,
            "concept_name": "Disease",
            "level": 2,
            "relationship_type": "Is a"
          },
          {
            "concept_id": 73211009,
            "concept_name": "Diabetes mellitus",
            "level": 3,
            "relationship_type": "Is a"
          },
          {
            "concept_id": 201826,
            "concept_name": "Type 2 diabetes mellitus",
            "level": 4,
            "relationship_type": null
          }
        ],
        "path_length": 5
      }
    ]
  },
  "meta": {
    "request_id": "req_concept_level_123",
    "timestamp": "2024-12-22T10:00:00Z",
    "vocab_release": "2025.2"
  }
}

​
Usage Examples

​
Basic Level Information

Get hierarchy level for a concept: 
curl -X GET "https://api.omophub.com/v1/concepts/201826/level" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Level with Sample Paths

Get level information including sample paths to root: 
curl -X GET "https://api.omophub.com/v1/concepts/201826/level?include_paths=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Specific Relationship Type

Use different relationship type for hierarchy calculation: 
curl -X GET "https://api.omophub.com/v1/concepts/201826/level?relationship_type=Subsumes" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Important Notes

  • Multiple paths - Concepts may have multiple paths to root concepts with different lengths
  • Granularity classification - Helps understand concept specificity level
  • Performance - Including paths increases response time but provides valuable context
  • Vocabulary differences - Hierarchy depth varies significantly between vocabularies
  • Relationship types - Different relationship types may produce different hierarchy views