Search Autocomplete (Coming Soon)

This feature is coming soon and is not yet available in the current API version.

Overview

This endpoint will provide intelligent autocomplete functionality for medical terminology searches. It will offer real-time suggestions as users type, helping them find the correct medical terms quickly and accurately. The system will understand medical context, abbreviations, and common spelling patterns to provide relevant suggestions.

Query Parameters

query

string

required

Partial search query for autocompletion (minimum 2 characters)

vocabulary_ids

string

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

domains

string

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

concept_classes

string

Filter to specific concept classes (comma-separated)

suggestion_types

string

default:"all"

Types of suggestions to include (comma-separated)
Options: exact, fuzzy, semantic, phonetic, abbreviation, all

completion_mode

string

default:"balanced"

Autocomplete completion strategy
Options: prefix, substring, fuzzy, semantic, balanced

medical_context

string

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

user_context

string

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

include_synonyms

boolean

default:"true"

Include synonyms in suggestions

include_abbreviations

boolean

default:"true"

Include medical abbreviations and acronyms

include_definitions

boolean

default:"false"

Include brief definitions with suggestions

include_frequency

boolean

default:"true"

Include usage frequency information

boost_recent

boolean

default:"true"

Boost recently searched terms

boost_popular

boolean

default:"true"

Boost commonly used medical terms

personalization

boolean

default:"false"

Enable personalized suggestions based on user history

min_frequency

integer

default:"1"

Minimum usage frequency for suggestions (integer count). This maps to the normalized frequency_score (0.0-1.0) in responses. Higher frequency counts result in higher frequency_scores through logarithmic normalization.

fuzzy_tolerance

number

default:"0.7"

Tolerance for fuzzy matching (0.0-1.0)

language

string

default:"en"

Language for suggestions (ISO 639-1 code)

regional_variant

string

Regional variant for terminology preferences
Examples: US, UK, AU, CA

standard_concept

string

Filter by standard concept status: S, N, C

include_invalid

boolean

default:"false"

Include invalid/deprecated concepts

max_suggestions

integer

default:"10"

Maximum number of suggestions to return (max 50)

response_time_limit

integer

default:"200"

Maximum response time in milliseconds (for real-time UX)
Note: 100ms applies only to highly optimized self-hosted stacks. Benchmark p50/p95 latency under realistic load. Third-party providers often exceed 500ms so adjust expectations accordingly.

vocab_release

string

Specific vocabulary release version (defaults to latest)

Response

success

boolean

Indicates if the request was successful

data

object

Show Autocomplete Results

query

string

Original partial query

autocomplete_metadata

object

Show Autocomplete Metadata

query_length

integer

Length of the input query

completion_mode

string

Completion strategy used

suggestion_count

integer

Number of suggestions returned

processing_time_ms

integer

Time taken to generate suggestions

cache_hit

boolean

Whether suggestions came from cache

personalization_applied

boolean

Whether personalization was used

suggestions

array

Array of autocomplete suggestions

Show Suggestion

suggestion_id

string

Unique identifier for this suggestion

suggested_text

string

Complete suggested search term

display_text

string

Text to display in UI (may include highlighting). Server-sanitized for XSS prevention; only allows safe HTML tags like <mark>. Clients should not perform additional HTML escaping but may sanitize further if needed.

completion_text

string

Text needed to complete the query

suggestion_type

string

Type of suggestion (exact, fuzzy, semantic, abbreviation, etc.)

relevance_score

number

Relevance score for this suggestion (0.0-1.0)

concept_info

object

Show Related Concept Information

match_details

object

Show Match Details

match_type

string

How this suggestion matches the query

match_position

string

Where the match occurs (start, middle, end)

character_offset

integer

Character position of the match

matched_length

integer

Length of the matched portion

completion_needed

integer

Characters needed to complete

usage_info

object

Show Usage Information

frequency_score

number

Usage frequency score (0.0-1.0), normalized from integer usage counts via logarithmic scaling

popularity_rank

integer

Ranking by popularity

recent_usage

boolean

Whether recently searched

search_volume

string

Relative search volume (High, Medium, Low)

Whether this term is trending

medical_context

object

Show Medical Context

