Skip to main content
POST
/
v1
/
concepts
/
search
/
similar
curl -X POST "https://api.omophub.com/v1/concepts/search/similar" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "concept_id": 201826,
    "page_size": 10
  }'

{
  "concepts": [
    {
      "concept_id": 443238,
      "concept_name": "Diabetic retinopathy",
      "concept_code": "4855003",
      "vocabulary_id": "SNOMED",
      "domain_id": "Condition",
      "concept_class_id": "Clinical Finding",
      "standard_concept": "S",
      "similarity_score": 0.89
    },
    {
      "concept_id": 192279,
      "concept_name": "Diabetic nephropathy",
      "concept_code": "127013003",
      "vocabulary_id": "SNOMED",
      "domain_id": "Condition",
      "concept_class_id": "Clinical Finding",
      "standard_concept": "S",
      "similarity_score": 0.87
    },
    {
      "concept_id": 376065,
      "concept_name": "Diabetic neuropathy",
      "concept_code": "230572002",
      "vocabulary_id": "SNOMED",
      "domain_id": "Condition",
      "concept_class_id": "Clinical Finding",
      "standard_concept": "S",
      "similarity_score": 0.85
    }
  ],
  "meta": {
    "source_concept_id": 201826,
    "total_results": 3,
    "similarity_model": "default",
    "vocab_release": "2025.2"
  }
}

​
Overview

This endpoint finds medical concepts that are semantically similar to a given concept or query. It uses embedding models to understand the meaning of medical terms and find related concepts, even when they don’t share common words. This is useful for discovering related diagnoses, treatments, or expanding search results beyond exact text matches.

​
Request Body

​
concept_id
integer
Find concepts similar to this concept ID
​
concept_name
string
Find concepts similar to this concept name (max 255 characters)
​
query
string
Natural language query to find similar concepts (max 500 characters)
AI-powered semantic search
​
context
string
Additional context to refine similarity matching (max 500 characters)
​
embedding_model
string
Embedding model to use for similarity calculation (max 50 characters)
​
similarity_threshold
number
Minimum similarity score for results (0.0-1.0). This is the canonical parameter.
Example: 0.7 returns only concepts with 70%+ similarity
​
min_similarity
number
deprecated
Deprecated: Use similarity_threshold instead. This parameter is retained for backward compatibility.
If both similarity_threshold and min_similarity are provided, similarity_threshold takes precedence.
​
page_size
integer
default:"20"
Number of results to return (1-100)
​
vocabularies
array
Filter results to specific vocabularies
Example: ["SNOMED", "ICD10CM"]
​
vocab_release
string
Specific vocabulary release version (defaults to latest)
At least one of concept_id, concept_name, or query must be provided.

​
Response

​
concepts
array
Array of similar concepts with similarity scores
​
meta
object
Request metadata including vocabulary release version
curl -X POST "https://api.omophub.com/v1/concepts/search/similar" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "concept_id": 201826,
    "page_size": 10
  }'

{
  "concepts": [
    {
      "concept_id": 443238,
      "concept_name": "Diabetic retinopathy",
      "concept_code": "4855003",
      "vocabulary_id": "SNOMED",
      "domain_id": "Condition",
      "concept_class_id": "Clinical Finding",
      "standard_concept": "S",
      "similarity_score": 0.89
    },
    {
      "concept_id": 192279,
      "concept_name": "Diabetic nephropathy",
      "concept_code": "127013003",
      "vocabulary_id": "SNOMED",
      "domain_id": "Condition",
      "concept_class_id": "Clinical Finding",
      "standard_concept": "S",
      "similarity_score": 0.87
    },
    {
      "concept_id": 376065,
      "concept_name": "Diabetic neuropathy",
      "concept_code": "230572002",
      "vocabulary_id": "SNOMED",
      "domain_id": "Condition",
      "concept_class_id": "Clinical Finding",
      "standard_concept": "S",
      "similarity_score": 0.85
    }
  ],
  "meta": {
    "source_concept_id": 201826,
    "total_results": 3,
    "similarity_model": "default",
    "vocab_release": "2025.2"
  }
}

​
Usage Examples

​
Find Similar by Concept ID

Find concepts similar to a known concept: 
curl -X POST "https://api.omophub.com/v1/concepts/search/similar" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "concept_id": 201826,
    "page_size": 20
  }'

​
Find Similar by Concept Name

Find concepts similar to a concept name: 
curl -X POST "https://api.omophub.com/v1/concepts/search/similar" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "concept_name": "Type 2 diabetes mellitus",
    "similarity_threshold": 0.7,
    "page_size": 15
  }'

​
Natural Language Query

Use natural language to find similar concepts: 
curl -X POST "https://api.omophub.com/v1/concepts/search/similar" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "complications related to high blood sugar",
    "vocabularies": ["SNOMED"],
    "page_size": 10
  }'

​
With Context

Add context to improve similarity matching: 
curl -X POST "https://api.omophub.com/v1/concepts/search/similar" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "concept_name": "chest pain",
    "context": "cardiac emergency department presentation",
    "similarity_threshold": 0.6,
    "page_size": 20
  }'

​
Filter by Vocabulary

Limit results to specific vocabularies: 
curl -X POST "https://api.omophub.com/v1/concepts/search/similar" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "concept_id": 201826,
    "vocabularies": ["SNOMED", "ICD10CM"],
    "page_size": 25
  }'

​
Alternative GET Endpoint

You can also use the GET endpoint to find similar concepts by concept ID: 
curl -X GET "https://api.omophub.com/v1/search/similar/201826" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Use Cases

​
Phenotype Development

Find related conditions when building phenotype definitions:
  • Start with a seed diagnosis
  • Discover related conditions, complications, and manifestations
  • Build comprehensive phenotype concept sets

​
Drug Safety Research

Identify related adverse events:
  • Find similar adverse drug reactions
  • Discover related symptoms and conditions
  • Support pharmacovigilance workflows

​
Clinical Decision Support

Expand differential diagnoses:
  • Find conditions similar to presenting symptoms
  • Discover related diagnoses to consider
  • Support diagnostic workflows