Traverse Relationships

curl -X POST "https://api.omophub.com/v1/concepts/relationships/traverse" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start_concepts": [201826, 4182210],
    "traversal_rules": {
      "relationship_types": ["Is a", "Maps to"],
      "direction": "both",
      "max_depth": 4,
      "vocabulary_filters": {
        "allowed_vocabularies": ["SNOMED", "ICD10CM"]
      },
      "concept_filters": {
        "domain_ids": ["Condition"],
        "standard_concepts_only": true
      }
    }
  }'

{
  "success": true,
  "data": {
    "traversal_results": [
      {
        "start_concept_id": 201826,
        "start_concept_name": "Type 2 diabetes mellitus",
        "found_concepts": [
          {
            "concept_id": 73211009,
            "concept_name": "Diabetes mellitus",
            "vocabulary_id": "SNOMED",
            "domain_id": "Condition",
            "concept_class_id": "Clinical Finding",
            "standard_concept": "S",
            "concept_code": "73211009",
            "depth_from_start": 1,
            "relationship_chain": [
              {
                "relationship_type": "Is a",
                "from_concept_id": 201826,
                "to_concept_id": 73211009,
                "direction": "outbound",
                "relationship_id": "rel_123456"
              }
            ]
          },
          {
            "concept_id": 443767,
            "concept_name": "Type 2 diabetes mellitus with complications",
            "vocabulary_id": "SNOMED",
            "domain_id": "Condition",
            "concept_class_id": "Clinical Finding",
            "standard_concept": "S",
            "concept_code": "443767",
            "depth_from_start": 2,
            "relationship_chain": [
              {
                "relationship_type": "Subsumes",
                "from_concept_id": 201826,
                "to_concept_id": 443767,
                "direction": "inbound",
                "relationship_id": "rel_789012"
              }
            ]
          },
          {
            "concept_id": 435216,
            "concept_name": "Type 2 diabetes mellitus",
            "vocabulary_id": "ICD10CM",
            "domain_id": "Condition",
            "concept_class_id": "ICD10 code",
            "standard_concept": "S",
            "concept_code": "E11",
            "depth_from_start": 1,
            "relationship_chain": [
              {
                "relationship_type": "Maps to",
                "from_concept_id": 201826,
                "to_concept_id": 435216,
                "direction": "outbound",
                "relationship_id": "rel_345678"
              }
            ]
          }
        ],
        "paths": [
          {
            "target_concept_id": 73211009,
            "path_length": 1,
            "path_concepts": [201826, 73211009],
            "path_relationships": [
              {
                "relationship_type": "Is a",
                "relationship_id": "is_a_rel",
                "direction": "outbound"
              }
            ],
            "is_shortest_path": true
          },
          {
            "target_concept_id": 435216,
            "path_length": 1,
            "path_concepts": [201826, 435216],
            "path_relationships": [
              {
                "relationship_type": "Maps to",
                "relationship_id": "maps_to_rel",
                "direction": "outbound"
              }
            ],
            "is_shortest_path": true
          }
        ],
        "statistics": {
          "total_concepts_found": 25,
          "max_depth_reached": 4,
          "relationship_types_used": ["Is a", "Maps to", "Subsumes"],
          "vocabularies_traversed": ["SNOMED", "ICD10CM"],
          "domains_found": ["Condition"],
          "truncated": false
        }
      }
    ],
    "global_statistics": {
      "total_start_concepts": 1,
      "total_unique_concepts_found": 25,
      "successful_traversals": 1,
      "failed_traversals": 0,
      "average_concepts_per_start": 25.0,
      "processing_time_ms": 456
    }
  },
  "meta": {
    "request_id": "req_traverse_123",
    "timestamp": "2024-12-22T10:00:00Z",
    "vocab_release": "2025.2"
  }
}

curl -X POST "https://api.omophub.com/v1/concepts/relationships/traverse" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start_concepts": [201826, 4182210],
    "traversal_rules": {
      "relationship_types": ["Is a", "Maps to"],
      "direction": "both",
      "max_depth": 4,
      "vocabulary_filters": {
        "allowed_vocabularies": ["SNOMED", "ICD10CM"]
      },
      "concept_filters": {
        "domain_ids": ["Condition"],
        "standard_concepts_only": true
      }
    }
  }'