specialty_relevance

array

Medical specialties where this term is relevant

clinical_context

string

Clinical context description

severity_level

string

Clinical severity if applicable

patient_facing

boolean

Whether appropriate for patient communication

definition

object

Brief definition (if include_definitions=true)

Show Definition

definition_text

string

Brief definition of the term

definition_source

string

Source of the definition

complexity_level

string

Language complexity (Simple, Moderate, Technical)

alternatives

array

Alternative suggestions (synonyms, variations)

highlighting

object

Show UI Highlighting Information

highlight_start

integer

Start position for highlighting matched text

highlight_end

integer

End position for highlighting

highlight_type

string

Type of highlighting (exact, fuzzy, partial)

suggestion_categories

array

Suggestions grouped by category

Show Suggestion Category

meta

object

Show Metadata

request_id

string

Unique identifier for the request

timestamp

string

Request timestamp

autocomplete_version

string

Autocomplete engine version

suggestions_source

string

Primary source of suggestions (cache, index, oh_model)

personalization_id

string

Personalization identifier (if applicable). Type: string or null

vocab_release

string

Vocabulary release version used

curl -X GET "https://api.omophub.com/v1/search/autocomplete?query=diab&vocabulary_ids=SNOMED,ICD10CM&suggestion_types=exact,fuzzy&include_definitions=true&max_suggestions=15" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "query": "diab",
    "autocomplete_metadata": {
      "query_length": 4,
      "completion_mode": "balanced",
      "suggestion_count": 5,
      "processing_time_ms": 45,
      "cache_hit": true,
      "personalization_applied": false
    },
    "suggestions": [
      {
        "suggestion_id": "auto_1",
        "suggested_text": "diabetes mellitus",
        "display_text": "<strong>diab</strong>etes mellitus",
        "completion_text": "etes mellitus",
        "suggestion_type": "exact",
        "relevance_score": 0.95,
        "concept_info": {
          "concept_id": 73211009,
          "concept_code": "73211009",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S"
        },
        "match_details": {
          "match_type": "prefix",
          "match_position": "start",
          "character_offset": 0,
          "matched_length": 4,
          "completion_needed": 13
        },
        "usage_info": {
          "frequency_score": 0.92,
          "popularity_rank": 1,
          "recent_usage": true,
          "search_volume": "High",
          "trending": false
        },
        "medical_context": {
          "specialty_relevance": [
            "endocrinology",
            "internal_medicine",
            "family_medicine"
          ],
          "clinical_context": "Common endocrine disorder",
          "severity_level": "chronic",
          "patient_facing": true
        },
        "definition": {
          "definition_text": "A group of metabolic disorders characterized by high blood sugar levels over a prolonged period",
          "definition_source": "SNOMED CT",
          "complexity_level": "Moderate"
        },
        "alternatives": [
          "diabetes",
          "DM",
          "diabetic condition"
        ],
        "highlighting": {
          "highlight_start": 0,
          "highlight_end": 4,
          "highlight_type": "exact"
        }
      },
      {
        "suggestion_id": "auto_2",
        "suggested_text": "diabetes",
        "display_text": "<strong>diab</strong>etes",
        "completion_text": "etes",
        "suggestion_type": "exact",
        "relevance_score": 0.93,
        "concept_info": {
          "concept_id": 73211009,
          "concept_code": "73211009",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S"
        },
        "match_details": {
          "match_type": "prefix",
          "match_position": "start",
          "character_offset": 0,
          "matched_length": 4,
          "completion_needed": 4
        },
        "usage_info": {
          "frequency_score": 0.89,
          "popularity_rank": 2,
          "recent_usage": true,
          "search_volume": "High",
          "trending": false
        },
        "medical_context": {
          "specialty_relevance": [
            "endocrinology",
            "internal_medicine",
            "family_medicine"
          ],
          "clinical_context": "Metabolic disorder",
          "severity_level": "chronic",
          "patient_facing": true
        },
        "definition": {
          "definition_text": "A metabolic disorder characterized by elevated blood glucose levels",
          "definition_source": "Medical Dictionary",
          "complexity_level": "Simple"
        },
        "alternatives": [
          "diabetes mellitus",
          "DM"
        ],
        "highlighting": {
          "highlight_start": 0,
          "highlight_end": 4,
          "highlight_type": "exact"
        }
      },
      {
        "suggestion_id": "auto_3",
        "suggested_text": "diabetic",
        "display_text": "<strong>diab</strong>etic",
        "completion_text": "etic",
        "suggestion_type": "exact",
        "relevance_score": 0.87,
        "concept_info": {
          "concept_id": 4030518,
          "concept_code": "420868002",
          "vocabulary_id": "SNOMED",
          "domain_id": "Observation",
          "concept_class_id": "Context-dependent",
          "standard_concept": "S"
        },
        "match_details": {
          "match_type": "prefix",
          "match_position": "start",
          "character_offset": 0,
          "matched_length": 4,
          "completion_needed": 4
        },
        "usage_info": {
          "frequency_score": 0.83,
          "popularity_rank": 3,
          "recent_usage": false,
          "search_volume": "Medium",
          "trending": false
        },
        "medical_context": {
          "specialty_relevance": [
            "endocrinology",
            "ophthalmology",
            "nephrology"
          ],
          "clinical_context": "Related to diabetes or diabetes patient",
          "severity_level": "variable",
          "patient_facing": true
        },
        "definition": {
          "definition_text": "Relating to or affected by diabetes",
          "definition_source": "Medical Dictionary",
          "complexity_level": "Simple"
        },
        "alternatives": [
          "diabetes-related",
          "diabetes patient"
        ],
        "highlighting": {
          "highlight_start": 0,
          "highlight_end": 4,
          "highlight_type": "exact"
        }
      },
      {
        "suggestion_id": "auto_4",
        "suggested_text": "type 2 diabetes",
        "display_text": "type 2 <strong>diab</strong>etes",
        "completion_text": "etes",
        "suggestion_type": "fuzzy",
        "relevance_score": 0.91,
        "concept_info": {
          "concept_id": 201826,
          "concept_code": "44054006",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S"
        },
        "match_details": {
          "match_type": "substring",
          "match_position": "middle",
          "character_offset": 7,
          "matched_length": 4,
          "completion_needed": 4
        },
        "usage_info": {
          "frequency_score": 0.88,
          "popularity_rank": 4,
          "recent_usage": true,
          "search_volume": "High",
          "trending": false
        },
        "medical_context": {
          "specialty_relevance": [
            "endocrinology",
            "internal_medicine"
          ],
          "clinical_context": "Most common form of diabetes",
          "severity_level": "chronic",
          "patient_facing": true
        },
        "definition": {
          "definition_text": "The most common type of diabetes, characterized by insulin resistance",
          "definition_source": "SNOMED CT",
          "complexity_level": "Moderate"
        },
        "alternatives": [
          "T2DM",
          "adult-onset diabetes",
          "NIDDM"
        ],
        "highlighting": {
          "highlight_start": 7,
          "highlight_end": 11,
          "highlight_type": "exact"
        }
      },
      {
        "suggestion_id": "auto_5",
        "suggested_text": "diabetic ketoacidosis",
        "display_text": "<strong>diab</strong>etic ketoacidosis",
        "completion_text": "etic ketoacidosis",
        "suggestion_type": "exact",
        "relevance_score": 0.79,
        "concept_info": {
          "concept_id": 443767006,
          "concept_code": "443767006",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S"
        },
        "match_details": {
          "match_type": "prefix",
          "match_position": "start",
          "character_offset": 0,
          "matched_length": 4,
          "completion_needed": 17
        },
        "usage_info": {
          "frequency_score": 0.65,
          "popularity_rank": 8,
          "recent_usage": false,
          "search_volume": "Medium",
          "trending": false
        },
        "medical_context": {
          "specialty_relevance": [
            "endocrinology",
            "emergency_medicine",
            "intensive_care"
          ],
          "clinical_context": "Serious diabetes complication",
          "severity_level": "severe",
          "patient_facing": false
        },
        "definition": {
          "definition_text": "A serious complication of diabetes characterized by high blood ketones",
          "definition_source": "SNOMED CT",
          "complexity_level": "Technical"
        },
        "alternatives": [
          "DKA",
          "ketoacidosis"
        ],
        "highlighting": {
          "highlight_start": 0,
          "highlight_end": 4,
          "highlight_type": "exact"
        }
      }
    ],
    "suggestion_categories": [
      {
        "category": "Exact Matches",
        "category_type": "exact",
        "suggestion_count": 3,
        "suggestions": ["diabetes mellitus", "diabetes", "diabetic"]
      },
      {
        "category": "Related Terms",
        "category_type": "semantic",
        "suggestion_count": 2,
        "suggestions": ["type 2 diabetes", "diabetic ketoacidosis"]
      },
      {
        "category": "Abbreviations",
        "category_type": "abbreviation",
        "suggestion_count": 3,
        "suggestions": ["DM", "T2DM", "DKA"]
      }
    ],
    "query_insights": {
      "query_completeness": 0.4,
      "likely_intent": "condition_search",
      "medical_domain_hints": [
        "Condition",
        "Endocrine disorders"
      ],
      "spelling_corrections": [],
      "abbreviation_expansions": [
        {
          "abbreviation": "DM",
          "expansion": "Diabetes Mellitus"
        }
      ]
    }
  },
  "meta": {
    "request_id": "req_autocomplete_123",
    "timestamp": "2024-01-15T10:30:00Z",
    "autocomplete_version": "v3.2.1",
    "suggestions_source": "cache",
    "personalization_id": null,
    "vocab_release": "2025.2"
  }
}

