Search Suggest - OMOPHub.com API

curl -X GET "https://api.omophub.com/v1/search/suggest?query=hart%20atack&vocabulary_ids=SNOMED,ICD10CM&suggestion_types=spelling,synonym,related&medical_context=cardiology&include_explanations=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "query": "hart atack",
    "query_analysis": {
      "detected_intent": "diagnostic",
      "confidence": 0.89,
      "query_quality": "Poor",
      "medical_concepts": [
        {
          "concept": "heart attack",
          "confidence": 0.85,
          "issues": ["spelling error in 'hart'", "spelling error in 'atack'"]
        }
      ],
      "potential_issues": [
        "Multiple spelling errors detected",
        "Informal terminology used",
        "Could be more specific"
      ],
      "improvement_opportunities": [
        "Use correct spelling: 'heart attack'",
        "Consider medical terminology: 'myocardial infarction'",
        "Specify type: 'acute myocardial infarction'"
      ]
    },
    "suggestions": {
      "spelling_corrections": [
        {
          "original": "hart",
          "correction": "heart",
          "confidence": 0.95,
          "correction_type": "spelling",
          "explanation": "Common misspelling of 'heart' in medical queries"
        },
        {
          "original": "atack",
          "correction": "attack", 
          "confidence": 0.92,
          "correction_type": "spelling",
          "explanation": "Missing 't' in 'attack' - common typo"
        }
      ],
      "synonyms": [
        {
          "original_term": "heart attack",
          "synonym": "myocardial infarction",
          "relevance_score": 0.98,
          "concept_id": 22298006,
          "vocabulary_id": "SNOMED",
          "usage_context": "Clinical documentation",
          "formality_level": "Technical",
          "explanation": "Standard medical terminology for heart attack, preferred in clinical settings"
        },
        {
          "original_term": "heart attack",
          "synonym": "MI",
          "relevance_score": 0.92,
          "concept_id": 22298006,
          "vocabulary_id": "SNOMED",
          "usage_context": "Clinical abbreviation",
          "formality_level": "Clinical",
          "explanation": "Common clinical abbreviation for myocardial infarction"
        },
        {
          "original_term": "heart attack",
          "synonym": "acute coronary syndrome",
          "relevance_score": 0.85,
          "concept_id": 394659003,
          "vocabulary_id": "SNOMED",
          "usage_context": "Emergency medicine",
          "formality_level": "Clinical",
          "explanation": "Broader clinical term encompassing heart attacks and related conditions"
        }
      ],
      "related_concepts": [
        {
          "suggested_term": "angina pectoris",
          "relationship_type": "related_condition",
          "relevance_score": 0.87,
          "concept_id": 194828000,
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "clinical_context": "Precursor or related chest pain condition",
          "explanation": "Related cardiac condition that can precede or mimic heart attack"
        },
        {
          "suggested_term": "coronary artery disease",
          "relationship_type": "underlying_cause",
          "relevance_score": 0.82,
          "concept_id": 53741008,
          "vocabulary_id": "SNOMED", 
          "domain_id": "Condition",
          "clinical_context": "Underlying pathology leading to heart attack",
          "explanation": "Primary underlying condition that causes most heart attacks"
        },
        {
          "suggested_term": "cardiac arrest",
          "relationship_type": "potential_complication",
          "relevance_score": 0.79,
          "concept_id": 410429000,
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "clinical_context": "Serious complication of heart attack",
          "explanation": "Potential life-threatening complication of myocardial infarction"
        }
      ],
      "broader_concepts": [
        {
          "suggested_term": "cardiovascular disease",
          "hierarchy_level": 2,
          "relevance_score": 0.76,
          "concept_id": 49601007,
          "vocabulary_id": "SNOMED",
          "generalization_type": "system",
          "use_case": "For broader cardiovascular condition searches"
        },
        {
          "suggested_term": "heart disease",
          "hierarchy_level": 1,
          "relevance_score": 0.81,
          "concept_id": 56265001,
          "vocabulary_id": "SNOMED",
          "generalization_type": "category",
          "use_case": "For general cardiac condition searches"
        }
      ],
      "narrower_concepts": [
        {
          "suggested_term": "ST elevation myocardial infarction",
          "hierarchy_level": 1,
          "relevance_score": 0.89,
          "concept_id": 401314000,
          "vocabulary_id": "SNOMED",
          "specialization_type": "subtype",
          "clinical_specificity": "High - specific type based on ECG findings"
        },
        {
          "suggested_term": "non-ST elevation myocardial infarction",
          "hierarchy_level": 1,
          "relevance_score": 0.87,
          "concept_id": 401303003,
          "vocabulary_id": "SNOMED",
          "specialization_type": "subtype",
          "clinical_specificity": "High - specific type based on ECG findings"
        },
        {
          "suggested_term": "acute anterior myocardial infarction",
          "hierarchy_level": 1,
          "relevance_score": 0.84,
          "concept_id": 54329005,
          "vocabulary_id": "SNOMED",
          "specialization_type": "anatomical_location",
          "clinical_specificity": "Very High - location-specific type"
        }
      ],
      "alternative_phrasings": [
        {
          "alternative_query": "heart attack",
          "phrasing_type": "corrected_lay",
          "appropriateness_score": 0.95,
          "target_audience": "General public, patients",
          "expected_results": 234,
          "advantages": [
            "Correct spelling",
            "Widely understood",
            "Patient-friendly"
          ]
        },
        {
          "alternative_query": "myocardial infarction",
          "phrasing_type": "medical_technical",
          "appropriateness_score": 0.92,
          "target_audience": "Healthcare professionals",
          "expected_results": 187,
          "advantages": [
            "Precise medical terminology",
            "Preferred in clinical documentation",
            "Standardized term"
          ]
        },
        {
          "alternative_query": "acute MI",
          "phrasing_type": "clinical_abbreviation",
          "appropriateness_score": 0.87,
          "target_audience": "Clinical staff",
          "expected_results": 156,
          "advantages": [
            "Efficient clinical communication",
            "Commonly used abbreviation",
            "Time-saving"
          ]
        }
      ],
      "trending_suggestions": [
        {
          "suggested_term": "troponin elevation",
          "trend_score": 0.78,
          "trend_context": "diagnostic_biomarker",
          "relevance_to_query": 0.82,
          "trend_duration": "6 months",
          "specialty_focus": [
            "emergency_medicine",
            "cardiology"
          ]
        }
      ],
      "popular_suggestions": [
        {
          "suggested_term": "chest pain",
          "popularity_score": 0.94,
          "search_volume": "High",
          "user_base": "Healthcare professionals and patients",
          "seasonal_pattern": "Stable year-round",
          "stability": "Stable"
        },
        {
          "suggested_term": "cardiac symptoms",
          "popularity_score": 0.86,
          "search_volume": "Medium",
          "user_base": "Healthcare professionals",
          "seasonal_pattern": "None",
          "stability": "Stable"
        }
      ]
    },
    "contextual_recommendations": {
      "search_strategy": "Start with corrected spelling, then explore specific types if needed",
      "vocabulary_recommendations": [
        {
          "vocabulary": "SNOMED",
          "reason": "Comprehensive cardiac terminology",
          "priority": "High"
        },
        {
          "vocabulary": "ICD10CM",
          "reason": "Administrative coding and billing",
          "priority": "Medium"
        }
      ],
      "domain_focus": [
        "Condition",
        "Observation"
      ],
      "filter_suggestions": [
        {
          "filter": "domain=Condition",
          "reason": "Focus on diagnostic conditions"
        },
        {
          "filter": "specialty=cardiology",
          "reason": "Cardiac-specific context"
        }
      ],
      "search_tips": [
        "Use correct spelling for better results",
        "Try both lay terms and medical terminology",
        "Consider specific types (STEMI, NSTEMI) for detailed information",
        "Include related symptoms (chest pain, shortness of breath) for broader context"
      ]
    },
    "personalization_insights": null
  },
  "meta": {
    "request_id": "req_search_suggest_123",
    "timestamp": "2024-01-15T10:30:00Z",
    "suggestion_engine_version": "v3.1.0",
    "total_suggestions": 45,
    "processing_time_ms": 178,
    "personalization_applied": false,
    "context_factors": [
      "medical_context: cardiology",
      "spelling_errors_detected",
      "intent: diagnostic",
      "formality: mixed"
    ],
    "vocab_release": "2024.2"
  }
}