{
  "success": true,
  "data": {
    "traversal_results": [
      {
        "start_concept_id": 201826,
        "start_concept_name": "Type 2 diabetes mellitus",
        "found_concepts": [
          {
            "concept_id": 73211009,
            "concept_name": "Diabetes mellitus",
            "vocabulary_id": "SNOMED",
            "domain_id": "Condition",
            "concept_class_id": "Clinical Finding",
            "standard_concept": "S",
            "concept_code": "73211009",
            "depth_from_start": 1,
            "relationship_chain": [
              {
                "relationship_type": "Is a",
                "from_concept_id": 201826,
                "to_concept_id": 73211009,
                "direction": "outbound",
                "relationship_id": "rel_123456"
              }
            ]
          },
          {
            "concept_id": 443767,
            "concept_name": "Type 2 diabetes mellitus with complications",
            "vocabulary_id": "SNOMED",
            "domain_id": "Condition",
            "concept_class_id": "Clinical Finding",
            "standard_concept": "S",
            "concept_code": "443767",
            "depth_from_start": 2,
            "relationship_chain": [
              {
                "relationship_type": "Subsumes",
                "from_concept_id": 201826,
                "to_concept_id": 443767,
                "direction": "inbound",
                "relationship_id": "rel_789012"
              }
            ]
          },
          {
            "concept_id": 435216,
            "concept_name": "Type 2 diabetes mellitus",
            "vocabulary_id": "ICD10CM",
            "domain_id": "Condition",
            "concept_class_id": "ICD10 code",
            "standard_concept": "S",
            "concept_code": "E11",
            "depth_from_start": 1,
            "relationship_chain": [
              {
                "relationship_type": "Maps to",
                "from_concept_id": 201826,
                "to_concept_id": 435216,
                "direction": "outbound",
                "relationship_id": "rel_345678"
              }
            ]
          }
        ],
        "paths": [
          {
            "target_concept_id": 73211009,
            "path_length": 1,
            "path_concepts": [201826, 73211009],
            "path_relationships": [
              {
                "relationship_type": "Is a",
                "relationship_id": "is_a_rel",
                "direction": "outbound"
              }
            ],
            "is_shortest_path": true
          },
          {
            "target_concept_id": 435216,
            "path_length": 1,
            "path_concepts": [201826, 435216],
            "path_relationships": [
              {
                "relationship_type": "Maps to",
                "relationship_id": "maps_to_rel",
                "direction": "outbound"
              }
            ],
            "is_shortest_path": true
          }
        ],
        "statistics": {
          "total_concepts_found": 25,
          "max_depth_reached": 4,
          "relationship_types_used": ["Is a", "Maps to", "Subsumes"],
          "vocabularies_traversed": ["SNOMED", "ICD10CM"],
          "domains_found": ["Condition"],
          "truncated": false
        }
      }
    ],
    "global_statistics": {
      "total_start_concepts": 1,
      "total_unique_concepts_found": 25,
      "successful_traversals": 1,
      "failed_traversals": 0,
      "average_concepts_per_start": 25.0,
      "processing_time_ms": 456
    }
  },
  "meta": {
    "request_id": "req_traverse_123",
    "timestamp": "2024-12-22T10:00:00Z",
    "vocab_release": "2025.2"
  }
}

Overview

This advanced endpoint allows you to traverse complex relationship networks across multiple concepts, following chains of relationships with sophisticated filtering and path-finding capabilities. Essential for advanced medical terminology analysis and complex queries.

Request Body

start_concepts

array

required

Array of starting concept IDs for traversal

traversal_rules

object

required

Rules defining how to traverse relationships

Show traversal_rules

relationship_types

array

Array of relationship types to follow (default: [“Is a”, “Maps to”])

direction

string

default:"both"

Traversal direction: “outbound”, “inbound”, or “both”

max_depth

integer

default:"5"

Maximum depth of traversal (1-10)

max_results_per_concept

integer

default:"100"

Maximum results per starting concept

vocabulary_filters

object

Vocabulary-based filtering

Show vocabulary_filters

allowed_vocabularies

array

Only traverse through these vocabularies

blocked_vocabularies

array

Never traverse through these vocabularies

target_vocabularies

array

Stop traversal when reaching these vocabularies

concept_filters

object

Concept-based filtering

Show concept_filters

domain_ids

array

Only include concepts from these domains

concept_classes

array

Only include concepts from these classes

standard_concepts_only

boolean

default:"false"

Only include standard concepts

exclude_invalid

boolean

default:"true"

Exclude invalid/deprecated concepts

path_options

object

Path-finding options

Show path_options

find_shortest_paths

boolean

default:"false"