Usage Examples

Basic Autocomplete

Get basic suggestions for a partial query:

curl -X GET "https://api.omophub.com/v1/search/autocomplete?query=asth&max_suggestions=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Medical Specialty Context

Get suggestions tailored to a medical specialty:

curl -X GET "https://api.omophub.com/v1/search/autocomplete?query=card&medical_context=cardiology&user_context=physician&include_definitions=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Multi-Type Suggestions

Include different types of suggestions:

curl -X GET "https://api.omophub.com/v1/search/autocomplete?query=pneum&suggestion_types=exact,fuzzy,semantic,abbreviation&include_abbreviations=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Real-Time Autocomplete

Optimize for real-time user experience:

curl -X GET "https://api.omophub.com/v1/search/autocomplete?query=dia&response_time_limit=50&max_suggestions=8&boost_popular=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Personalized Suggestions

Get personalized suggestions based on user context:

curl -X GET "https://api.omophub.com/v1/search/autocomplete?query=anxi&user_context=psychiatrist&personalization=true&boost_recent=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Domain-Specific Autocomplete

Focus suggestions on specific medical domains:

curl -X GET "https://api.omophub.com/v1/search/autocomplete?query=surg&domains=Procedure&vocabulary_ids=SNOMED,HCPCS&include_definitions=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Completion Modes