curl -X GET "https://api.omophub.com/v1/search/suggest?query=hart%20atack&vocabulary_ids=SNOMED,ICD10CM&suggestion_types=spelling,synonym,related&medical_context=cardiology&include_explanations=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "query": "hart atack",
    "query_analysis": {
      "detected_intent": "diagnostic",
      "confidence": 0.89,
      "query_quality": "Poor",
      "medical_concepts": [
        {
          "concept": "heart attack",
          "confidence": 0.85,
          "issues": ["spelling error in 'hart'", "spelling error in 'atack'"]
        }
      ],
      "potential_issues": [
        "Multiple spelling errors detected",
        "Informal terminology used",
        "Could be more specific"
      ],
      "improvement_opportunities": [
        "Use correct spelling: 'heart attack'",
        "Consider medical terminology: 'myocardial infarction'",
        "Specify type: 'acute myocardial infarction'"
      ]
    },
    "suggestions": {
      "spelling_corrections": [
        {
          "original": "hart",
          "correction": "heart",
          "confidence": 0.95,
          "correction_type": "spelling",
          "explanation": "Common misspelling of 'heart' in medical queries"
        },
        {
          "original": "atack",
          "correction": "attack", 
          "confidence": 0.92,
          "correction_type": "spelling",
          "explanation": "Missing 't' in 'attack' - common typo"
        }
      ],
      "synonyms": [
        {
          "original_term": "heart attack",
          "synonym": "myocardial infarction",
          "relevance_score": 0.98,
          "concept_id": 22298006,
          "vocabulary_id": "SNOMED",
          "usage_context": "Clinical documentation",
          "formality_level": "Technical",
          "explanation": "Standard medical terminology for heart attack, preferred in clinical settings"
        },
        {
          "original_term": "heart attack",
          "synonym": "MI",
          "relevance_score": 0.92,
          "concept_id": 22298006,
          "vocabulary_id": "SNOMED",
          "usage_context": "Clinical abbreviation",
          "formality_level": "Clinical",
          "explanation": "Common clinical abbreviation for myocardial infarction"
        },
        {
          "original_term": "heart attack",
          "synonym": "acute coronary syndrome",
          "relevance_score": 0.85,
          "concept_id": 394659003,
          "vocabulary_id": "SNOMED",
          "usage_context": "Emergency medicine",
          "formality_level": "Clinical",
          "explanation": "Broader clinical term encompassing heart attacks and related conditions"
        }
      ],
      "related_concepts": [
        {
          "suggested_term": "angina pectoris",
          "relationship_type": "related_condition",
          "relevance_score": 0.87,
          "concept_id": 194828000,
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "clinical_context": "Precursor or related chest pain condition",
          "explanation": "Related cardiac condition that can precede or mimic heart attack"
        },
        {
          "suggested_term": "coronary artery disease",
          "relationship_type": "underlying_cause",
          "relevance_score": 0.82,
          "concept_id": 53741008,
          "vocabulary_id": "SNOMED", 
          "domain_id": "Condition",
          "clinical_context": "Underlying pathology leading to heart attack",
          "explanation": "Primary underlying condition that causes most heart attacks"
        },
        {
          "suggested_term": "cardiac arrest",
          "relationship_type": "potential_complication",
          "relevance_score": 0.79,
          "concept_id": 410429000,
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "clinical_context": "Serious complication of heart attack",
          "explanation": "Potential life-threatening complication of myocardial infarction"
        }
      ],
      "broader_concepts": [
        {
          "suggested_term": "cardiovascular disease",
          "hierarchy_level": 2,
          "relevance_score": 0.76,
          "concept_id": 49601007,
          "vocabulary_id": "SNOMED",
          "generalization_type": "system",
          "use_case": "For broader cardiovascular condition searches"
        },
        {
          "suggested_term": "heart disease",
          "hierarchy_level": 1,
          "relevance_score": 0.81,
          "concept_id": 56265001,
          "vocabulary_id": "SNOMED",
          "generalization_type": "category",
          "use_case": "For general cardiac condition searches"
        }
      ],
      "narrower_concepts": [
        {
          "suggested_term": "ST elevation myocardial infarction",
          "hierarchy_level": 1,
          "relevance_score": 0.89,
          "concept_id": 401314000,
          "vocabulary_id": "SNOMED",
          "specialization_type": "subtype",
          "clinical_specificity": "High - specific type based on ECG findings"
        },
        {
          "suggested_term": "non-ST elevation myocardial infarction",
          "hierarchy_level": 1,
          "relevance_score": 0.87,
          "concept_id": 401303003,
          "vocabulary_id": "SNOMED",
          "specialization_type": "subtype",
          "clinical_specificity": "High - specific type based on ECG findings"
        },
        {
          "suggested_term": "acute anterior myocardial infarction",
          "hierarchy_level": 1,
          "relevance_score": 0.84,
          "concept_id": 54329005,
          "vocabulary_id": "SNOMED",
          "specialization_type": "anatomical_location",
          "clinical_specificity": "Very High - location-specific type"
        }
      ],
      "alternative_phrasings": [
        {
          "alternative_query": "heart attack",
          "phrasing_type": "corrected_lay",
          "appropriateness_score": 0.95,
          "target_audience": "General public, patients",
          "expected_results": 234,
          "advantages": [
            "Correct spelling",
            "Widely understood",
            "Patient-friendly"
          ]
        },
        {
          "alternative_query": "myocardial infarction",
          "phrasing_type": "medical_technical",
          "appropriateness_score": 0.92,
          "target_audience": "Healthcare professionals",
          "expected_results": 187,
          "advantages": [
            "Precise medical terminology",
            "Preferred in clinical documentation",
            "Standardized term"
          ]
        },
        {
          "alternative_query": "acute MI",
          "phrasing_type": "clinical_abbreviation",
          "appropriateness_score": 0.87,
          "target_audience": "Clinical staff",
          "expected_results": 156,
          "advantages": [
            "Efficient clinical communication",
            "Commonly used abbreviation",
            "Time-saving"
          ]
        }
      ],
      "trending_suggestions": [
        {
          "suggested_term": "troponin elevation",
          "trend_score": 0.78,
          "trend_context": "diagnostic_biomarker",
          "relevance_to_query": 0.82,
          "trend_duration": "6 months",
          "specialty_focus": [
            "emergency_medicine",
            "cardiology"
          ]
        }
      ],
      "popular_suggestions": [
        {
          "suggested_term": "chest pain",
          "popularity_score": 0.94,
          "search_volume": "High",
          "user_base": "Healthcare professionals and patients",
          "seasonal_pattern": "Stable year-round",
          "stability": "Stable"
        },
        {
          "suggested_term": "cardiac symptoms",
          "popularity_score": 0.86,
          "search_volume": "Medium",
          "user_base": "Healthcare professionals",
          "seasonal_pattern": "None",
          "stability": "Stable"
        }
      ]
    },
    "contextual_recommendations": {
      "search_strategy": "Start with corrected spelling, then explore specific types if needed",
      "vocabulary_recommendations": [
        {
          "vocabulary": "SNOMED",
          "reason": "Comprehensive cardiac terminology",
          "priority": "High"
        },
        {
          "vocabulary": "ICD10CM",
          "reason": "Administrative coding and billing",
          "priority": "Medium"
        }
      ],
      "domain_focus": [
        "Condition",
        "Observation"
      ],
      "filter_suggestions": [
        {
          "filter": "domain=Condition",
          "reason": "Focus on diagnostic conditions"
        },
        {
          "filter": "specialty=cardiology",
          "reason": "Cardiac-specific context"
        }
      ],
      "search_tips": [
        "Use correct spelling for better results",
        "Try both lay terms and medical terminology",
        "Consider specific types (STEMI, NSTEMI) for detailed information",
        "Include related symptoms (chest pain, shortness of breath) for broader context"
      ]
    },
    "personalization_insights": null
  },
  "meta": {
    "request_id": "req_search_suggest_123",
    "timestamp": "2024-01-15T10:30:00Z",
    "suggestion_engine_version": "v3.1.0",
    "total_suggestions": 45,
    "processing_time_ms": 178,
    "personalization_applied": false,
    "context_factors": [
      "medical_context: cardiology",
      "spelling_errors_detected",
      "intent: diagnostic",
      "formality: mixed"
    ],
    "vocab_release": "2024.2"
  }
}

