Skip to main content
POST
https://api.omophub.com
/
v1
/
search
/
similar
curl -X POST "https://api.omophub.com/v1/search/similar" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "type 2 diabetes mellitus",
    "vocabulary_ids": ["SNOMED", "ICD10CM"],
    "domain_ids": ["Condition"],
    "similarity_threshold": 0.8,
    "max_results": 10,
    "include_scores": true,
    "include_explanations": true,
    "standard_concept": "S"
  }'

{
  "success": true,
  "data": {
    "similar_concepts": [
      {
        "concept_id": 44054006,
        "concept_name": "Type 2 diabetes mellitus",
        "concept_code": "44054006",
        "vocabulary_id": "SNOMED",
        "domain_id": "Condition",
        "concept_class_id": "Clinical Finding",
        "similarity_score": 1.0,
        "explanation": "Exact match - same clinical concept",
        "standard_concept": "S",
        "synonyms": ["Non-insulin dependent diabetes mellitus", "Adult-onset diabetes"]
      },
      {
        "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": "S",
        "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"]
      }
    ],
    "search_metadata": {
      "original_query": "type 2 diabetes mellitus",
      "algorithm_used": "hybrid",
      "similarity_threshold": 0.8,
      "total_candidates": 125000,
      "results_returned": 3,
      "processing_time_ms": 245
    }
  }
}

​
Overview

This endpoint identifies medical concepts that are semantically similar to a provided query or set of criteria. It leverages advanced machine learning models trained on medical terminology to discover related concepts that may not share exact keywords but are clinically relevant and contextually similar.

​
Request Body

​
query
string
required
Primary search query or concept description to find similar concepts for
​
vocabulary_ids
array
Target vocabularies to search within (array of strings)
Examples: ["SNOMED", "ICD10CM"], ["RXNORM", "NDC"]
​
domain_ids
array
Clinical domains to focus the similarity search (array of strings)
Examples: ["Condition", "Procedure"], ["Drug", "Device"]
​
concept_class_ids
array
Concept classes to include in similarity search (array of strings)
Examples: ["Clinical Finding", "Procedure"], ["Ingredient", "Brand Name"]
​
similarity_threshold
number
default:"0.7"
Minimum similarity score threshold (0.1 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), N (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)

​
Response

​
success
boolean
Indicates if the request was successful
​
data
object
Contains the similar concepts search results
curl -X POST "https://api.omophub.com/v1/search/similar" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "type 2 diabetes mellitus",
    "vocabulary_ids": ["SNOMED", "ICD10CM"],
    "domain_ids": ["Condition"],
    "similarity_threshold": 0.8,
    "max_results": 10,
    "include_scores": true,
    "include_explanations": true,
    "standard_concept": "S"
  }'

{
  "success": true,
  "data": {
    "similar_concepts": [
      {
        "concept_id": 44054006,
        "concept_name": "Type 2 diabetes mellitus",
        "concept_code": "44054006",
        "vocabulary_id": "SNOMED",
        "domain_id": "Condition",
        "concept_class_id": "Clinical Finding",
        "similarity_score": 1.0,
        "explanation": "Exact match - same clinical concept",
        "standard_concept": "S",
        "synonyms": ["Non-insulin dependent diabetes mellitus", "Adult-onset diabetes"]
      },
      {
        "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": "S",
        "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"]
      }
    ],
    "search_metadata": {
      "original_query": "type 2 diabetes mellitus",
      "algorithm_used": "hybrid",
      "similarity_threshold": 0.8,
      "total_candidates": 125000,
      "results_returned": 3,
      "processing_time_ms": 245
    }
  }
}

​
Usage Examples

Find concepts similar to a medical condition: 
{
  "query": "hypertension",
  "max_results": 5,
  "similarity_threshold": 0.7
}

​
Cross-Vocabulary Similarity

Find similar concepts across multiple vocabularies: 
{
  "query": "myocardial infarction",
  "vocabulary_ids": ["SNOMED", "ICD10CM", "ICD9CM"],
  "domain_ids": ["Condition"],
  "similarity_threshold": 0.8,
  "include_explanations": true
}

​
Pharmacological Similarity

Find similar drug concepts with detailed scoring: 
{
  "query": "metformin hydrochloride",
  "vocabulary_ids": ["RXNORM"],
  "domain_ids": ["Drug"],
  "concept_class_ids": ["Ingredient", "Clinical Drug"],
  "similarity_threshold": 0.75,
  "include_scores": true,
  "algorithm": "semantic"
}