Prefix Mode

Description: Matches terms that start with the query
Best For: Traditional autocomplete behavior
Performance: Fastest
Example: “diab” → “diabetes”, “diabetic”

Substring Mode

Description: Matches terms containing the query anywhere
Best For: Finding terms when users know partial words
Performance: Fast
Example: “card” → “myocardial”, “pericardium”

Fuzzy Mode

Description: Tolerates typos and spelling variations
Best For: Handling user input errors
Performance: Moderate
Example: “diabetis” → “diabetes”, “diabetic”

Semantic Mode

Description: Finds conceptually related terms
Best For: Discovering related medical concepts
Performance: Slower
Example: “heart attack” → “myocardial infarction”, “coronary syndrome”

Balanced Mode

Description: Combines multiple strategies with weighting
Best For: General-purpose autocomplete
Performance: Moderate
Example: Uses all approaches with intelligent scoring

Suggestion Types

Exact Suggestions

Description: Direct prefix or substring matches
Confidence: High
Use Case: User knows the beginning of the term
Examples: “diab” → “diabetes”, “diabetic”

Fuzzy Suggestions

Description: Matches with spelling tolerance
Confidence: Medium to High
Use Case: User has typos or spelling variations
Examples: “pnemonia” → “pneumonia”

Semantic Suggestions

Description: Conceptually related terms
Confidence: Medium
Use Case: Discovery and exploration
Examples: “chest pain” → “angina”, “myocardial infarction”

