Skip to main content
This feature is coming soon and is not yet available in the current API version.

​
Overview

This endpoint will provide semantic search capabilities that understand the meaning and context of queries rather than just matching text. It will use advanced natural language processing and machine learning models to find conceptually related medical terms, enabling more intuitive and comprehensive search experiences.

​
Query Parameters

​
query
string
required
Natural language query or medical description
​
vocabulary_ids
string | array[string]
Target vocabularies
GET examples: SNOMED, ICD10CM,LOINC, RXNORM,NDC
POST examples: ["SNOMED","ICD10CM"]
​
domains
string | array[string]
Filter results to specific domains
GET examples: Condition, Condition,Procedure, Drug,Device
POST examples: ["Condition","Procedure"]
​
concept_classes
string | array[string]
Filter to specific concept classes
GET examples: Clinical Finding, Disorder,Clinical Finding, Substance,Product
POST examples: ["Clinical Finding","Disorder"]
​
semantic_threshold
number
default:"0.6"
Minimum semantic similarity score (0.0-1.0, higher = more strict)
​
search_mode
string
default:"comprehensive"
Semantic search mode
Options: comprehensive, precise, exploratory, clinical, research
​
context_expansion
boolean
default:"true"
Expand search context using related medical concepts
​
include_synonyms
boolean
default:"true"
Include semantically similar synonyms
​
include_related_concepts
boolean
default:"true"
Include conceptually related terms
​
clinical_context
string
Clinical specialty context for search focus
Examples: cardiology, oncology, pediatrics, emergency_medicine
​
patient_context
string
Patient context for relevance scoring
Options: adult, pediatric, geriatric, acute_care, chronic_care
​
language_model
string
default:"medical_bert"
Language model for semantic understanding
Options: medical_bert, clinical_transformer, bio_gpt, hybrid
​
embedding_version
string
default:"v2.1"
Semantic embedding model version
​
boost_common_terms
boolean
default:"true"
Boost commonly used medical terms in results
​
standard_concept
string
Filter by standard concept status: S, N, C
​
include_invalid
boolean
default:"false"
Include invalid/deprecated concepts
​
temporal_context
string
Temporal context for medical concepts
Options: acute, chronic, historical, current, preventive
​
severity_context
string
Clinical severity context
Options: mild, moderate, severe, critical, any
​
explain_relevance
boolean
default:"false"
Include explanation of why concepts are relevant
​
sort_by
string
default:"semantic_score"
Sort order for results
Options: semantic_score, clinical_relevance, usage_frequency, alphabetical
​
page
integer
default:"1"
Page number for pagination
​
page_size
integer
default:"20"
Number of results per page (max 100)
​
vocab_release
string
Specific vocabulary release version (defaults to latest)

​
Response

​
success
boolean
Indicates if the request was successful
​
data
object
​
meta
object
curl -X GET "https://api.omophub.com/v1/search/semantic?query=chest%20pain%20after%20physical%20activity&vocabulary_ids=SNOMED,ICD10CM&semantic_threshold=0.7&clinical_context=cardiology&explain_relevance=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

​
POST Request for Sensitive Data

PHI Security Warning: Avoid sending protected health information (PHI) or sensitive patient data in URL query strings as they may be logged by servers, proxies, or browser history. Use POST requests with JSON bodies for sensitive queries. Consider API key rotation and ensure full URLs are not logged in your applications.
For sensitive queries containing potential PHI, use POST requests: 
curl -X POST "https://api.omophub.com/v1/search/semantic" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "patient reports chest pain with shortness of breath",
    "clinical_context": "cardiology", 
    "explain_relevance": true,
    "vocabulary_ids": ["SNOMED", "ICD10CM"],
    "semantic_threshold": 0.7,
    "page_size": 20
  }'

