Skip to main content
GET
https://api.omophub.com
/
v1
/
search
/
similar
/
{conceptId}
curl -X GET "https://api.omophub.com/v1/search/similar/44054006?vocabulary_ids=SNOMED,ICD10CM&similarity_threshold=0.8&max_results=10&include_scores=true&include_explanations=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": {
    "source_concept": {
      "concept_id": 44054006,
      "concept_name": "Type 2 diabetes mellitus",
      "concept_code": "44054006",
      "vocabulary_id": "SNOMED",
      "domain_id": "Condition",
      "concept_class_id": "Clinical Finding",
      "standard_concept": "S"
    },
    "similar_concepts": [
      {
        "concept_id": 201826,
        "concept_name": "Type 2 diabetes mellitus without complications",
        "concept_code": "E11.9",
        "vocabulary_id": "ICD10CM",
        "domain_id": "Condition",
        "concept_class_id": "4-char nonbill code",
        "similarity_score": 0.92,
        "explanation": "High similarity - more specific variant of the same condition",
        "standard_concept": null,
        "synonyms": ["Type II diabetes mellitus uncomplicated"]
      },
      {
        "concept_id": 443729,
        "concept_name": "Diabetes mellitus type 2 with hyperglycemia",
        "concept_code": "443729",
        "vocabulary_id": "SNOMED",
        "domain_id": "Condition",
        "concept_class_id": "Clinical Finding",
        "similarity_score": 0.89,
        "explanation": "High similarity - related complication of the same condition",
        "standard_concept": "S",
        "synonyms": ["Type 2 DM with elevated glucose"]
      },
      {
        "concept_id": 432367,
        "concept_name": "Diabetes mellitus type 2 with diabetic nephropathy",
        "concept_code": "E11.21",
        "vocabulary_id": "ICD10CM",
        "domain_id": "Condition",
        "concept_class_id": "5-char billing code",
        "similarity_score": 0.86,
        "explanation": "High similarity - complication of the same condition",
        "standard_concept": null,
        "synonyms": ["Type 2 DM with kidney disease"]
      }
    ],
    "search_metadata": {
      "source_concept_id": 44054006,
      "algorithm_used": "hybrid",
      "similarity_threshold": 0.8,
      "total_candidates": 125000,
      "results_returned": 3,
      "processing_time_ms": 187
    }
  }
}

​
Overview

This endpoint finds medical concepts that are semantically similar to a specific concept identified by its OMOP concept ID. It uses the same advanced machine learning algorithms as the POST version but optimized for concept-to-concept similarity matching, making it ideal for discovering related concepts when you have a specific starting point.

​
Path Parameters

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

​
Query Parameters

​
vocabulary_ids
string
Target vocabularies to search within (comma-separated)
Examples: SNOMED, SNOMED,ICD10CM, RXNORM,NDC
​
domain_ids
string
Clinical domains to focus the similarity search (comma-separated)
Examples: Condition,Procedure, Drug,Device
​
concept_class_ids
string
Concept classes to include in similarity search (comma-separated)
Examples: Clinical Finding,Procedure, Ingredient,Brand Name
​
similarity_threshold
number
default:"0.7"
Minimum similarity score threshold (0.0 to 1.0)
Higher values = More strict similarity matching
​
max_results
integer
default:"20"
Maximum number of similar concepts to return
​
include_scores
boolean
default:"true"
Include similarity scores in the response
​
include_explanations
boolean
default:"false"
Include explanations for why concepts are considered similar
​
standard_concept
string
Filter to standard concepts only
Options: S (standard), C (classification), NULL (non-standard)
​
include_invalid
boolean
default:"false"
Include invalid/deprecated concepts in similarity search
​
algorithm
string
default:"hybrid"
Similarity algorithm to use
Options: semantic (embedding-based), lexical (text-based), hybrid (combined)
​
exclude_self
boolean
default:"true"
Exclude the source concept from results

​
Response

​
success
boolean
Indicates if the request was successful
​
error
object
Error information (present only on error responses)
​
data
object
Contains the similar concepts search results
curl -X GET "https://api.omophub.com/v1/search/similar/44054006?vocabulary_ids=SNOMED,ICD10CM&similarity_threshold=0.8&max_results=10&include_scores=true&include_explanations=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": {
    "source_concept": {
      "concept_id": 44054006,
      "concept_name": "Type 2 diabetes mellitus",
      "concept_code": "44054006",
      "vocabulary_id": "SNOMED",
      "domain_id": "Condition",
      "concept_class_id": "Clinical Finding",
      "standard_concept": "S"
    },
    "similar_concepts": [
      {
        "concept_id": 201826,
        "concept_name": "Type 2 diabetes mellitus without complications",
        "concept_code": "E11.9",
        "vocabulary_id": "ICD10CM",
        "domain_id": "Condition",
        "concept_class_id": "4-char nonbill code",
        "similarity_score": 0.92,
        "explanation": "High similarity - more specific variant of the same condition",
        "standard_concept": null,
        "synonyms": ["Type II diabetes mellitus uncomplicated"]
      },
      {
        "concept_id": 443729,
        "concept_name": "Diabetes mellitus type 2 with hyperglycemia",
        "concept_code": "443729",
        "vocabulary_id": "SNOMED",
        "domain_id": "Condition",
        "concept_class_id": "Clinical Finding",
        "similarity_score": 0.89,
        "explanation": "High similarity - related complication of the same condition",
        "standard_concept": "S",
        "synonyms": ["Type 2 DM with elevated glucose"]
      },
      {
        "concept_id": 432367,
        "concept_name": "Diabetes mellitus type 2 with diabetic nephropathy",
        "concept_code": "E11.21",
        "vocabulary_id": "ICD10CM",
        "domain_id": "Condition",
        "concept_class_id": "5-char billing code",
        "similarity_score": 0.86,
        "explanation": "High similarity - complication of the same condition",
        "standard_concept": null,
        "synonyms": ["Type 2 DM with kidney disease"]
      }
    ],
    "search_metadata": {
      "source_concept_id": 44054006,
      "algorithm_used": "hybrid",
      "similarity_threshold": 0.8,
      "total_candidates": 125000,
      "results_returned": 3,
      "processing_time_ms": 187
    }
  }
}

​
Usage Examples

​
Basic Similarity by ID

Find concepts similar to Type 2 Diabetes (concept ID 44054006): 
GET /v1/search/similar/44054006?max_results=5&similarity_threshold=0.7

​
Cross-Vocabulary Similarity

Find similar concepts across multiple vocabularies: 
GET /v1/search/similar/1308216?vocabulary_ids=SNOMED,ICD10CM,LOINC&domain_ids=Condition,Measurement&include_explanations=true
Find similar pharmaceutical concepts: 
GET /v1/search/similar/1503297?vocabulary_ids=RXNORM&domain_ids=Drug&concept_class_ids=Ingredient,Clinical Drug&similarity_threshold=0.8

​
High-Precision Similarity

Get only highly similar concepts with detailed scoring: 
GET /v1/search/similar/443390?similarity_threshold=0.9&max_results=10&include_scores=true&algorithm=semantic

​
Performance Notes

  • Concept-to-concept similarity is typically faster than query-based similarity
  • Hybrid algorithm provides best balance of accuracy and performance
  • Semantic algorithm is most accurate but computationally intensive
  • Caching is applied for frequently requested concept similarities