Overview

This endpoint provides intelligent search suggestions and query recommendations to help users refine their medical terminology searches. It analyzes user queries, medical context, and search patterns to suggest alternative search terms, related concepts, and improved query formulations.

Query Parameters

query

string

required

Original search query for which suggestions are needed

vocabulary_ids

string

Target vocabularies for suggestions (comma-separated)
Examples: SNOMED, ICD10CM,LOINC, RXNORM,NDC

domain_ids

string

Filter suggestions to specific domains (comma-separated)
Examples: Condition,Procedure, Drug,Device

concept_class_ids

string

Filter to specific concept classes (comma-separated)

suggestion_types

string

default:"all"

Types of suggestions to include (comma-separated)
Options: spelling, synonym, related, broader, narrower, alternative, trending, popular, all

medical_context

string

Medical specialty context for relevant suggestions
Examples: cardiology, oncology, pediatrics, emergency_medicine

user_context

string

User type for suggestion personalization
Options: physician, nurse, pharmacist, researcher, patient, student

search_intent

string

Detected or specified search intent
Options: diagnostic, therapeutic, procedural, research, educational, administrative

include_corrections

boolean

default:"true"

Include spelling corrections and typo fixes

include_alternatives

boolean

default:"true"

Include alternative phrasings and synonyms