{
  "success": true,
  "data": {
    "query": "chest pain after physical activity",
    "query_analysis": {
      "detected_entities": [
        {
          "entity": "chest pain",
          "type": "symptom",
          "confidence": 0.95
        },
        {
          "entity": "physical activity",
          "type": "trigger",
          "confidence": 0.89
        }
      ],
      "query_intent": "diagnostic",
      "clinical_context": "cardiology",
      "semantic_concepts": [
        "chest discomfort",
        "exertional pain",
        "cardiac symptoms",
        "angina"
      ],
      "language_confidence": 0.92
    },
    "semantic_parameters": {
      "search_mode": "comprehensive",
      "semantic_threshold": 0.7,
      "language_model": "medical_bert",
      "embedding_version": "v2.1",
      "context_expansion": true
    },
    "search_statistics": {
      "total_candidates": 45672,
      "semantic_matches": 34,
      "context_expanded_matches": 12,
      "processing_time_ms": 2847,
      "model_inference_time_ms": 1234
    },
    "concepts": [
      {
        "concept_id": 194828000,
        "concept_name": "Angina pectoris",
        "concept_code": "194828000",
        "vocabulary_id": "SNOMED",
        "vocabulary_name": "Systematized Nomenclature of Medicine Clinical Terms",
        "domain_id": "Condition",
        "concept_class_id": "Clinical Finding",
        "standard_concept": "S",
        "semantic_score": 0.94,
        "clinical_relevance_score": 0.97,
        "semantic_details": {
          "match_type": "direct",
          "semantic_relationship": "synonymous",
          "confidence_level": "High",
          "matching_concepts": [
            "chest pain",
            "exertional"
          ],
          "semantic_distance": 0.06,
          "context_factors": [
            "cardiac context",
            "exertional trigger",
            "chest location"
          ]
        },
        "relevance_explanation": {
          "primary_reasons": [
            "Classic presentation of exertional chest pain",
            "Direct semantic match for cardiac chest pain",
            "Strong clinical relevance in cardiology context"
          ],
          "semantic_connections": [
            "chest pain → cardiac symptom",
            "physical activity → exertional trigger",
            "angina → chest pain syndrome"
          ],
          "clinical_context_match": "Perfect match for cardiology evaluation of exertional chest pain",
          "usage_context": "Primary diagnostic consideration for activity-related chest discomfort"
        },
        "related_concepts": [
          {
            "concept_id": 25106000,
            "concept_name": "Unstable angina",
            "relationship_type": "narrower",
            "semantic_score": 0.87
          },
          {
            "concept_id": 233819005,
            "concept_name": "Stable angina",
            "relationship_type": "narrower",
            "semantic_score": 0.91
          }
        ]
      },
      {
        "concept_id": 22298006,
        "concept_name": "Myocardial infarction",
        "concept_code": "22298006",
        "vocabulary_id": "SNOMED",
        "vocabulary_name": "Systematized Nomenclature of Medicine Clinical Terms",
        "domain_id": "Condition",
        "concept_class_id": "Clinical Finding",
        "standard_concept": "S",
        "semantic_score": 0.87,
        "clinical_relevance_score": 0.93,
        "semantic_details": {
          "match_type": "related",
          "semantic_relationship": "related",
          "confidence_level": "High",
          "matching_concepts": [
            "chest pain",
            "cardiac event"
          ],
          "semantic_distance": 0.13,
          "context_factors": [
            "cardiac context",
            "chest pain symptom",
            "serious cardiac condition"
          ]
        },
        "relevance_explanation": {
          "primary_reasons": [
            "Can present as exertional chest pain",
            "Critical differential diagnosis",
            "High clinical importance in chest pain evaluation"
          ],
          "semantic_connections": [
            "chest pain → cardiac symptom",
            "myocardial infarction → acute chest pain",
            "exertional trigger → cardiac stress"
          ],
          "clinical_context_match": "Important differential diagnosis for exertional chest pain",
          "usage_context": "Critical consideration in acute chest pain evaluation"
        },
        "related_concepts": [
          {
            "concept_id": 401314000,
            "concept_name": "Acute ST segment elevation myocardial infarction",
            "relationship_type": "narrower",
            "semantic_score": 0.83
          }
        ]
      },
      {
        "concept_id": 233910005,
        "concept_name": "Exercise-induced asthma",
        "concept_code": "233910005",
        "vocabulary_id": "SNOMED",
        "vocabulary_name": "Systematized Nomenclature of Medicine Clinical Terms",
        "domain_id": "Condition",
        "concept_class_id": "Clinical Finding",
        "standard_concept": "S",
        "semantic_score": 0.79,
        "clinical_relevance_score": 0.84,
        "semantic_details": {
          "match_type": "contextual",
          "semantic_relationship": "related",
          "confidence_level": "Medium",
          "matching_concepts": [
            "physical activity",
            "exercise-induced"
          ],
          "semantic_distance": 0.21,
          "context_factors": [
            "exertional trigger",
            "respiratory symptoms",
            "activity-related"
          ]
        },
        "relevance_explanation": {
          "primary_reasons": [
            "Exercise-induced condition matching activity trigger",
            "Can cause chest discomfort during activity",
            "Common differential for exertional symptoms"
          ],
          "semantic_connections": [
            "physical activity → exercise trigger",
            "chest symptoms → respiratory discomfort",
            "exertional → activity-induced"
          ],
          "clinical_context_match": "Relevant differential for activity-related chest symptoms",
          "usage_context": "Consider in patients with exertional chest discomfort and respiratory symptoms"
        },
        "related_concepts": [
          {
            "concept_id": 195967001,
            "concept_name": "Asthma",
            "relationship_type": "broader",
            "semantic_score": 0.76
          }
        ]
      }
    ],
    "semantic_clusters": [
      {
        "cluster_id": "cardiac_conditions",
        "cluster_theme": "Cardiac chest pain conditions",
        "concept_count": 18,
        "average_score": 0.89,
        "representative_concepts": [
          "Angina pectoris",
          "Myocardial infarction",
          "Coronary artery disease"
        ]
      },
      {
        "cluster_id": "exertional_conditions",
        "cluster_theme": "Exercise-induced medical conditions",
        "concept_count": 8,
        "average_score": 0.78,
        "representative_concepts": [
          "Exercise-induced asthma",
          "Exertional dyspnea",
          "Exercise intolerance"
        ]
      }
    ],
    "query_suggestions": {
      "similar_queries": [
        "exertional chest pain",
        "cardiac chest pain with activity",
        "chest discomfort during exercise",
        "activity-induced chest pain"
      ],
      "related_searches": [
        "angina pectoris",
        "exercise stress test",
        "cardiac evaluation",
        "chest pain differential diagnosis"
      ],
      "concept_expansions": [
        "exertional angina",
        "cardiac ischemia",
        "coronary artery disease",
        "chest pain syndrome"
      ],
      "clinical_alternatives": [
        "substernal chest pressure with exertion",
        "activity-related cardiac symptoms",
        "chest tightness during physical activity"
      ]
    }
  },
  "meta": {
    "request_id": "req_semantic_search_123",
    "timestamp": "2024-01-15T10:30:00Z",
    "model_version": "medical_bert_v2.1.0",
    "processing_mode": "comprehensive",
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total_items": 34,
      "total_pages": 2,
      "has_next": true,
      "has_previous": false
    },
    "vocab_release": "2025.2"
  }
}

