Skip to main content
GET
/
v1
/
concepts
/
{concept_id}
/
relationships
curl -G "https://api.omophub.com/v1/concepts/201826/relationships" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  --data-urlencode "relationship_types=Is a,Part of" \
  --data-urlencode "include_synonyms=true" \
  --data-urlencode "group_by_type=true"

{
  "success": true,
  "data": {
    "concept": {
    "concept_id": 201826,
    "concept_name": "Type 2 diabetes mellitus",
    "vocabulary_id": "SNOMED",
    "domain_id": "Condition",
    "concept_class_id": "Clinical Finding"
  },
  "relationships_by_type": {
    "Is a": [
      {
        "relationship_id": "rel_1",
        "relationship_type": "Is a",
        "reverse_relationship_type": "Subsumes",
        "direction": "outgoing",
        "related_concept": {
          "concept_id": 201826,
          "concept_name": "Diabetes mellitus",
          "concept_code": "73211009",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "valid_start_date": "1970-01-01T00:00:00Z",
          "valid_end_date": "2099-12-31T00:00:00Z"
        },
        "semantic_distance": 0.1,
        "relationship_strength": 0.95,
        "valid_start_date": "1970-01-01T00:00:00Z",
        "valid_end_date": "2099-12-31T00:00:00Z"
      }
    ],
    "Maps to": [
      {
        "relationship_id": "rel_2",
        "relationship_type": "Maps to",
        "reverse_relationship_type": "Mapped from",
        "direction": "outgoing",
        "related_concept": {
          "concept_id": 45757292,
          "concept_name": "Type 2 diabetes mellitus",
          "concept_code": "E11",
          "vocabulary_id": "ICD10CM",
          "domain_id": "Condition",
          "concept_class_id": "3-char billing code",
          "standard_concept": "S",
          "valid_start_date": "2016-10-01T00:00:00Z",
          "valid_end_date": "2099-12-31T00:00:00Z"
        },
        "semantic_distance": 0.05,
        "relationship_strength": 0.98,
        "valid_start_date": "2016-10-01T00:00:00Z",
        "valid_end_date": "2099-12-31T00:00:00Z"
      }
    ],
    "Associated with": [
      {
        "relationship_id": "rel_3",
        "relationship_type": "Associated with",
        "reverse_relationship_type": "Associated with",
        "direction": "outgoing",
        "related_concept": {
          "concept_id": 201820,
          "concept_name": "Diabetes mellitus due to insulin receptor antibodies",
          "concept_code": "190368000",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "valid_start_date": "2002-01-31T00:00:00Z",
          "valid_end_date": "2099-12-31T00:00:00Z"
        },
        "semantic_distance": 0.3,
        "relationship_strength": 0.7,
        "valid_start_date": "2002-01-31T00:00:00Z",
        "valid_end_date": "2099-12-31T00:00:00Z"
      }
    ]
  },
  "relationship_summary": {
    "total_relationships": 47,
    "unique_relationship_types": 8,
    "outgoing_relationships": 32,
    "incoming_relationships": 15,
    "relationship_type_counts": {
      "Is a": 1,
      "Maps to": 12,
      "Associated with": 8,
      "Has associated morphology": 5,
      "Finding site": 3,
      "Subsumes": 18
    },
    "vocabulary_distribution": {
      "SNOMED": 28,
      "ICD10CM": 12,
      "ICD10": 7
    },
    "domain_distribution": {
      "Condition": 38,
      "Procedure": 6,
      "Observation": 3
    },
    "most_common_relationships": [
      "Subsumes",
      "Maps to", 
      "Associated with",
      "Has associated morphology"
    ]
    }
  },
  "meta": {
    "pagination": {
      "page": 1,
      "page_size": 100,
      "total_items": 47,
      "total_pages": 1,
      "has_next": false,
      "has_previous": false
    },
    "request_id": "req_relationship_concept_78901234",
    "timestamp": "2024-12-22T10:30:00Z",
    "vocab_release": "2025.2"
  }
}
This endpoint provides comprehensive relationship information for a concept, showing how it connects to other concepts through various relationship types such as “Is a”, “Part of”, “Has ingredient”, and many others in medical vocabularies.

​
Path Parameters

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

​
Query Parameters

​
relationship_types
string
Comma-separated list of specific relationship types to retrieve
Example: Is a,Part of,Has ingredient,Maps to
​
direction
string
default:"both"
Direction of relationships to retrieve
Options: incoming, outgoing, both
​
vocabulary_ids
string
Filter relationships to specific vocabularies
Example: SNOMED,ICD10CM,RxNorm
​
domain_ids
string
Filter related concepts to specific domains
Example: Condition,Drug,Procedure
​
standard_only
boolean
default:"true"
Only return relationships to standard concepts
​
include_deprecated
boolean
default:"false"
Include relationships to deprecated/invalid concepts
​
include_synonyms
boolean
default:"false"
Include synonym information for related concepts
​
include_distance
boolean
default:"false"
Include semantic distance scores for relationships
​
group_by_type
boolean
default:"false"
Group relationships by their type in the response
​
include_reverse
boolean
default:"true"
Include reverse relationship names for clarity
​
page_size
integer
default:"100"
Number of relationships to return per page (max 1000)
​
page
integer
default:"1"
Page number for pagination (1-based)

​
Response

​
concept
object
The source concept for which relationships were retrieved
​
relationships
array
Array of relationship objects (when group_by_type=false)
​
relationships_by_type
object
Relationships grouped by type (when group_by_type=true)
​
relationship_summary
object
Summary statistics about the relationships
​
meta
object
Response metadata and pagination information
curl -G "https://api.omophub.com/v1/concepts/201826/relationships" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  --data-urlencode "relationship_types=Is a,Part of" \
  --data-urlencode "include_synonyms=true" \
  --data-urlencode "group_by_type=true"

