Skip to main content
GET
https://api.omophub.com
/
v1
/
concepts
/
{conceptId}
/
related
curl -X GET "https://api.omophub.com/v1/concepts/201826/related?min_relatedness_score=0.4&max_results=20" \
  -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"
    },
    "related_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",
        "overall_relatedness_score": 0.92,
        "relatedness_details": {
          "hierarchical_score": 0.95,
          "semantic_score": 0.88,
          "co_occurrence_score": 0.91,
          "mapping_score": 0.85,
          "primary_relationship_type": "Is a",
          "relationship_path_length": 1,
          "explanation": "Direct parent concept in SNOMED hierarchy with strong semantic similarity"
        }
      },
      {
        "concept_id": 443735,
        "concept_name": "Type 2 diabetes mellitus without complications",
        "vocabulary_id": "SNOMED",
        "domain_id": "Condition",
        "concept_class_id": "Clinical Finding",
        "standard_concept": "S",
        "concept_code": "443735",
        "overall_relatedness_score": 0.89,
        "relatedness_details": {
          "hierarchical_score": 0.87,
          "semantic_score": 0.94,
          "co_occurrence_score": 0.86,
          "mapping_score": 0.82,
          "primary_relationship_type": "Subsumes",
          "relationship_path_length": 1,
          "explanation": "Specific subtype with very high semantic similarity"
        }
      },
      {
        "concept_id": 4048098,
        "concept_name": "Diabetic complication",
        "vocabulary_id": "SNOMED",
        "domain_id": "Condition",
        "concept_class_id": "Clinical Finding",
        "standard_concept": "S",
        "concept_code": "4048098",
        "overall_relatedness_score": 0.76,
        "relatedness_details": {
          "hierarchical_score": 0.65,
          "semantic_score": 0.82,
          "co_occurrence_score": 0.89,
          "mapping_score": 0.68,
          "primary_relationship_type": "Associated with",
          "relationship_path_length": 2,
          "explanation": "Frequently co-occurring concept representing complications of diabetes"
        }
      },
      {
        "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",
        "overall_relatedness_score": 0.94,
        "relatedness_details": {
          "hierarchical_score": 0.72,
          "semantic_score": 0.98,
          "co_occurrence_score": 0.85,
          "mapping_score": 0.99,
          "primary_relationship_type": "Maps to",
          "relationship_path_length": 1,
          "explanation": "Exact cross-vocabulary mapping with identical semantic meaning"
        }
      }
    ],
    "analysis_summary": {
      "total_candidates_evaluated": 1247,
      "concepts_above_threshold": 28,
      "average_relatedness_score": 0.65,
      "max_relatedness_score": 0.94,
      "relatedness_types_used": ["hierarchical", "semantic", "co_occurrence", "mapping"],
      "vocabulary_distribution": {
        "SNOMED": 18,
        "ICD10CM": 7,
        "ICD9CM": 3
      },
      "domain_distribution": {
        "Condition": 22,
        "Observation": 4,
        "Drug": 2
      }
    }
  },
  "meta": {
    "request_id": "req_related_123",
    "timestamp": "2024-12-22T10:00:00Z",
    "vocab_release": "2025.2"
  }
}

​
Overview

This endpoint finds concepts that are conceptually related to a given concept through various relationship types, semantic similarity, and co-occurrence patterns. It’s designed for discovering relevant concepts that may not be directly connected through standard hierarchical relationships.

​
Path Parameters

​
conceptId
integer
required
The unique OMOP concept ID to find related concepts for

​
Query Parameters

​
relatedness_types
string
Types of relatedness to include. Multiple values are comma-separated.
Options: hierarchical, semantic, co_occurrence, mapping (default: all)
Note: Providing any unknown value will result in a 400 Bad Request response.
​
vocabulary_ids
string
Comma-separated list of vocabulary IDs to filter results
​
domain_ids
string
Comma-separated list of domain IDs to filter results
​
min_relatedness_score
number
default:"0.3"
Minimum relatedness score (0.0-1.0) to include in results
​
max_results
integer
default:"50"
Maximum number of related concepts to return
​
include_scores
boolean
default:"true"
Include detailed relatedness scores and explanations. Boolean values must be serialized as string values “true” or “false” when sent over the wire.
​
standard_concepts_only
boolean
default:"false"
Only return standard concepts. Boolean values must be serialized as string values “true” or “false” when sent over the wire.
​
vocab_release
string
Specific vocabulary release version (e.g., “2024.1”)

​
Response

