Search Similar Concepts

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"
  }'

import { OMOPHub } from '@omophub/omophub-node';

const client = new OMOPHub();
const { data } = await client.search.similar({
  query: 'type 2 diabetes mellitus',
  vocabularyIds: ['SNOMED', 'ICD10CM'],
  domainIds: ['Condition'],
  similarityThreshold: 0.8,
  pageSize: 10,
  includeScores: true,
  includeExplanations: true,
  standardConcept: 'S',
});

import requests

url = "https://api.omophub.com/v1/search/similar"
payload = {
    "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"
}

response = requests.post(
    url,
    json=payload,
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
data = response.json()

{
  "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"
      }
    }
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_THRESHOLD",
    "message": "Similarity threshold must be between 0 and 1.0",
    "details": {
      "provided_threshold": 1.5,
      "valid_range": "0-1.0"
    }
  }
}

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"
  }'

import { OMOPHub } from '@omophub/omophub-node';

const client = new OMOPHub();
const { data } = await client.search.similar({
  query: 'type 2 diabetes mellitus',
  vocabularyIds: ['SNOMED', 'ICD10CM'],
  domainIds: ['Condition'],
  similarityThreshold: 0.8,
  pageSize: 10,
  includeScores: true,
  includeExplanations: true,
  standardConcept: 'S',
});

import requests

url = "https://api.omophub.com/v1/search/similar"
payload = {
    "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"
}

response = requests.post(
    url,
    json=payload,
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
data = response.json()

{
  "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"
      }
    }
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_THRESHOLD",
    "message": "Similarity threshold must be between 0 and 1.0",
    "details": {
      "provided_threshold": 1.5,
      "valid_range": "0-1.0"
    }
  }
}

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

Show data

similar_concepts

array

Array of concepts similar to the query

Show similar_concepts

concept_id

integer

OMOP concept ID

concept_name

string

Primary concept name

concept_code

string

Vocabulary-specific concept code

vocabulary_id

string

Source vocabulary identifier

domain_id

string

Clinical domain classification

concept_class_id

string

Concept class identifier

similarity_score

number

Similarity score between 0.0 and 1.0

explanation

string

Reason for similarity match (if requested)

standard_concept

string

Standard concept flag (S, C, or N)

synonyms

array

Alternative names for the concept

search_metadata

object

Information about the similarity search

Show search_metadata

original_query

string

The original search query provided

algorithm_used

string

Similarity algorithm applied (semantic, lexical, or hybrid)

similarity_threshold

number

Minimum similarity threshold applied

total_candidates

integer

Approximate count of concepts evaluated for similarity. For semantic algorithm, this is a lower bound based on sampled results.

results_returned

integer

Number of similar concepts returned

processing_time_ms

integer

Search processing time in milliseconds

embedding_latency_ms

integer

Time spent on embedding generation (only present when algorithm_used is semantic)

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"
  }'

import { OMOPHub } from '@omophub/omophub-node';

const client = new OMOPHub();
const { data } = await client.search.similar({
  query: 'type 2 diabetes mellitus',
  vocabularyIds: ['SNOMED', 'ICD10CM'],
  domainIds: ['Condition'],
  similarityThreshold: 0.8,
  pageSize: 10,
  includeScores: true,
  includeExplanations: true,
  standardConcept: 'S',
});

import requests

url = "https://api.omophub.com/v1/search/similar"
payload = {
    "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"
}

response = requests.post(
    url,
    json=payload,
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
data = response.json()

{
  "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"
      }
    }
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_THRESHOLD",
    "message": "Similarity threshold must be between 0 and 1.0",
    "details": {
      "provided_threshold": 1.5,
      "valid_range": "0-1.0"
    }
  }
}

Usage Examples

Basic Similarity Search

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

Feature	`semantic`	`lexical`	`hybrid` (default)
Model	Neural embeddings	Jaccard word similarity	Word + character similarity
Best for	Conceptual similarity	Fuzzy text matching	Balanced matching
”heart attack” → “MI”	Excellent	Poor (word mismatch)	Poor
Typo tolerance	Moderate	Good	Good
Total counts	Approximate	Exact	Exact
Speed	Fast (15-50ms)	Fast (50-200ms)	Fast (50-200ms)
Requirements	Embedding service	None	None

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.

GET Search Similar by ID - Get similar concepts for a specific concept ID
Semantic Search - Dedicated semantic search endpoint using neural embeddings
Advanced Search - Advanced search with multiple criteria

Bulk Semantic Search Get Similar Concepts by ID

API Reference

Search

Concepts

Concept Hierarchy

Mappings

FHIR Resolver

Relationships

Domains & Classifications

Vocabularies

Overview

Request Body

Response

Usage Examples

Basic Similarity Search

Cross-Vocabulary Similarity

Pharmacological Similarity

Semantic Search for Clinical Terms

Algorithm Comparison

​Overview

​Request Body

​Response

​Usage Examples

​Basic Similarity Search

​Cross-Vocabulary Similarity

​Pharmacological Similarity

​Semantic Search for Clinical Terms

​Algorithm Comparison

​Related Endpoints

Overview

Request Body

Response

Usage Examples

Basic Similarity Search

Cross-Vocabulary Similarity

Pharmacological Similarity

Semantic Search for Clinical Terms

Algorithm Comparison

Related Endpoints