Skip to main content
GET
https://api.omophub.com
/
v1
/
concepts
/
{conceptId}
/
relationships
/
options
curl -X GET "https://api.omophub.com/v1/concepts/201826/relationships/options?include_counts=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": {
    "concept": {
      "concept_id": 201826,
      "concept_name": "Type 2 diabetes mellitus",
      "vocabulary_id": "SNOMED",
      "domain_id": "Condition",
      "concept_class_id": "Clinical Finding"
    },
    "relationship_options": {
      "outbound": [
        {
          "relationship_id": "Maps to",
          "relationship_name": "Maps to",
          "relationship_concept_id": 44818790,
          "reverse_relationship": "Mapped from",
          "is_hierarchical": false,
          "defines_ancestry": false,
          "count": 3,
          "target_vocabularies": ["SNOMED", "ICD10CM"],
          "target_domains": ["Condition"],
          "example_targets": [
            {
              "concept_id": 44054006,
              "concept_name": "Diabetes mellitus type 2 (disorder)"
            },
            {
              "concept_id": 443735,
              "concept_name": "Type 2 diabetes mellitus without complications"
            }
          ]
        },
        {
          "relationship_id": "Is a",
          "relationship_name": "Is a",
          "relationship_concept_id": 44818821,
          "reverse_relationship": "Subsumes",
          "is_hierarchical": true,
          "defines_ancestry": true,
          "count": 2,
          "target_vocabularies": ["SNOMED"],
          "target_domains": ["Condition"],
          "example_targets": [
            {
              "concept_id": 73211009,
              "concept_name": "Diabetes mellitus"
            }
          ]
        }
      ],
      "inbound": [
        {
          "relationship_id": "Subsumes",
          "relationship_name": "Subsumes",
          "relationship_concept_id": 44818723,
          "reverse_relationship": "Is a",
          "is_hierarchical": true,
          "defines_ancestry": true,
          "count": 15,
          "source_vocabularies": ["SNOMED"],
          "source_domains": ["Condition"],
          "example_sources": [
            {
              "concept_id": 443767,
              "concept_name": "Type 2 diabetes mellitus with complications"
            },
            {
              "concept_id": 201254,
              "concept_name": "Type 2 diabetes mellitus with ketoacidosis"
            }
          ]
        }
      ]
    },
    "summary": {
      "total_outbound_types": 5,
      "total_inbound_types": 3,
      "total_unique_types": 7,
      "hierarchical_types": ["Is a", "Subsumes"],
      "mapping_types": ["Maps to", "Mapped from"],
      "most_common_types": ["Subsumes", "Maps to", "Is a"],
      "connected_vocabularies": ["SNOMED", "ICD10CM", "ICD9CM"]
    }
  },
  "meta": {
    "request_id": "req_relationship_options_123",
    "timestamp": "2024-12-22T10:00:00Z",
    "vocab_release": "2025.2"
  }
}

​
Overview

This endpoint returns all available relationship types that can be applied to or from a specific concept, along with metadata about relationship options. This is useful for building dynamic UI components and understanding what relationships are possible for a concept.

​
Path Parameters

​
conceptId
integer
required
The unique OMOP concept ID to get relationship options for

​
Query Parameters

​
direction
string
Filter by relationship direction: “outbound”, “inbound”, or “both” (default: “both”)
​
vocabulary_ids
string
Comma-separated list of vocabularies to filter relationship options
​
include_counts
boolean
default:"false"
Include count of relationships for each relationship type
​
include_invalid
boolean
default:"false"
Include invalid/deprecated relationship types
​
vocab_release
string
Specific vocabulary release version (e.g., “2024.1”)

​
Response