​
Usage Examples

​
Natural Language Query

Search using natural language descriptions: 
curl -X GET "https://api.omophub.com/v1/search/semantic?query=patient%20has%20trouble%20sleeping%20and%20feels%20anxious&domains=Condition&search_mode=clinical" \
  -H "Authorization: Bearer YOUR_API_KEY"
Use clinical specialty context: 
curl -X GET "https://api.omophub.com/v1/search/semantic?query=irregular%20heartbeat&clinical_context=cardiology&context_expansion=true&explain_relevance=true" \
  -H "Authorization: Bearer YOUR_API_KEY"
Perform broad semantic exploration: 
curl -X GET "https://api.omophub.com/v1/search/semantic?query=chronic%20kidney%20disease%20complications&search_mode=exploratory&include_related_concepts=true&semantic_threshold=0.6" \
  -H "Authorization: Bearer YOUR_API_KEY"
Use strict semantic matching: 
curl -X GET "https://api.omophub.com/v1/search/semantic?query=acute%20myocardial%20infarction&search_mode=precise&semantic_threshold=0.8&vocabulary_ids=SNOMED" \
  -H "Authorization: Bearer YOUR_API_KEY"
Search with patient context: 
curl -X GET "https://api.omophub.com/v1/search/semantic?query=child%20with%20fever%20and%20rash&patient_context=pediatric&clinical_context=pediatrics&context_expansion=true" \
  -H "Authorization: Bearer YOUR_API_KEY"
Academic and research-focused search: 
curl -X GET "https://api.omophub.com/v1/search/semantic?query=inflammatory%20biomarkers%20in%20rheumatoid%20arthritis&search_mode=research&include_related_concepts=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Semantic Search Modes

​
Comprehensive

  • Description: Broad semantic exploration with context expansion
  • Best For: Initial concept discovery, research, comprehensive evaluation
  • Threshold: Lower (0.6-0.7)
  • Results: More diverse, includes related concepts