Phonetic Suggestions

Description: Matches based on pronunciation
Confidence: Medium
Use Case: Voice input or pronunciation-based search
Examples: “noomonia” → “pneumonia”

Abbreviation Suggestions

Description: Medical abbreviations and acronyms
Confidence: High
Use Case: Professional medical communication
Examples: “MI” → “myocardial infarction”, “DM” → “diabetes mellitus”

User Context Optimization

Physician Context

Priority: Standard medical terminology
Include: Technical terms, abbreviations
Exclude: Lay terms, simplified language
Example: Prefer “myocardial infarction” over “heart attack”

Nurse Context

Priority: Clinical terms with patient care focus
Include: Nursing-specific terminology, care procedures
Exclude: Highly technical research terms
Example: Include “medication administration”, “patient assessment”

Pharmacist Context

Priority: Drug-related terminology
Include: Medication names, drug interactions, dosages
Exclude: Surgical procedures, diagnostic terms
Example: Emphasize drug names, pharmaceutical terminology

Researcher Context

Priority: Technical and research terminology
Include: Research methods, statistical terms, technical concepts
Exclude: Patient-facing language
Example: Include “biomarkers”, “clinical endpoints”

Patient Context

Priority: Patient-friendly terminology
Include: Lay terms, simplified explanations
Exclude: Complex medical jargon
Example: Prefer “heart attack” over “myocardial infarction”

Student Context

Priority: Educational terminology with explanations
Include: Basic concepts with definitions
Exclude: Highly specialized terms
Example: Include terms with educational definitions

Performance Features

Real-Time Optimization

Target Response Time: <100ms for optimal UX
Caching Strategy: Aggressive caching of popular queries
Index Optimization: Pre-computed suggestions for common prefixes
Load Balancing: Distributed processing for high traffic

Intelligent Caching

Query Pattern Cache: Common medical term prefixes
User-Specific Cache: Personalized suggestion cache
Frequency-Based Cache: Cache popular medical terms
Context-Aware Cache: Specialty-specific suggestion cache

Progressive Enhancement

Minimum Query Length: 2 characters for performance
Graduated Complexity: Simple suggestions first, complex later
Quality Thresholds: Filter low-quality suggestions
Response Size Limits: Optimal payload size for speed

Basic Search - Execute full search with completed term
Fuzzy Search - Handle typos in completed searches
Semantic Search - Meaning-based search
Search Suggest - Alternative query suggestions

API Reference

Concepts

Concept Hierarchy

Search

Search (Coming Soon)

Relationships

Domains & Classifications

Mappings

Vocabularies

​Overview

​Query Parameters

​Response

​Usage Examples

​Basic Autocomplete

​Medical Specialty Context

​Multi-Type Suggestions

​Real-Time Autocomplete

​Personalized Suggestions

​Domain-Specific Autocomplete

​Completion Modes

​Prefix Mode

​Substring Mode

​Fuzzy Mode

​Semantic Mode

​Balanced Mode

​Suggestion Types

​Exact Suggestions

​Fuzzy Suggestions

​Semantic Suggestions

​Phonetic Suggestions

​Abbreviation Suggestions

​User Context Optimization

​Physician Context

​Nurse Context

​Pharmacist Context

​Researcher Context

​Patient Context

​Student Context

​Performance Features

​Real-Time Optimization

​Intelligent Caching

​Progressive Enhancement

​Related Endpoints

Overview

Query Parameters

Response

Usage Examples

Basic Autocomplete

Medical Specialty Context

Multi-Type Suggestions

Real-Time Autocomplete

Personalized Suggestions

Domain-Specific Autocomplete

Completion Modes

Prefix Mode

Substring Mode

Fuzzy Mode

Semantic Mode

Balanced Mode

Suggestion Types

Exact Suggestions

Fuzzy Suggestions

Semantic Suggestions

Phonetic Suggestions

Abbreviation Suggestions

User Context Optimization

Physician Context

Nurse Context

Pharmacist Context

Researcher Context

Patient Context

Student Context

Performance Features

Real-Time Optimization

Intelligent Caching

Progressive Enhancement

Related Endpoints