​
data
object
required
Response data containing relationship options
​
meta
object
required
Response metadata and API information
curl -X GET "https://api.omophub.com/v1/concepts/201826/relationships/options?include_counts=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": {
    "concept": {
      "concept_id": 201826,
      "concept_name": "Type 2 diabetes mellitus",
      "vocabulary_id": "SNOMED",
      "domain_id": "Condition",
      "concept_class_id": "Clinical Finding"
    },
    "relationship_options": {
      "outbound": [
        {
          "relationship_id": "Maps to",
          "relationship_name": "Maps to",
          "relationship_concept_id": 44818790,
          "reverse_relationship": "Mapped from",
          "is_hierarchical": false,
          "defines_ancestry": false,
          "count": 3,
          "target_vocabularies": ["SNOMED", "ICD10CM"],
          "target_domains": ["Condition"],
          "example_targets": [
            {
              "concept_id": 44054006,
              "concept_name": "Diabetes mellitus type 2 (disorder)"
            },
            {
              "concept_id": 443735,
              "concept_name": "Type 2 diabetes mellitus without complications"
            }
          ]
        },
        {
          "relationship_id": "Is a",
          "relationship_name": "Is a",
          "relationship_concept_id": 44818821,
          "reverse_relationship": "Subsumes",
          "is_hierarchical": true,
          "defines_ancestry": true,
          "count": 2,
          "target_vocabularies": ["SNOMED"],
          "target_domains": ["Condition"],
          "example_targets": [
            {
              "concept_id": 73211009,
              "concept_name": "Diabetes mellitus"
            }
          ]
        }
      ],
      "inbound": [
        {
          "relationship_id": "Subsumes",
          "relationship_name": "Subsumes",
          "relationship_concept_id": 44818723,
          "reverse_relationship": "Is a",
          "is_hierarchical": true,
          "defines_ancestry": true,
          "count": 15,
          "source_vocabularies": ["SNOMED"],
          "source_domains": ["Condition"],
          "example_sources": [
            {
              "concept_id": 443767,
              "concept_name": "Type 2 diabetes mellitus with complications"
            },
            {
              "concept_id": 201254,
              "concept_name": "Type 2 diabetes mellitus with ketoacidosis"
            }
          ]
        }
      ]
    },
    "summary": {
      "total_outbound_types": 5,
      "total_inbound_types": 3,
      "total_unique_types": 7,
      "hierarchical_types": ["Is a", "Subsumes"],
      "mapping_types": ["Maps to", "Mapped from"],
      "most_common_types": ["Subsumes", "Maps to", "Is a"],
      "connected_vocabularies": ["SNOMED", "ICD10CM", "ICD9CM"]
    }
  },
  "meta": {
    "request_id": "req_relationship_options_123",
    "timestamp": "2024-12-22T10:00:00Z",
    "vocab_release": "2025.2"
  }
}

​
Usage Examples

​
Basic Relationship Options

Get all available relationship types: 
curl -X GET "https://api.omophub.com/v1/concepts/201826/relationships/options" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Outbound Only with Counts

Get outbound relationship options with counts: 
curl -X GET "https://api.omophub.com/v1/concepts/201826/relationships/options?direction=outbound&include_counts=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Filtered by Vocabularies

Get relationship options for specific vocabularies: 
curl -X GET "https://api.omophub.com/v1/concepts/201826/relationships/options?vocabulary_ids=SNOMED,ICD10CM" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
UI Integration Example

Use in dropdown components: 
async function loadRelationshipOptions(conceptId) {
  const response = await fetch(`/v1/concepts/${conceptId}/relationships/options?direction=outbound`);
  const result = await response.json();
  const data = result.data;

  return data.relationship_options.outbound.map(rel => ({
    value: rel.relationship_id,
    label: rel.relationship_name,
    count: rel.count,
    isHierarchical: rel.is_hierarchical
  }));
}

// Use in UI
const options = await loadRelationshipOptions(201826);
const selectOptions = options.map(opt =>
  `<option value="${opt.value}">${opt.label} ${opt.count ? '(' + opt.count + ')' : ''}</option>`
);

​
Important Notes

  • Dynamic options - Available relationship types vary by concept and vocabulary
  • Hierarchical indicators - Use is_hierarchical and defines_ancestry flags for navigation
  • Performance - Including counts increases response time but provides valuable context
  • UI components - Perfect for building dynamic relationship selection interfaces
  • Reverse relationships - Each relationship type has a corresponding reverse relationship