Skip to main content
curl -X POST "https://api.omophub.com/v1/concepts/relationships/traverse" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "concept_ids": [201826],
    "traversal_params": {
      "relationship_types": ["Is a", "Maps to"],
      "max_depth": 3
    }
  }'

{
  "success": true,
  "data": {
    "starting_concepts": [201826],
    "discovered_concepts": [
      {
        "concept_id": 73211009,
        "concept_name": "Diabetes mellitus",
        "vocabulary_id": "SNOMED",
        "distance": 1,
        "path": ["Type 2 diabetes mellitus", "Diabetes mellitus"],
        "relationship_path": ["Is a"]
      },
      {
        "concept_id": 443767,
        "concept_name": "Type 2 diabetes mellitus with complications",
        "vocabulary_id": "SNOMED",
        "distance": 1,
        "path": ["Type 2 diabetes mellitus", "Type 2 diabetes mellitus with complications"],
        "relationship_path": ["Subsumes"]
      },
      {
        "concept_id": 435216,
        "concept_name": "Type 2 diabetes mellitus",
        "vocabulary_id": "ICD10CM",
        "distance": 1,
        "path": ["Type 2 diabetes mellitus", "Type 2 diabetes mellitus"],
        "relationship_path": ["Maps to"]
      }
    ],
    "relationship_paths": [],
    "traversal_summary": {
      "total_discovered": 25,
      "max_distance_reached": 3,
      "relationship_types_used": ["Is a", "Subsumes", "Maps to"]
    }
  },
  "meta": {
    "request_id": "req_traverse_123",
    "timestamp": "2025-01-15T10:00:00Z",
    "vocab_release": "2025.1"
  }
}

​
Overview

This endpoint allows you to traverse relationship networks starting from one or more concepts, following chains of relationships to discover connected concepts. Uses a recursive graph traversal algorithm with cycle detection.

​
Request Body

​
concept_ids
array
required
Array of starting concept IDs for traversal (1-50 concepts)
​
traversal_params
object
Optional parameters for controlling the traversal

​
Query Parameters

​
vocab_release
string
Specific vocabulary release version (e.g., “2025.1”)

​
Response

​
success
boolean
required
Indicates whether the request was successful
​
data
object
required
Response data containing traversal results
​
meta
object
required
Response metadata
curl -X POST "https://api.omophub.com/v1/concepts/relationships/traverse" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "concept_ids": [201826],
    "traversal_params": {
      "relationship_types": ["Is a", "Maps to"],
      "max_depth": 3
    }
  }'

{
  "success": true,
  "data": {
    "starting_concepts": [201826],
    "discovered_concepts": [
      {
        "concept_id": 73211009,
        "concept_name": "Diabetes mellitus",
        "vocabulary_id": "SNOMED",
        "distance": 1,
        "path": ["Type 2 diabetes mellitus", "Diabetes mellitus"],
        "relationship_path": ["Is a"]
      },
      {
        "concept_id": 443767,
        "concept_name": "Type 2 diabetes mellitus with complications",
        "vocabulary_id": "SNOMED",
        "distance": 1,
        "path": ["Type 2 diabetes mellitus", "Type 2 diabetes mellitus with complications"],
        "relationship_path": ["Subsumes"]
      },
      {
        "concept_id": 435216,
        "concept_name": "Type 2 diabetes mellitus",
        "vocabulary_id": "ICD10CM",
        "distance": 1,
        "path": ["Type 2 diabetes mellitus", "Type 2 diabetes mellitus"],
        "relationship_path": ["Maps to"]
      }
    ],
    "relationship_paths": [],
    "traversal_summary": {
      "total_discovered": 25,
      "max_distance_reached": 3,
      "relationship_types_used": ["Is a", "Subsumes", "Maps to"]
    }
  },
  "meta": {
    "request_id": "req_traverse_123",
    "timestamp": "2025-01-15T10:00:00Z",
    "vocab_release": "2025.1"
  }
}

​
Usage Examples

​
Basic Traversal

Simple traversal with default settings: 
{
  "concept_ids": [201826],
  "traversal_params": {
    "max_depth": 2
  }
}

​
With Path Details

Include detailed path information: 
{
  "concept_ids": [201826],
  "traversal_params": {
    "relationship_types": ["Is a", "Maps to"],
    "max_depth": 3,
    "include_paths": true
  }
}

​
Multiple Starting Concepts

Traverse from multiple concepts: 
{
  "concept_ids": [201826, 4182210, 313217],
  "traversal_params": {
    "max_depth": 2,
    "page_size": 50
  }
}

​
Vocabulary-Filtered Traversal

Limit to specific vocabularies: 
{
  "concept_ids": [201826],
  "traversal_params": {
    "vocabulary_ids": ["SNOMED", "ICD10CM"],
    "max_depth": 3
  }
}

​
Important Notes

  • Concept limit: Maximum 50 starting concepts per request
  • Depth limit: Maximum traversal depth is 5 to prevent performance issues
  • Cycle detection: The algorithm prevents infinite loops by tracking visited concepts
  • Performance: Deep traversals with many starting concepts may take longer
  • Default relationships: If not specified, uses [“Is a”, “Subsumes”, “Mapped from”]