> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omophub.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Autocomplete

> Get real-time autocomplete suggestions for OMOP medical terminology searches with optional phonetic matching for typo-tolerant clinical lookups.

## Overview

This endpoint provides autocomplete functionality for medical terminology searches. It offers real-time suggestions as users type, helping them find the correct medical terms quickly. The endpoint supports both standard prefix matching and phonetic (Soundex) matching for handling common misspellings.

## Query Parameters

<ParamField query="query" type="string" required>
  Search query for autocompletion (minimum 2 characters, maximum 100)
</ParamField>

<ParamField query="vocabulary_ids" type="string">
  Filter suggestions to specific vocabularies (comma-separated)

  <br />

  **Examples**: `SNOMED`, `ICD10CM,LOINC`, `RXNORM`
</ParamField>

<ParamField query="domain_ids" type="string">
  Filter suggestions to specific domains (comma-separated)

  <br />

  **Examples**: `Condition`, `Drug,Procedure`
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number (1-based indexing)
</ParamField>

<ParamField query="page_size" type="integer" default="10">
  Number of suggestions to return per page (1-20)
</ParamField>

<ParamField query="algorithm" type="string" default="default">
  Matching algorithm to use

  <br />

  **Options**: `default`, `soundex`

  <br />

  Use `soundex` for phonetic matching to handle misspellings
</ParamField>

<ParamField query="vocab_release" type="string">
  Specific vocabulary release version (defaults to latest)
</ParamField>

## Response

<ResponseField name="suggestions" type="array">
  Array of autocomplete suggestions with concept details
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.omophub.com/v1/search/autocomplete?query=diab&page_size=5" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.omophub.com/v1/search/autocomplete",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      params={
          "query": "diab",
          "vocabulary_ids": "SNOMED,ICD10CM",
          "page_size": 10
      }
  )

  data = response.json()
  suggestions = data["suggestions"]
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.omophub.com/v1/search/autocomplete?query=diab&page_size=5',
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const suggestions = await response.json();
  ```

  ```r R theme={null}
  library(omophub)

  client <- OMOPHub$new()
  suggestions <- client$search$autocomplete("diab", page_size = 5)
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "suggestions": [
      {
        "concept_id": 201826,
        "concept_name": "Type 2 diabetes mellitus",
        "concept_code": "44054006",
        "vocabulary_id": "SNOMED",
        "domain_id": "Condition",
        "concept_class_id": "Clinical Finding",
        "standard_concept": "S",
        "score": 0.95
      },
      {
        "concept_id": 201254,
        "concept_name": "Type 1 diabetes mellitus",
        "concept_code": "46635009",
        "vocabulary_id": "SNOMED",
        "domain_id": "Condition",
        "concept_class_id": "Clinical Finding",
        "standard_concept": "S",
        "score": 0.92
      },
      {
        "concept_id": 443238,
        "concept_name": "Diabetic retinopathy",
        "concept_code": "4855003",
        "vocabulary_id": "SNOMED",
        "domain_id": "Condition",
        "concept_class_id": "Clinical Finding",
        "standard_concept": "S",
        "score": 0.88
      }
    ],
    "meta": {
      "query": "diab",
      "algorithm": "default",
      "total_suggestions": 3,
      "vocab_release": "2025.2"
    }
  }
  ```
</ResponseExample>

## Usage Examples

### Basic Autocomplete

Get suggestions for a partial query:

```bash theme={null}
curl -X GET "https://api.omophub.com/v1/search/autocomplete?query=asth&page_size=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Vocabulary-Filtered Autocomplete

Focus suggestions on specific vocabularies:

```bash theme={null}
curl -X GET "https://api.omophub.com/v1/search/autocomplete?query=hyper&vocabulary_ids=SNOMED,ICD10CM&page_size=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Domain-Filtered Autocomplete

Get suggestions only for specific domains:

```bash theme={null}
curl -X GET "https://api.omophub.com/v1/search/autocomplete?query=aspir&domain_ids=Drug&page_size=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Phonetic Matching (Soundex)

Use phonetic matching to handle misspellings:

```bash theme={null}
curl -X GET "https://api.omophub.com/v1/search/autocomplete?query=diabetis&algorithm=soundex&page_size=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

This will find "diabetes" even when spelled incorrectly as "diabetis".

## Algorithms

### Default Algorithm

* Standard prefix matching
* Fast and accurate for correctly spelled queries
* Best for real-time autocomplete UX

### Soundex Algorithm

* Phonetic matching based on pronunciation
* Handles common misspellings and typos
* Useful for voice-to-text input or uncertain spellings
* Example: "noomonia" matches "pneumonia"

## Performance Notes

* **Minimum query length**: 2 characters required
* **Response time**: Optimized for real-time use (\<100ms typical)
* **Caching**: Results are cached for 24 hours per vocabulary release
* **Rate limiting**: Standard rate limits apply

## Related Endpoints

* [Basic Search](/api-reference/search/basic-search) - Full-text search with filters
* [Similarity Search](/api-reference/search/semantic-search) - Find semantically similar concepts