Include conceptually related terms

include_hierarchical

boolean

default:"true"

Include broader and narrower concepts

Include trending medical terms

include_popular

boolean

default:"true"

Include popular search terms

include_explanations

boolean

default:"false"

Include explanations for why suggestions are relevant

personalization

boolean

default:"false"

Enable personalized suggestions based on user history

cultural_context

string

Cultural or regional context for suggestions
Examples: US, UK, international, multicultural

language

string

default:"en"

Language for suggestions (ISO 639-1 code)

complexity_level

string

default:"balanced"

Preferred complexity level for suggestions
Options: simple, intermediate, advanced, technical, balanced

patient_facing

boolean

default:"false"

Whether suggestions should be patient-appropriate

standard_concept

string

Filter by standard concept status: S, N, C

include_invalid

boolean

default:"true"

Include suggestions for invalid/deprecated concepts

page

integer

default:"1"

Page number (1-based indexing)

page_size

integer

default:"20"

Number of suggestions to return per page (max 100)

relevance_threshold

number

default:"0.6"

Minimum relevance score for suggestions (0.0-1.0)

vocab_release

string

Specific vocabulary release version (defaults to latest)

Response

success

boolean

Indicates if the request was successful

data

object

Show Search Suggestions

query

string

Original search query

query_analysis

object

Show Query Analysis

detected_intent

string

Automatically detected search intent

confidence

number

Confidence in intent detection (0.0-1.0)

