Skip to main content

​
Overview

The OMOPHub API provides multiple endpoints for finding medical concepts that are semantically similar to a given query or concept. These endpoints use advanced machine learning algorithms trained on medical terminology to discover clinically relevant relationships.

​
Available Similarity Search Endpoints

​
POST /v1/search/similar

Recommended for flexible similarity searches
  • Find similar concepts using natural language queries
  • Supports complex filtering with request body parameters
  • Ideal for exploratory medical concept discovery
View POST Search Similar Documentation →

​
GET /v1/search/similar/

Recommended for concept-to-concept similarity
  • Find concepts similar to a specific OMOP concept ID
  • Optimized for performance with URL path parameters
  • Ideal when you have a specific starting concept
View GET Search Similar by ID Documentation →

​
Key Features

​
Advanced ML Algorithms

  • Semantic similarity using medical embeddings
  • Lexical similarity for text-based matching
  • Hybrid approach combining both methods

​
Healthcare-Specific Optimizations

  • Medical domain expertise built into models
  • Clinical vocabulary understanding (SNOMED, ICD-10, RxNorm)
  • Healthcare relationship context awareness

​
Flexible Filtering Options

  • Filter by vocabularies, domains, and concept classes
  • Adjustable similarity thresholds
  • Standard vs non-standard concept filtering

​
Usage Examples

​
Finding Drug Alternatives

Use similarity search to find alternative medications: 
curl -X POST "$BASE_URL/v1/search/similar" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "metformin",
    "domain_ids": ["Drug"],
    "similarity_threshold": 0.7
  }'
Find conditions related to a specific diagnosis: 
GET /v1/search/similar/44054006?domain_ids=Condition&max_results=10

​
Cross-Vocabulary Mapping

Discover equivalent concepts across medical vocabularies: 
curl -X POST "$BASE_URL/v1/search/similar" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "type 2 diabetes",
    "vocabulary_ids": ["SNOMED", "ICD10CM", "ICD9CM"],
    "explanations": true
  }'

​
Best Practices

​
Choosing the Right Endpoint

  • Use POST /search/similar for:
    • Natural language queries
    • Complex filtering requirements
    • Exploratory searches
  • Use GET /search/similar/ for:
    • Known concept IDs
    • High-performance applications
    • Programmatic integrations

​
Optimization Tips

  • Set appropriate similarity thresholds (0.7-0.9 for most use cases)
  • Limit results with max_results parameter
  • Use domain filtering to focus on relevant clinical areas
  • Enable explanations for understanding similarity reasoning
⌘I