{
  "success": true,
  "data": {
    "concept": {
    "concept_id": 201826,
    "concept_name": "Type 2 diabetes mellitus",
    "vocabulary_id": "SNOMED",
    "domain_id": "Condition",
    "concept_class_id": "Clinical Finding"
  },
  "relationships_by_type": {
    "Is a": [
      {
        "relationship_id": "rel_1",
        "relationship_type": "Is a",
        "reverse_relationship_type": "Subsumes",
        "direction": "outgoing",
        "related_concept": {
          "concept_id": 201826,
          "concept_name": "Diabetes mellitus",
          "concept_code": "73211009",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "valid_start_date": "1970-01-01T00:00:00Z",
          "valid_end_date": "2099-12-31T00:00:00Z"
        },
        "semantic_distance": 0.1,
        "relationship_strength": 0.95,
        "valid_start_date": "1970-01-01T00:00:00Z",
        "valid_end_date": "2099-12-31T00:00:00Z"
      }
    ],
    "Maps to": [
      {
        "relationship_id": "rel_2",
        "relationship_type": "Maps to",
        "reverse_relationship_type": "Mapped from",
        "direction": "outgoing",
        "related_concept": {
          "concept_id": 45757292,
          "concept_name": "Type 2 diabetes mellitus",
          "concept_code": "E11",
          "vocabulary_id": "ICD10CM",
          "domain_id": "Condition",
          "concept_class_id": "3-char billing code",
          "standard_concept": "S",
          "valid_start_date": "2016-10-01T00:00:00Z",
          "valid_end_date": "2099-12-31T00:00:00Z"
        },
        "semantic_distance": 0.05,
        "relationship_strength": 0.98,
        "valid_start_date": "2016-10-01T00:00:00Z",
        "valid_end_date": "2099-12-31T00:00:00Z"
      }
    ],
    "Associated with": [
      {
        "relationship_id": "rel_3",
        "relationship_type": "Associated with",
        "reverse_relationship_type": "Associated with",
        "direction": "outgoing",
        "related_concept": {
          "concept_id": 201820,
          "concept_name": "Diabetes mellitus due to insulin receptor antibodies",
          "concept_code": "190368000",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "valid_start_date": "2002-01-31T00:00:00Z",
          "valid_end_date": "2099-12-31T00:00:00Z"
        },
        "semantic_distance": 0.3,
        "relationship_strength": 0.7,
        "valid_start_date": "2002-01-31T00:00:00Z",
        "valid_end_date": "2099-12-31T00:00:00Z"
      }
    ]
  },
  "relationship_summary": {
    "total_relationships": 47,
    "unique_relationship_types": 8,
    "outgoing_relationships": 32,
    "incoming_relationships": 15,
    "relationship_type_counts": {
      "Is a": 1,
      "Maps to": 12,
      "Associated with": 8,
      "Has associated morphology": 5,
      "Finding site": 3,
      "Subsumes": 18
    },
    "vocabulary_distribution": {
      "SNOMED": 28,
      "ICD10CM": 12,
      "ICD10": 7
    },
    "domain_distribution": {
      "Condition": 38,
      "Procedure": 6,
      "Observation": 3
    },
    "most_common_relationships": [
      "Subsumes",
      "Maps to", 
      "Associated with",
      "Has associated morphology"
    ]
    }
  },
  "meta": {
    "pagination": {
      "page": 1,
      "page_size": 100,
      "total_items": 47,
      "total_pages": 1,
      "has_next": false,
      "has_previous": false
    },
    "request_id": "req_relationship_concept_78901234",
    "timestamp": "2024-12-22T10:30:00Z",
    "vocab_release": "2025.2"
  }
}

​
Usage Examples

​
All Relationships

Get all relationships for a concept: 
const allRelationships = await fetch('/v1/concepts/201826/relationships', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json'
  }
});

​
Hierarchical Relationships Only

Retrieve only “Is a” and “Subsumes” relationships: 
const params = new URLSearchParams({ relationship_types: 'Is a,Subsumes' });
const hierarchical = await fetch(`/v1/concepts/201826/relationships?${params}`, {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json'
  }
});

​
Cross-Vocabulary Mappings

Find mappings to other vocabularies: 
const params = new URLSearchParams({
  relationship_types: 'Maps to',
  vocabulary_ids: 'ICD10CM,ICD10'
});
const mappings = await fetch(`/v1/concepts/201826/relationships?${params}`, {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json'
  }
});

​
Outgoing Relationships Only

Get only relationships going out from the concept: 
const params = new URLSearchParams({
  direction: 'outgoing',
  include_distance: 'true'
});
const outgoing = await fetch(`/v1/concepts/201826/relationships?${params}`, {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json'
  }
});

​
Grouped by Type

Organize relationships by their type: 
const params = new URLSearchParams({
  group_by_type: 'true',
  include_synonyms: 'true'
});
const grouped = await fetch(`/v1/concepts/201826/relationships?${params}`, {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json'
  }
});

​
Notes

  • Relationship direction is crucial: “outgoing” means the source concept is the subject of the relationship
  • Semantic distance provides a measure of how closely related two concepts are (lower = closer)
  • Standard concepts are prioritized for relationship targets unless explicitly disabled
  • Some relationships are bidirectional (e.g., “Associated with”) while others are unidirectional
  • Cross-vocabulary relationships often use “Maps to” relationship types
  • Large concepts may have hundreds of relationships - use pagination and filtering appropriately
  • Relationship strength indicates the confidence or importance of the connection