query_quality

string

Assessment of query quality (Excellent, Good, Fair, Poor)

medical_concepts

array

Medical concepts identified in the query

potential_issues

array

Potential issues with the query

improvement_opportunities

array

Ways the query could be improved

suggestions

object

Show Suggestion Categories

spelling_corrections

array

Spelling and typo corrections

Show Spelling Correction

original

string

Original potentially misspelled term

correction

string

Suggested correction

confidence

number

Confidence in the correction (0.0-1.0)

correction_type

string

Type of correction (typo, spelling, grammar)

explanation

string

Explanation of the correction (if include_explanations=true)

synonyms

array

Synonym suggestions

Show Synonym Suggestion

original_term

string

Original term from query

synonym

string

Suggested synonym

relevance_score

number

Relevance score (0.0-1.0)

concept_id

integer

Associated concept ID (if applicable)

vocabulary_id

string

Source vocabulary

usage_context

string

Typical usage context

formality_level

string

Level of formality (Technical, Clinical, Lay)

explanation

string

Why this synonym is relevant (if include_explanations=true)

Conceptually related suggestions

Show Related Concept Suggestion

broader_concepts

array

More general concept suggestions

Show Broader Concept Suggestion

suggested_term

string

Suggested broader term

hierarchy_level

integer

Levels up in hierarchy

relevance_score

number

Relevance score (0.0-1.0)

concept_id

integer

Concept ID

vocabulary_id

string

Source vocabulary

generalization_type

string

Type of generalization (category, class, system)

use_case

string

When to use this broader term

narrower_concepts

array

More specific concept suggestions

Show Narrower Concept Suggestion

suggested_term

string

Suggested narrower term

hierarchy_level

integer

Levels down in hierarchy

relevance_score

number

Relevance score (0.0-1.0)

concept_id

integer

Concept ID

vocabulary_id

string

Source vocabulary

specialization_type

string

Type of specialization (subtype, specific case, variant)

clinical_specificity

string

Level of clinical specificity

alternative_phrasings

array

Alternative ways to phrase the query

Show Alternative Phrasing

alternative_query

string

Alternative query phrasing

phrasing_type

string

Type of alternative (formal, informal, technical, lay)

appropriateness_score

number

Appropriateness score (0.0-1.0)

target_audience

string

Intended audience for this phrasing

expected_results

integer

Expected number of search results

advantages

array

Advantages of this phrasing

Trending medical terms related to the query

Show Trending Suggestion

popular_suggestions

array

Popular search terms related to the query

Show Popular Suggestion

suggested_term

string

Popular term

popularity_score

number

Popularity score (0.0-1.0)

search_volume

string

Relative search volume (High, Medium, Low)

user_base

string

Primary user base for this term

seasonal_pattern

string

Seasonal usage pattern (if applicable)

stability

string

Stability of popularity (Stable, Growing, Declining)

contextual_recommendations

object

Show Contextual Recommendations

search_strategy

string

Recommended search strategy

vocabulary_recommendations

array

Recommended vocabularies for this query

domain_focus

array

Recommended domains to focus on

filter_suggestions

array

Suggested filters to apply

search_tips

array

General search tips for this type of query

personalization_insights

object

Personalized recommendations (if personalization=true)

Show Personalization Insights

user_patterns

array

Detected user search patterns

preferred_vocabularies

array

User’s preferred vocabularies

common_domains

array

User’s commonly searched domains

suggested_specialties

array

Suggested medical specialties based on history

learning_opportunities

array

Suggested learning opportunities

meta

object

Show Metadata

request_id

string

Unique identifier for the request

timestamp

string

Request timestamp

suggestion_engine_version

string

Suggestion engine version

total_suggestions

integer

Total number of suggestions returned

processing_time_ms

integer

Time taken to generate suggestions

personalization_applied

boolean

Whether personalization was used

context_factors

array

Contextual factors influencing suggestions

vocab_release

string

Vocabulary release version used

