Skip to main content
GET
/
v1
/
concepts
/
{concept_id}
/
hierarchy
/
paths
curl -X GET "https://api.omophub.com/v1/concepts/201826/hierarchy/paths?include_concept_details=true&include_statistics=true&path_type=all" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "concept": {
      "concept_id": 201826,
      "concept_name": "Type 2 diabetes mellitus",
      "vocabulary_id": "SNOMED",
      "domain_id": "Condition"
    },
  "hierarchy_paths": [
    {
      "path_id": "path_1",
      "path_length": 6,
      "root_concept_id": 138875005,
      "root_concept_name": "SNOMED CT Concept",
      "path_concepts": [201826, 73211009, 362969004, 64572001, 404684003, 138875005],
      "path_relationships": ["Is a", "Is a", "Is a", "Is a", "Is a"],
      "path_details": [
        {
          "concept_id": 201826,
          "concept_name": "Type 2 diabetes mellitus",
          "concept_code": "44054006",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "position_in_path": 0,
          "relationship_to_next": "Is a"
        },
        {
          "concept_id": 73211009,
          "concept_name": "Diabetes mellitus",
          "concept_code": "73211009",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition", 
          "concept_class_id": "Clinical Finding",
          "position_in_path": 1,
          "relationship_to_next": "Is a"
        },
        {
          "concept_id": 362969004,
          "concept_name": "Disorder of endocrine system",
          "concept_code": "362969004",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "position_in_path": 2,
          "relationship_to_next": "Is a"
        },
        {
          "concept_id": 64572001,
          "concept_name": "Disease",
          "concept_code": "64572001",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "position_in_path": 3,
          "relationship_to_next": "Is a"
        },
        {
          "concept_id": 404684003,
          "concept_name": "Clinical finding",
          "concept_code": "404684003",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "position_in_path": 4,
          "relationship_to_next": "Is a"
        },
        {
          "concept_id": 138875005,
          "concept_name": "SNOMED CT Concept",
          "concept_code": "138875005",
          "vocabulary_id": "SNOMED",
          "domain_id": "Metadata",
          "concept_class_id": "Model Component",
          "position_in_path": 5,
          "relationship_to_next": null
        }
      ],
      "path_score": 0.95,
      "is_primary_path": true,
      "path_complexity": "moderate"
    }
  ],
  "path_analysis": {
    "total_paths": 1,
    "unique_root_concepts": 1,
    "average_path_length": 6.0,
    "shortest_path_length": 6,
    "longest_path_length": 6,
    "common_ancestors": [
      "Diabetes mellitus",
      "Disorder of endocrine system", 
      "Disease",
      "Clinical finding"
    ],
    "vocabulary_distribution": {
      "SNOMED": 6
    },
    "domain_distribution": {
      "Condition": 6
    },
    "relationship_types_used": ["Is a"],
    "classification_consistency": 1.0
  },
  "root_concepts": [
      {
        "concept_id": 138875005,
        "concept_name": "SNOMED CT Concept",
        "vocabulary_id": "SNOMED",
        "paths_to_root": 1,
        "shortest_path_to_root": 6
      }
    ]
  },
  "meta": {
    "request_id": "req_hierarchy_paths_201826_20241222_103200",
    "timestamp": "2024-12-22T10:32:00Z",
    "vocab_release": "2025.2"
  }
}
This endpoint provides detailed analysis of all possible classification paths from a specific concept to its root concepts, essential for understanding complex medical taxonomy relationships and multiple inheritance patterns.

​
Path Parameters

​
concept_id
integer
required
The unique identifier of the concept to retrieve hierarchy paths for
Example: 201826 (Type 2 diabetes mellitus)

​
Query Parameters

​
vocabulary_id
string
Filter paths to specific vocabulary
Example: SNOMED
​
relationship_types
string
Comma-separated list of relationship types to follow for path traversal
Default: Is a
Example: Is a,Part of
​
include_intermediate
boolean
default:"true"
Include all intermediate concepts in each path
​
include_concept_details
boolean
default:"false"
Include detailed information for each concept in paths
​
max_path_length
integer
Maximum number of concepts allowed in any single path
Range: 2-15 (inclusive). Out-of-range values are rejected with 400 Bad Request and descriptive error message.
​
standard_only
boolean
default:"true"
Only include standard concepts in paths
​
include_deprecated
boolean
default:"false"
Include deprecated/invalid concepts in paths
​
path_type
string
default:"all"
Type of paths to retrieve
Options: all, shortest, longest, distinct_roots
​
include_statistics
boolean
default:"false"
Include path analysis and statistics
​
format
string
default:"detailed"
Response format for path data. Formats are mutually exclusive.
Options:
  • detailed/compact: Returns hierarchy_paths array with path objects and metadata
  • graph: Returns nodes and edges arrays (does NOT include hierarchy_paths)

Detailed/Compact format returns:
  • hierarchy_paths: Array of path objects with full details
  • meta: Metadata about the query and results

Graph format returns:
  • nodes: Array with id, label, optional metadata
  • edges: Array with source, target, optional label/metadata
  • meta: Metadata about the query and results

​
Response