Find shortest paths between start and target concepts

include_path_details

boolean

default:"false"

Include detailed path information in results

stop_at_first_match

boolean

default:"false"

Stop traversal when first matching concept is found

target_criteria

object

Optional criteria for target concepts

Show target_criteria

target_concept_ids

array

Specific concept IDs to find paths to

target_concept_names

array

Find concepts matching these names (partial match)

target_codes

array

Find concepts with these specific codes

Query Parameters

vocab_release

string

Specific vocabulary release version (e.g., “2024.1”)

Response

success

boolean

required

Indicates whether the request was successful

traversal_results

array

required

Results for each starting concept

Show traversal_results

start_concept_id

integer

The concept ID where traversal started

start_concept_name

string

Name of the starting concept

found_concepts

array

Array of concepts found during traversal

Show found_concepts

concept_id

integer

Found concept ID

concept_name

string

Found concept name

vocabulary_id

string

Found concept vocabulary

domain_id

string

Found concept domain

concept_class_id

string

Found concept class

standard_concept

string

Standard concept flag

concept_code

string

Found concept code

depth_from_start

integer

Depth level from starting concept

relationship_chain

array

Chain of relationships to reach this concept

Show Relationship Chain Item

relationship_type

string

Type/name of relationship (e.g., “Is a”, “Maps to”, “Subsumes”)

from_concept_id

integer

Origin concept ID in this relationship step

to_concept_id

integer

Destination concept ID in this relationship step

direction

string

Traversal direction for this step (“outbound”, “inbound”)

relationship_id

string

Unique identifier for this relationship instance

paths

array

Detailed path information (when include_path_details=true)

Show paths

target_concept_id

integer

Target concept at end of path

path_length

integer

Number of steps in path

path_concepts

array

Ordered array of concepts in path

path_relationships

array

Ordered array of relationship objects in path

Show path_relationships item

relationship_type

string

Type/name of relationship

relationship_id

string

Unique identifier for this relationship

direction

string

Traversal direction (“outbound” or “inbound”)

is_shortest_path

boolean

Whether this is a shortest path

statistics

object

Traversal statistics for this starting concept

Show statistics

total_concepts_found

integer

Total unique concepts found

max_depth_reached

integer

Maximum depth reached during traversal

relationship_types_used

array

Relationship types actually traversed

vocabularies_traversed

array

Vocabularies encountered

domains_found

array

Domains found in results

truncated

boolean

Whether results were truncated due to limits

global_statistics

object

required

Overall traversal statistics

Show global_statistics

total_start_concepts

integer

Number of starting concepts processed

total_unique_concepts_found

integer

Total unique concepts across all traversals

successful_traversals

integer

Number of successful traversals

failed_traversals

integer

Number of failed traversals

average_concepts_per_start

number

Average concepts found per starting concept

processing_time_ms

integer

Total processing time

meta

object

required

Request metadata and response information

Show meta

correlation_id

string

Unique request correlation identifier

api_version

string

API version used for this request

curl -X POST "https://api.omophub.com/v1/concepts/relationships/traverse" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start_concepts": [201826, 4182210],
    "traversal_rules": {
      "relationship_types": ["Is a", "Maps to"],
      "direction": "both",
      "max_depth": 4,
      "vocabulary_filters": {
        "allowed_vocabularies": ["SNOMED", "ICD10CM"]
      },
      "concept_filters": {
        "domain_ids": ["Condition"],
        "standard_concepts_only": true
      }
    }
  }'