curl -X GET "https://api.omophub.com/v1/search/suggest?query=hart%20atack&vocabulary_ids=SNOMED,ICD10CM&suggestion_types=spelling,synonym,related&medical_context=cardiology&include_explanations=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "query": "hart atack",
    "query_analysis": {
      "detected_intent": "diagnostic",
      "confidence": 0.89,
      "query_quality": "Poor",
      "medical_concepts": [
        {
          "concept": "heart attack",
          "confidence": 0.85,
          "issues": ["spelling error in 'hart'", "spelling error in 'atack'"]
        }
      ],
      "potential_issues": [
        "Multiple spelling errors detected",
        "Informal terminology used",
        "Could be more specific"
      ],
      "improvement_opportunities": [
        "Use correct spelling: 'heart attack'",
        "Consider medical terminology: 'myocardial infarction'",
        "Specify type: 'acute myocardial infarction'"
      ]
    },
    "suggestions": {
      "spelling_corrections": [
        {
          "original": "hart",
          "correction": "heart",
          "confidence": 0.95,
          "correction_type": "spelling",
          "explanation": "Common misspelling of 'heart' in medical queries"
        },
        {
          "original": "atack",
          "correction": "attack", 
          "confidence": 0.92,
          "correction_type": "spelling",
          "explanation": "Missing 't' in 'attack' - common typo"
        }
      ],
      "synonyms": [
        {
          "original_term": "heart attack",
          "synonym": "myocardial infarction",
          "relevance_score": 0.98,
          "concept_id": 22298006,
          "vocabulary_id": "SNOMED",
          "usage_context": "Clinical documentation",
          "formality_level": "Technical",
          "explanation": "Standard medical terminology for heart attack, preferred in clinical settings"
        },
        {
          "original_term": "heart attack",
          "synonym": "MI",
          "relevance_score": 0.92,
          "concept_id": 22298006,
          "vocabulary_id": "SNOMED",
          "usage_context": "Clinical abbreviation",
          "formality_level": "Clinical",
          "explanation": "Common clinical abbreviation for myocardial infarction"
        },
        {
          "original_term": "heart attack",
          "synonym": "acute coronary syndrome",
          "relevance_score": 0.85,
          "concept_id": 394659003,
          "vocabulary_id": "SNOMED",
          "usage_context": "Emergency medicine",
          "formality_level": "Clinical",
          "explanation": "Broader clinical term encompassing heart attacks and related conditions"
        }
      ],
      "related_concepts": [
        {
          "suggested_term": "angina pectoris",
          "relationship_type": "related_condition",
          "relevance_score": 0.87,
          "concept_id": 194828000,
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "clinical_context": "Precursor or related chest pain condition",
          "explanation": "Related cardiac condition that can precede or mimic heart attack"
        },
        {
          "suggested_term": "coronary artery disease",
          "relationship_type": "underlying_cause",
          "relevance_score": 0.82,
          "concept_id": 53741008,
          "vocabulary_id": "SNOMED", 
          "domain_id": "Condition",
          "clinical_context": "Underlying pathology leading to heart attack",
          "explanation": "Primary underlying condition that causes most heart attacks"
        },
        {
          "suggested_term": "cardiac arrest",
          "relationship_type": "potential_complication",
          "relevance_score": 0.79,
          "concept_id": 410429000,
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "clinical_context": "Serious complication of heart attack",
          "explanation": "Potential life-threatening complication of myocardial infarction"
        }
      ],
      "broader_concepts": [
        {
          "suggested_term": "cardiovascular disease",
          "hierarchy_level": 2,
          "relevance_score": 0.76,
          "concept_id": 49601007,
          "vocabulary_id": "SNOMED",
          "generalization_type": "system",
          "use_case": "For broader cardiovascular condition searches"
        },
        {
          "suggested_term": "heart disease",
          "hierarchy_level": 1,
          "relevance_score": 0.81,
          "concept_id": 56265001,
          "vocabulary_id": "SNOMED",
          "generalization_type": "category",
          "use_case": "For general cardiac condition searches"
        }
      ],
      "narrower_concepts": [
        {
          "suggested_term": "ST elevation myocardial infarction",
          "hierarchy_level": 1,
          "relevance_score": 0.89,
          "concept_id": 401314000,
          "vocabulary_id": "SNOMED",
          "specialization_type": "subtype",
          "clinical_specificity": "High - specific type based on ECG findings"
        },
        {
          "suggested_term": "non-ST elevation myocardial infarction",
          "hierarchy_level": 1,
          "relevance_score": 0.87,
          "concept_id": 401303003,
          "vocabulary_id": "SNOMED",
          "specialization_type": "subtype",
          "clinical_specificity": "High - specific type based on ECG findings"
        },
        {
          "suggested_term": "acute anterior myocardial infarction",
          "hierarchy_level": 1,
          "relevance_score": 0.84,
          "concept_id": 54329005,
          "vocabulary_id": "SNOMED",
          "specialization_type": "anatomical_location",
          "clinical_specificity": "Very High - location-specific type"
        }
      ],
      "alternative_phrasings": [
        {
          "alternative_query": "heart attack",
          "phrasing_type": "corrected_lay",
          "appropriateness_score": 0.95,
          "target_audience": "General public, patients",
          "expected_results": 234,
          "advantages": [
            "Correct spelling",
            "Widely understood",
            "Patient-friendly"
          ]
        },
        {
          "alternative_query": "myocardial infarction",
          "phrasing_type": "medical_technical",
          "appropriateness_score": 0.92,
          "target_audience": "Healthcare professionals",
          "expected_results": 187,
          "advantages": [
            "Precise medical terminology",
            "Preferred in clinical documentation",
            "Standardized term"
          ]
        },
        {
          "alternative_query": "acute MI",
          "phrasing_type": "clinical_abbreviation",
          "appropriateness_score": 0.87,
          "target_audience": "Clinical staff",
          "expected_results": 156,
          "advantages": [
            "Efficient clinical communication",
            "Commonly used abbreviation",
            "Time-saving"
          ]
        }
      ],
      "trending_suggestions": [
        {
          "suggested_term": "troponin elevation",
          "trend_score": 0.78,
          "trend_context": "diagnostic_biomarker",
          "relevance_to_query": 0.82,
          "trend_duration": "6 months",
          "specialty_focus": [
            "emergency_medicine",
            "cardiology"
          ]
        }
      ],
      "popular_suggestions": [
        {
          "suggested_term": "chest pain",
          "popularity_score": 0.94,
          "search_volume": "High",
          "user_base": "Healthcare professionals and patients",
          "seasonal_pattern": "Stable year-round",
          "stability": "Stable"
        },
        {
          "suggested_term": "cardiac symptoms",
          "popularity_score": 0.86,
          "search_volume": "Medium",
          "user_base": "Healthcare professionals",
          "seasonal_pattern": "None",
          "stability": "Stable"
        }
      ]
    },
    "contextual_recommendations": {
      "search_strategy": "Start with corrected spelling, then explore specific types if needed",
      "vocabulary_recommendations": [
        {
          "vocabulary": "SNOMED",
          "reason": "Comprehensive cardiac terminology",
          "priority": "High"
        },
        {
          "vocabulary": "ICD10CM",
          "reason": "Administrative coding and billing",
          "priority": "Medium"
        }
      ],
      "domain_focus": [
        "Condition",
        "Observation"
      ],
      "filter_suggestions": [
        {
          "filter": "domain=Condition",
          "reason": "Focus on diagnostic conditions"
        },
        {
          "filter": "specialty=cardiology",
          "reason": "Cardiac-specific context"
        }
      ],
      "search_tips": [
        "Use correct spelling for better results",
        "Try both lay terms and medical terminology",
        "Consider specific types (STEMI, NSTEMI) for detailed information",
        "Include related symptoms (chest pain, shortness of breath) for broader context"
      ]
    },
    "personalization_insights": null
  },
  "meta": {
    "request_id": "req_search_suggest_123",
    "timestamp": "2024-01-15T10:30:00Z",
    "suggestion_engine_version": "v3.1.0",
    "total_suggestions": 45,
    "processing_time_ms": 178,
    "personalization_applied": false,
    "context_factors": [
      "medical_context: cardiology",
      "spelling_errors_detected",
      "intent: diagnostic",
      "formality: mixed"
    ],
    "vocab_release": "2024.2"
  }
}

