> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omophub.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Traverse Relationships

> Traverse OMOP relationship networks across vocabularies to discover connected concepts - RxNorm ingredients, SNOMED parents, ICD mappings, and more.

## 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

<ParamField body="concept_ids" type="array" required>
  Array of starting concept IDs for traversal (1-50 concepts)
</ParamField>

<ParamField body="traversal_params" type="object">
  Optional parameters for controlling the traversal

  <Expandable title="traversal_params">
    <ParamField body="max_depth" type="integer" default="3">
      Maximum traversal depth (1-5)
    </ParamField>

    <ParamField body="relationship_types" type="array">
      Array of relationship types to follow (default: \["Is a", "Subsumes", "Mapped from"])
    </ParamField>

    <ParamField body="vocabulary_ids" type="array">
      Limit traversal to specific vocabularies
    </ParamField>

    <ParamField body="include_invalid" type="boolean" default="true">
      Include invalid/deprecated concepts in traversal
    </ParamField>

    <ParamField body="include_paths" type="boolean" default="false">
      Include detailed path information in response
    </ParamField>

    <ParamField body="breadth_first" type="boolean" default="false">
      Use breadth-first traversal (default is depth-first)
    </ParamField>

    <ParamField body="min_score" type="number">
      Minimum relevance score filter (0.0-1.0)
    </ParamField>

    <ParamField body="page_size" type="integer" default="100">
      Maximum number of results to return
    </ParamField>
  </Expandable>
</ParamField>

## Query Parameters

<ParamField query="vocab_release" type="string">
  Specific vocabulary release version (e.g., "2025.1")
</ParamField>

## Response

<ResponseField name="success" type="boolean" required>
  Indicates whether the request was successful
</ResponseField>

<ResponseField name="data" type="object" required>
  Response data containing traversal results

  <Expandable title="data">
    <ResponseField name="starting_concepts" type="array">
      Array of concept IDs that were used as starting points
    </ResponseField>

    <ResponseField name="discovered_concepts" type="array">
      Array of concepts discovered during traversal

      <Expandable title="discovered_concepts">
        <ResponseField name="concept_id" type="integer">Discovered concept ID</ResponseField>
        <ResponseField name="concept_name" type="string">Discovered concept name</ResponseField>
        <ResponseField name="vocabulary_id" type="string">Concept vocabulary</ResponseField>
        <ResponseField name="distance" type="integer">Distance from starting concept</ResponseField>
        <ResponseField name="path" type="array">Array of concept names in the path</ResponseField>
        <ResponseField name="relationship_path" type="array">Array of relationship types used</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="relationship_paths" type="array">
      Detailed path information (when include\_paths=true)

      <Expandable title="relationship_paths">
        <ResponseField name="source_concept_id" type="integer">Source concept ID</ResponseField>
        <ResponseField name="target_concept_id" type="integer">Target concept ID</ResponseField>
        <ResponseField name="path" type="array">Path details</ResponseField>
        <ResponseField name="distance" type="integer">Path distance</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="traversal_summary" type="object">
      Summary statistics for the traversal

      <Expandable title="traversal_summary">
        <ResponseField name="total_discovered" type="integer">Total concepts discovered</ResponseField>
        <ResponseField name="max_distance_reached" type="integer">Maximum distance reached</ResponseField>
        <ResponseField name="relationship_types_used" type="array">Relationship types traversed</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object" required>
  Response metadata

  <Expandable title="meta">
    <ResponseField name="request_id" type="string">Unique request identifier</ResponseField>
    <ResponseField name="timestamp" type="string">ISO 8601 timestamp</ResponseField>
    <ResponseField name="vocab_release" type="string">Vocabulary release version used</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  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
      }
    }'
  ```

  ```python Python theme={null}
  import requests

  def traverse_relationships(concept_ids, traversal_params=None):
      url = "https://api.omophub.com/v1/concepts/relationships/traverse"
      headers = {
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      }

      data = {"concept_ids": concept_ids}
      if traversal_params:
          data["traversal_params"] = traversal_params

      response = requests.post(url, json=data, headers=headers)
      return response.json()

  # Example: Traverse from Type 2 diabetes
  result = traverse_relationships(
      concept_ids=[201826],
      traversal_params={
          "relationship_types": ["Is a", "Subsumes", "Maps to"],
          "max_depth": 3,
          "include_paths": True
      }
  )

  data = result['data']
  print(f"Starting concepts: {data['starting_concepts']}")
  print(f"Discovered {data['traversal_summary']['total_discovered']} concepts")
  print(f"Max distance: {data['traversal_summary']['max_distance_reached']}")

  for concept in data['discovered_concepts'][:5]:
      print(f"  - {concept['concept_name']} (distance: {concept['distance']})")
  ```

  ```javascript JavaScript theme={null}
  const traverseRelationships = async (conceptIds, traversalParams = {}) => {
    const response = await fetch('https://api.omophub.com/v1/concepts/relationships/traverse', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        concept_ids: conceptIds,
        traversal_params: traversalParams
      })
    });

    return response.json();
  };

  // Example usage
  const result = await traverseRelationships([201826], {
    relationship_types: ['Is a', 'Maps to'],
    max_depth: 3
  });

  const data = result.data;
  console.log(`Discovered ${data.traversal_summary.total_discovered} concepts`);

  data.discovered_concepts.slice(0, 5).forEach(concept => {
    console.log(`- ${concept.concept_name} (distance: ${concept.distance})`);
  });
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</ResponseExample>

## Usage Examples

### Basic Traversal

Simple traversal with default settings:

```json theme={null}
{
  "concept_ids": [201826],
  "traversal_params": {
    "max_depth": 2
  }
}
```

### With Path Details

Include detailed path information:

```json theme={null}
{
  "concept_ids": [201826],
  "traversal_params": {
    "relationship_types": ["Is a", "Maps to"],
    "max_depth": 3,
    "include_paths": true
  }
}
```

### Multiple Starting Concepts

Traverse from multiple concepts:

```json theme={null}
{
  "concept_ids": [201826, 4182210, 313217],
  "traversal_params": {
    "max_depth": 2,
    "page_size": 50
  }
}
```

### Vocabulary-Filtered Traversal

Limit to specific vocabularies:

```json theme={null}
{
  "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"]

## Related Endpoints

* [Batch Hierarchy Queries](/api-reference/concepts/batch-hierarchy-queries) - Batch hierarchy queries
* [Get Concept Relationships](/api-reference/concepts/get-concept-relationships) - Single concept relationships
* [Get Concept Hierarchy](/api-reference/concepts/get-concept-hierarchy) - Hierarchical relationships only