​
success
boolean
required
Indicates if the request was successful
​
concept
object
required
The source concept being analyzed
​
related_concepts
array
required
Array of related concepts ordered by relatedness score
​
analysis_summary
object
required
Summary of the relatedness analysis
​
meta
object
required
Response metadata and API information
curl -X GET "https://api.omophub.com/v1/concepts/201826/related?min_relatedness_score=0.4&max_results=20" \
  -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"
    },
    "related_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",
        "overall_relatedness_score": 0.92,
        "relatedness_details": {
          "hierarchical_score": 0.95,
          "semantic_score": 0.88,
          "co_occurrence_score": 0.91,
          "mapping_score": 0.85,
          "primary_relationship_type": "Is a",
          "relationship_path_length": 1,
          "explanation": "Direct parent concept in SNOMED hierarchy with strong semantic similarity"
        }
      },
      {
        "concept_id": 443735,
        "concept_name": "Type 2 diabetes mellitus without complications",
        "vocabulary_id": "SNOMED",
        "domain_id": "Condition",
        "concept_class_id": "Clinical Finding",
        "standard_concept": "S",
        "concept_code": "443735",
        "overall_relatedness_score": 0.89,
        "relatedness_details": {
          "hierarchical_score": 0.87,
          "semantic_score": 0.94,
          "co_occurrence_score": 0.86,
          "mapping_score": 0.82,
          "primary_relationship_type": "Subsumes",
          "relationship_path_length": 1,
          "explanation": "Specific subtype with very high semantic similarity"
        }
      },
      {
        "concept_id": 4048098,
        "concept_name": "Diabetic complication",
        "vocabulary_id": "SNOMED",
        "domain_id": "Condition",
        "concept_class_id": "Clinical Finding",
        "standard_concept": "S",
        "concept_code": "4048098",
        "overall_relatedness_score": 0.76,
        "relatedness_details": {
          "hierarchical_score": 0.65,
          "semantic_score": 0.82,
          "co_occurrence_score": 0.89,
          "mapping_score": 0.68,
          "primary_relationship_type": "Associated with",
          "relationship_path_length": 2,
          "explanation": "Frequently co-occurring concept representing complications of diabetes"
        }
      },
      {
        "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",
        "overall_relatedness_score": 0.94,
        "relatedness_details": {
          "hierarchical_score": 0.72,
          "semantic_score": 0.98,
          "co_occurrence_score": 0.85,
          "mapping_score": 0.99,
          "primary_relationship_type": "Maps to",
          "relationship_path_length": 1,
          "explanation": "Exact cross-vocabulary mapping with identical semantic meaning"
        }
      }
    ],
    "analysis_summary": {
      "total_candidates_evaluated": 1247,
      "concepts_above_threshold": 28,
      "average_relatedness_score": 0.65,
      "max_relatedness_score": 0.94,
      "relatedness_types_used": ["hierarchical", "semantic", "co_occurrence", "mapping"],
      "vocabulary_distribution": {
        "SNOMED": 18,
        "ICD10CM": 7,
        "ICD9CM": 3
      },
      "domain_distribution": {
        "Condition": 22,
        "Observation": 4,
        "Drug": 2
      }
    }
  },
  "meta": {
    "request_id": "req_related_123",
    "timestamp": "2024-12-22T10:00:00Z",
    "vocab_release": "2025.2"
  }
}

​
Usage Examples

Find general related concepts: 
curl -X GET "https://api.omophub.com/v1/concepts/201826/related" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
High-Confidence Relationships

Get only highly related concepts: 
curl -X GET "https://api.omophub.com/v1/concepts/201826/related?min_relatedness_score=0.7&max_results=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Domain-Specific Relations

Find related concepts within specific domains: 
curl -X GET "https://api.omophub.com/v1/concepts/201826/related?domain_ids=Condition,Observation&vocabulary_ids=SNOMED" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Semantic Similarity Focus

Focus on semantic relatedness: 
curl -X GET "https://api.omophub.com/v1/concepts/201826/related?relatedness_types=semantic,co_occurrence" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Application Integration

Use in recommendation systems: 
async function getConceptRecommendations(conceptId, userContext) {
  const params = new URLSearchParams({
    min_relatedness_score: userContext.precision_level || '0.4',
    max_results: userContext.max_suggestions || '20',
    vocabulary_ids: userContext.preferred_vocabularies?.join(',') || '',
    standard_concepts_only: userContext.standard_only || 'false'
  });

  const response = await fetch(`/v1/concepts/${conceptId}/related?${params}`);
  const data = await response.json();
  
  return data.related_concepts.map(concept => ({
    id: concept.concept_id,
    name: concept.concept_name,
    vocabulary: concept.vocabulary_id,
    score: concept.overall_relatedness_score,
    explanation: concept.relatedness_details?.explanation
  }));
}

​
Important Notes

  • Scoring algorithm - Combines multiple relatedness signals for comprehensive results
  • Performance - Analysis involves complex calculations and may take longer than simple queries
  • Score interpretation - Scores above 0.7 indicate strong relatedness, 0.4-0.7 moderate, below 0.4 weak
  • Vocabulary coverage - Results quality depends on vocabulary completeness and relationships
  • Context sensitive - Relatedness can vary based on clinical context and use case