Usage Examples

Spelling Correction Suggestions

Get suggestions for queries with spelling errors:

curl -X GET "https://api.omophub.com/v1/search/suggest?query=pnemonia&suggestion_types=spelling,synonym&include_corrections=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Comprehensive Query Suggestions

Get comprehensive suggestions for query improvement:

curl -X GET "https://api.omophub.com/v1/search/suggest?query=diabetes&suggestion_types=all&medical_context=endocrinology&user_context=physician&include_explanations=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Alternative Phrasing Suggestions

Get alternative ways to phrase a medical query:

curl -X GET "https://api.omophub.com/v1/search/suggest?query=high%20blood%20pressure&suggestion_types=alternative,synonym&complexity_level=technical&patient_facing=false" \
  -H "Authorization: Bearer YOUR_API_KEY"

Hierarchical Concept Suggestions

Get broader and narrower concept suggestions:

curl -X GET "https://api.omophub.com/v1/search/suggest?query=pneumonia&suggestion_types=broader,narrower&include_hierarchical=true&vocabulary_ids=SNOMED" \
  -H "Authorization: Bearer YOUR_API_KEY"

Patient-Friendly Suggestions

Get patient-appropriate suggestions:

curl -X GET "https://api.omophub.com/v1/search/suggest?query=myocardial%20infarction&user_context=patient&patient_facing=true&complexity_level=simple&include_alternatives=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get trending and popular related terms:

curl -X GET "https://api.omophub.com/v1/search/suggest?query=covid&suggestion_types=trending,popular,related&include_trending=true&include_popular=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Suggestion Types

Spelling Corrections

Purpose: Fix typos and spelling errors
Confidence: High for obvious corrections
Use Case: Improve query accuracy
Examples: “hart” → “heart”, “diabetis” → “diabetes”

Synonyms

Purpose: Alternative terms with same meaning
Formality Levels: Technical, Clinical, Lay
Use Case: Find standard terminology
Examples: “heart attack” → “myocardial infarction”

Relationships: Associated, causes, treats, complicates
Clinical Context: Related conditions and procedures
Use Case: Explore connected medical concepts
Examples: “diabetes” → “insulin”, “hyperglycemia”

Broader Concepts

Hierarchy: Move up concept hierarchies
Generalization: Category, system, class level
Use Case: Widen search scope
Examples: “pneumonia” → “lung disease” → “respiratory condition”