{
  "success": true,
  "data": {
    "traversal_results": [
      {
        "start_concept_id": 201826,
        "start_concept_name": "Type 2 diabetes mellitus",
        "found_concepts": [
          {
            "concept_id": 73211009,
            "concept_name": "Diabetes mellitus",
            "vocabulary_id": "SNOMED",
            "domain_id": "Condition",
            "concept_class_id": "Clinical Finding",
            "standard_concept": "S",
            "concept_code": "73211009",
            "depth_from_start": 1,
            "relationship_chain": [
              {
                "relationship_type": "Is a",
                "from_concept_id": 201826,
                "to_concept_id": 73211009,
                "direction": "outbound",
                "relationship_id": "rel_123456"
              }
            ]
          },
          {
            "concept_id": 443767,
            "concept_name": "Type 2 diabetes mellitus with complications",
            "vocabulary_id": "SNOMED",
            "domain_id": "Condition",
            "concept_class_id": "Clinical Finding",
            "standard_concept": "S",
            "concept_code": "443767",
            "depth_from_start": 2,
            "relationship_chain": [
              {
                "relationship_type": "Subsumes",
                "from_concept_id": 201826,
                "to_concept_id": 443767,
                "direction": "inbound",
                "relationship_id": "rel_789012"
              }
            ]
          },
          {
            "concept_id": 435216,
            "concept_name": "Type 2 diabetes mellitus",
            "vocabulary_id": "ICD10CM",
            "domain_id": "Condition",
            "concept_class_id": "ICD10 code",
            "standard_concept": "S",
            "concept_code": "E11",
            "depth_from_start": 1,
            "relationship_chain": [
              {
                "relationship_type": "Maps to",
                "from_concept_id": 201826,
                "to_concept_id": 435216,
                "direction": "outbound",
                "relationship_id": "rel_345678"
              }
            ]
          }
        ],
        "paths": [
          {
            "target_concept_id": 73211009,
            "path_length": 1,
            "path_concepts": [201826, 73211009],
            "path_relationships": [
              {
                "relationship_type": "Is a",
                "relationship_id": "is_a_rel",
                "direction": "outbound"
              }
            ],
            "is_shortest_path": true
          },
          {
            "target_concept_id": 435216,
            "path_length": 1,
            "path_concepts": [201826, 435216],
            "path_relationships": [
              {
                "relationship_type": "Maps to",
                "relationship_id": "maps_to_rel",
                "direction": "outbound"
              }
            ],
            "is_shortest_path": true
          }
        ],
        "statistics": {
          "total_concepts_found": 25,
          "max_depth_reached": 4,
          "relationship_types_used": ["Is a", "Maps to", "Subsumes"],
          "vocabularies_traversed": ["SNOMED", "ICD10CM"],
          "domains_found": ["Condition"],
          "truncated": false
        }
      }
    ],
    "global_statistics": {
      "total_start_concepts": 1,
      "total_unique_concepts_found": 25,
      "successful_traversals": 1,
      "failed_traversals": 0,
      "average_concepts_per_start": 25.0,
      "processing_time_ms": 456
    }
  },
  "meta": {
    "request_id": "req_traverse_123",
    "timestamp": "2024-12-22T10:00:00Z",
    "vocab_release": "2025.2"
  }
}

Usage Examples

Basic Relationship Traversal

Simple traversal with default settings:

{
  "start_concepts": [201826],
  "traversal_rules": {
    "relationship_types": ["Is a", "Maps to"],
    "max_depth": 3
  }
}

Cross-Vocabulary Mapping

Find mappings between vocabularies:

{
  "start_concepts": [201826],
  "traversal_rules": {
    "relationship_types": ["Maps to"],
    "vocabulary_filters": {
      "target_vocabularies": ["ICD10CM", "ICD9CM"]
    }
  }
}

Path Finding

Find specific paths between concepts:

{
  "start_concepts": [201826],
  "target_criteria": {
    "target_concept_ids": [73211009, 4182210]
  },
  "traversal_rules": {
    "path_options": {
      "find_shortest_paths": true,
      "include_path_details": true
    }
  }
}

Important Notes

Complexity limits: Maximum 10 starting concepts and depth 10 to prevent performance issues
Result limits: Use max_results_per_concept to control response size
Performance: Complex traversals may take several seconds
Memory usage: Deep traversals with many concepts can be memory-intensive
Path finding: Enable path details only when needed as it increases processing time

Batch Relationship Queries - Simpler bulk relationship queries
Get Concept Relationships - Single concept relationships
Get Concept Hierarchy - Hierarchical relationships only

Get Relationship Options Batch Relationship Queries

⌘I

API Reference

Concepts

Concept Hierarchy

Search

Search (Coming Soon)

Relationships

Domains & Classifications

Mappings

Vocabularies

Overview

Request Body

Query Parameters

Response

Usage Examples

Basic Relationship Traversal

Cross-Vocabulary Mapping

Path Finding

Important Notes

API Reference

Concepts

Concept Hierarchy

Search

Search (Coming Soon)

Relationships

Domains & Classifications

Mappings

Vocabularies

​Overview

​Request Body

​Query Parameters

​Response

​Usage Examples

​Basic Relationship Traversal

​Cross-Vocabulary Mapping

​Path Finding

​Important Notes

​Related Endpoints

Overview

Request Body

Query Parameters

Response

Usage Examples

Basic Relationship Traversal

Cross-Vocabulary Mapping

Path Finding

Important Notes

Related Endpoints