​
Precise

  • Description: Strict semantic matching for exact concept identification
  • Best For: Specific diagnosis lookup, exact concept mapping
  • Threshold: Higher (0.8-0.9)
  • Results: Highly relevant, fewer false positives

​
Exploratory

  • Description: Wide-ranging exploration of semantic relationships
  • Best For: Research, concept discovery, broad medical exploration
  • Threshold: Lowest (0.5-0.6)
  • Results: Maximum diversity, includes distant relationships

​
Clinical

  • Description: Optimized for clinical decision-making contexts
  • Best For: Patient care, diagnostic support, clinical documentation
  • Threshold: Moderate (0.7-0.8)
  • Results: Clinically relevant, practice-oriented

​
Research

  • Description: Academic and research-focused semantic search
  • Best For: Literature research, hypothesis generation, academic study
  • Threshold: Variable (0.6-0.8)
  • Results: Research-relevant, includes emerging concepts

​
Language Models

​
Medical BERT

  • Description: BERT model trained on medical literature and clinical texts
  • Strengths: General medical understanding, clinical context
  • Best For: General medical queries, clinical documentation
  • Performance: Balanced speed and accuracy

​
Clinical Transformer

  • Description: Transformer model optimized for clinical text
  • Strengths: Clinical reasoning, diagnostic context
  • Best For: Clinical decision support, diagnostic queries
  • Performance: Higher accuracy, moderate speed

​
Bio GPT

  • Description: GPT-based model trained on biomedical literature
  • Strengths: Research context, complex medical relationships
  • Best For: Research queries, literature exploration
  • Performance: High accuracy, slower processing

​
Hybrid

  • Description: Ensemble of multiple models with weighted scoring
  • Strengths: Comprehensive coverage, robust performance
  • Best For: Mission-critical applications, diverse query types
  • Performance: Highest accuracy, slowest processing

​
Semantic Relationship Types

​
Synonymous

  • Description: Concepts with equivalent or near-equivalent meaning
  • Examples: “heart attack” → “myocardial infarction”
  • Score Range: 0.9-1.0
  • Clinical Use: Direct concept mapping, terminology standardization

​
Broader

  • Description: More general concepts that encompass the query
  • Examples: “Type 2 diabetes” → “diabetes mellitus”
  • Score Range: 0.7-0.9
  • Clinical Use: Differential diagnosis, concept hierarchies

​
Narrower

  • Description: More specific concepts within the query domain
  • Examples: “pneumonia” → “bacterial pneumonia”
  • Score Range: 0.7-0.9
  • Clinical Use: Specific diagnosis, detailed classification
  • Description: Conceptually connected but not hierarchically related
  • Examples: “diabetes” → “insulin”
  • Score Range: 0.6-0.8
  • Clinical Use: Associated conditions, related treatments

​
Clinical Context Applications

​
Diagnostic Support

  • Query Types: Symptom descriptions, clinical presentations
  • Context: Patient symptoms, examination findings
  • Output: Differential diagnoses, related conditions
  • Example: “chest pain with shortness of breath”

​
Treatment Planning

  • Query Types: Therapeutic interventions, treatment options
  • Context: Condition-specific treatments, patient factors
  • Output: Treatment options, therapeutic procedures
  • Example: “treatment for hypertension in elderly patients”
  • Query Types: Drug indications, therapeutic effects
  • Context: Clinical conditions, patient characteristics
  • Output: Relevant medications, drug classes
  • Example: “antibiotic for respiratory infection”

​
Procedure Selection

  • Query Types: Medical procedures, interventions
  • Context: Clinical indications, patient factors
  • Output: Appropriate procedures, surgical options
  • Example: “minimally invasive cardiac surgery”

​
Performance Optimization

​
Query Formulation

  • Natural Language: Use complete sentences and clinical language
  • Specificity: Include relevant clinical context and details
  • Medical Terminology: Mix lay terms with medical terminology
  • Context: Provide clinical specialty or patient context

​
Threshold Selection

  • High Precision: Use 0.8+ for specific concept identification
  • Balanced: Use 0.7 for general clinical search
  • High Recall: Use 0.6 for broad exploration
  • Research: Use 0.5-0.6 for comprehensive discovery

​
Model Selection

  • Speed Priority: Use Medical BERT
  • Accuracy Priority: Use Clinical Transformer or Hybrid
  • Research Focus: Use Bio GPT
  • Balanced: Use Hybrid model
⌘I