​
concept
object
The source concept for which paths were retrieved
​
hierarchy_paths
array
Array of complete hierarchical paths to root concepts
​
path_analysis
object
Statistical analysis of all paths (when include_statistics=true)
​
root_concepts
array
Summary of all root concepts reached through paths
​
nodes
array
Array of graph nodes (when format=graph)
​
edges
array
Array of graph edges connecting nodes (when format=graph)

​
Errors

​
400
object
Bad Request - Invalid parameter values
​
404
object
Not Found - Concept or hierarchy not found
​
422
object
Unprocessable Entity - Semantic validation fails
​
500
object
Internal Server Error - Server processing error
curl -X GET "https://api.omophub.com/v1/concepts/201826/hierarchy/paths?include_concept_details=true&include_statistics=true&path_type=all" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "concept": {
      "concept_id": 201826,
      "concept_name": "Type 2 diabetes mellitus",
      "vocabulary_id": "SNOMED",
      "domain_id": "Condition"
    },
  "hierarchy_paths": [
    {
      "path_id": "path_1",
      "path_length": 6,
      "root_concept_id": 138875005,
      "root_concept_name": "SNOMED CT Concept",
      "path_concepts": [201826, 73211009, 362969004, 64572001, 404684003, 138875005],
      "path_relationships": ["Is a", "Is a", "Is a", "Is a", "Is a"],
      "path_details": [
        {
          "concept_id": 201826,
          "concept_name": "Type 2 diabetes mellitus",
          "concept_code": "44054006",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "position_in_path": 0,
          "relationship_to_next": "Is a"
        },
        {
          "concept_id": 73211009,
          "concept_name": "Diabetes mellitus",
          "concept_code": "73211009",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition", 
          "concept_class_id": "Clinical Finding",
          "position_in_path": 1,
          "relationship_to_next": "Is a"
        },
        {
          "concept_id": 362969004,
          "concept_name": "Disorder of endocrine system",
          "concept_code": "362969004",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "position_in_path": 2,
          "relationship_to_next": "Is a"
        },
        {
          "concept_id": 64572001,
          "concept_name": "Disease",
          "concept_code": "64572001",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "position_in_path": 3,
          "relationship_to_next": "Is a"
        },
        {
          "concept_id": 404684003,
          "concept_name": "Clinical finding",
          "concept_code": "404684003",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "position_in_path": 4,
          "relationship_to_next": "Is a"
        },
        {
          "concept_id": 138875005,
          "concept_name": "SNOMED CT Concept",
          "concept_code": "138875005",
          "vocabulary_id": "SNOMED",
          "domain_id": "Metadata",
          "concept_class_id": "Model Component",
          "position_in_path": 5,
          "relationship_to_next": null
        }
      ],
      "path_score": 0.95,
      "is_primary_path": true,
      "path_complexity": "moderate"
    }
  ],
  "path_analysis": {
    "total_paths": 1,
    "unique_root_concepts": 1,
    "average_path_length": 6.0,
    "shortest_path_length": 6,
    "longest_path_length": 6,
    "common_ancestors": [
      "Diabetes mellitus",
      "Disorder of endocrine system", 
      "Disease",
      "Clinical finding"
    ],
    "vocabulary_distribution": {
      "SNOMED": 6
    },
    "domain_distribution": {
      "Condition": 6
    },
    "relationship_types_used": ["Is a"],
    "classification_consistency": 1.0
  },
  "root_concepts": [
      {
        "concept_id": 138875005,
        "concept_name": "SNOMED CT Concept",
        "vocabulary_id": "SNOMED",
        "paths_to_root": 1,
        "shortest_path_to_root": 6
      }
    ]
  },
  "meta": {
    "request_id": "req_hierarchy_paths_201826_20241222_103200",
    "timestamp": "2024-12-22T10:32:00Z",
    "vocab_release": "2025.2"
  }
}

​
Usage Examples

​
All Classification Paths

Get all possible hierarchical paths for a concept: 
const allPaths = await fetch('/v1/concepts/201826/hierarchy/paths?path_type=all');

​
Shortest Paths Only

Retrieve only the shortest paths to root concepts: 
const shortestPaths = await fetch('/v1/concepts/201826/hierarchy/paths?path_type=shortest&include_statistics=true');

​
Detailed Path Analysis

Get comprehensive path information with concept details: 
const detailedPaths = await fetch('/v1/concepts/201826/hierarchy/paths?include_concept_details=true&include_statistics=true');

​
Cross-Vocabulary Paths

Analyze paths across multiple vocabularies: 
// Build URL with proper encoding
const params = new URLSearchParams({
  relationship_types: 'Is a,Maps to'
});
const crossVocabPaths = await fetch(`/v1/concepts/201826/hierarchy/paths?${params.toString()}`);

​
Graph Format for Visualization

Get path data in graph format for network visualization: 
const graphPaths = await fetch('/v1/concepts/201826/hierarchy/paths?format=graph');

​
Notes

  • Path analysis is essential for understanding complex medical taxonomies with multiple inheritance
  • Primary paths represent the most commonly used or clinically relevant classification route
  • Path scores consider factors like clinical relevance, path length, and concept standardization
  • Some concepts may have dozens of classification paths in complex vocabularies like SNOMED CT
  • Common ancestors help identify key classification concepts shared across multiple paths
  • Cross-vocabulary paths may include mapping relationships in addition to hierarchical ones
  • Path complexity assessment helps identify concepts with unusual or complex classification patterns