Narrower Concepts

Specialization: Subtypes, variants, specific cases
Clinical Specificity: Increase diagnostic precision
Use Case: Get more specific results
Examples: “diabetes” → “type 2 diabetes” → “insulin-resistant diabetes”

Alternative Phrasings

Formality: Formal, informal, technical, lay
Target Audience: Professionals, patients, researchers
Use Case: Reach different audiences
Examples: “MI” vs “heart attack” vs “myocardial infarction”

Temporal: Currently popular or emerging
Context: Research, clinical practice, news
Use Case: Discover emerging topics
Examples: New treatments, recent outbreaks, research terms

Popular Suggestions

Usage: Commonly searched terms
Stability: Stable, growing, or declining popularity
Use Case: Find common related searches
Examples: High-volume search terms

Search Intent Detection

Diagnostic Intent

Characteristics: Symptom descriptions, condition names
Suggestions: Differential diagnoses, related symptoms
Context: Clinical assessment, patient evaluation
Examples: “chest pain” → diagnostic conditions

Therapeutic Intent

Characteristics: Treatment queries, medication searches
Suggestions: Treatment options, drug alternatives
Context: Treatment planning, medication selection
Examples: “diabetes treatment” → therapeutic options

Procedural Intent

Characteristics: Procedure names, intervention queries
Suggestions: Related procedures, alternatives
Context: Procedure selection, surgical planning
Examples: “cardiac catheterization” → related procedures

Research Intent

Characteristics: Technical terms, study-related queries
Suggestions: Research terminology, methodological terms
Context: Academic research, literature review
Examples: “biomarkers” → research concepts

Educational Intent

Characteristics: Learning-focused queries
Suggestions: Educational resources, explanatory terms
Context: Medical education, patient education
Examples: “anatomy” → educational concepts

Administrative Intent

Characteristics: Coding, billing, documentation queries
Suggestions: Administrative codes, documentation terms
Context: Medical coding, billing processes
Examples: “ICD codes” → administrative terminology

Personalization Features

User Pattern Analysis

Search History: Commonly searched terms and domains
Vocabulary Preferences: Preferred medical vocabularies
Specialty Focus: Medical specialties of interest
Complexity Level: Preferred terminology complexity

Personalized Suggestions

Relevant Terms: Terms matching user’s interests
Vocabulary Bias: Suggestions from preferred vocabularies
Specialty Context: Specialty-specific recommendations
Learning Path: Educational progression suggestions

Privacy Considerations

Opt-in: Personalization requires explicit consent
Data Security: Secure storage of user patterns
Anonymization: Personal data anonymization
User Control: Users can disable personalization

Cultural and Regional Context

Regional Terminology

US Medical Terms: American medical terminology preferences
UK Medical Terms: British medical terminology variations
International: WHO and international standard terms
Multicultural: Inclusive terminology for diverse populations

Cultural Sensitivity

Inclusive Language: Culturally appropriate medical terms
Accessibility: Terms accessible to diverse populations
Local Practices: Regional medical practice variations
Language Variants: Regional language preferences

Search Autocomplete - Real-time query completion
Basic Search - Execute suggested searches
Semantic Search - Meaning-based search
Fuzzy Search - Typo-tolerant search

Search Facets Search Trending

​Overview

​Query Parameters

​Response

​Usage Examples

​Spelling Correction Suggestions

​Comprehensive Query Suggestions

​Alternative Phrasing Suggestions

​Hierarchical Concept Suggestions

​Patient-Friendly Suggestions

​Trending and Popular Suggestions

​Suggestion Types

​Spelling Corrections

​Synonyms

​Related Concepts

​Broader Concepts

​Narrower Concepts

​Alternative Phrasings

​Trending Suggestions

​Popular Suggestions

​Search Intent Detection

​Diagnostic Intent

​Therapeutic Intent

​Procedural Intent

​Research Intent

​Educational Intent

​Administrative Intent

​Personalization Features

​User Pattern Analysis

​Personalized Suggestions

​Privacy Considerations

​Cultural and Regional Context

​Regional Terminology

​Cultural Sensitivity

​Related Endpoints

Overview

Query Parameters

Response

Usage Examples

Spelling Correction Suggestions

Comprehensive Query Suggestions

Alternative Phrasing Suggestions

Hierarchical Concept Suggestions

Patient-Friendly Suggestions

Trending and Popular Suggestions

Suggestion Types

Spelling Corrections

Synonyms

Related Concepts

Broader Concepts

Narrower Concepts

Alternative Phrasings

Trending Suggestions

Popular Suggestions

Search Intent Detection

Diagnostic Intent

Therapeutic Intent

Procedural Intent

Research Intent

Educational Intent

Administrative Intent

Personalization Features

User Pattern Analysis

Personalized Suggestions

Privacy Considerations

Cultural and Regional Context

Regional Terminology

Cultural Sensitivity

Related Endpoints