Skip to main content
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,
    "page_size": 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
    }
  },
  "meta": {
    "request_id": "req_sim_abc123",
    "timestamp": "2024-01-15T10:30:00Z",
    "vocab_release": "2025.1",
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total_items": 3,
      "total_pages": 1,
      "has_next": false,
      "has_previous": false
    },
    "search": {
      "query": "type 2 diabetes mellitus",
      "total_results": 3,
      "filters_applied": {
        "similarity_type": "concept"
      }
    }
  }
}

​
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 to 1.0)
Higher values = More strict similarity matching
​
page_size
integer
default:"20"
Number of similar concepts to return per page
​
page
integer
default:"1"
Page number (1-based indexing)
​
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:"true"
Include invalid/deprecated concepts in similarity search
​
algorithm
string
default:"hybrid"
Similarity algorithm to use
Options:
  • semantic - Neural embedding-based similarity. Best for finding conceptually similar terms (e.g., “heart attack” → “Myocardial infarction”).
  • lexical - Text-based Jaccard word similarity. Good for fuzzy text matching and typo tolerance.
  • hybrid (default) - Combines word and character similarity for balanced matching.

​
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,
    "page_size": 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
    }
  },
  "meta": {
    "request_id": "req_sim_abc123",
    "timestamp": "2024-01-15T10:30:00Z",
    "vocab_release": "2025.1",
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total_items": 3,
      "total_pages": 1,
      "has_next": false,
      "has_previous": false
    },
    "search": {
      "query": "type 2 diabetes mellitus",
      "total_results": 3,
      "filters_applied": {
        "similarity_type": "concept"
      }
    }
  }
}

​
Usage Examples

Find concepts similar to a medical condition: 
{
  "query": "hypertension",
  "page_size": 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"
}

​
Semantic Search for Clinical Terms

Use neural embeddings to find conceptually similar terms (even when words don’t match): 
{
  "query": "heart attack",
  "vocabulary_ids": ["SNOMED"],
  "domain_ids": ["Condition"],
  "similarity_threshold": 0.5,
  "algorithm": "semantic",
  "page_size": 10
}
This will find “Myocardial infarction” and related concepts even though the words “heart” and “attack” don’t appear in the medical term.

​
Algorithm Comparison

Featuresemanticlexicalhybrid (default)
ModelNeural embeddingsJaccard word similarityWord + character similarity
Best forConceptual similarityFuzzy text matchingBalanced matching
”heart attack” → “MI”ExcellentPoor (word mismatch)Poor
Typo toleranceModerateGoodGood
Total countsApproximateExactExact
SpeedFast (15-50ms)Fast (50-200ms)Fast (50-200ms)
RequirementsEmbedding serviceNoneNone
Semantic Algorithm Pagination: When using algorithm: "semantic", the total_candidates and pagination counts are approximate values optimized for performance. Use has_next in the response to reliably determine if more results exist.