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

string

required

Primary search query or concept description to find similar concepts for

array

Target vocabularies to search within (array of strings)
Examples: ["SNOMED", "ICD10CM"], ["RXNORM", "NDC"]

array

Clinical domains to focus the similarity search (array of strings)
Examples: ["Condition", "Procedure"], ["Drug", "Device"]

array

Concept classes to include in similarity search (array of strings)
Examples: ["Clinical Finding", "Procedure"], ["Ingredient", "Brand Name"]

number

default:"0.7"

Minimum similarity score threshold (0 to 1.0)
Higher values = More strict similarity matching

integer

default:"20"

Number of similar concepts to return per page

integer

default:"1"

Page number (1-based indexing)

boolean

default:"true"

Include similarity scores in the response

boolean

default:"false"

Include explanations for why concepts are considered similar

string

Filter to standard concepts only
Options: S (standard), C (classification), N (non-standard)

boolean

default:"true"

Include invalid/deprecated concepts in similarity search

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

boolean

Indicates if the request was successful

object

Contains the similar concepts search results

Show data

array

Array of concepts similar to the query

Show similar_concepts

integer

OMOP concept ID

string

Primary concept name

string

Vocabulary-specific concept code

string

Source vocabulary identifier

string

Clinical domain classification

string

Concept class identifier

number

Similarity score between 0.0 and 1.0

string

Reason for similarity match (if requested)

string

Standard concept flag (S, C, or N)

array

Alternative names for the concept

object

Information about the similarity search

Show search_metadata

string

The original search query provided

string

Similarity algorithm applied (semantic, lexical, or hybrid)

number

Minimum similarity threshold applied

integer

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

integer

Number of similar concepts returned

integer

Search processing time in milliseconds

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

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