# Autocomplete

Search suggestions

## Get search suggestions

> Returns search suggestions grouped by type (products and categories)\
> that match the provided search text. This endpoint is automatically\
> triggered as users type in the search field.\
> \
> \*\*How Autocomplete Works:\*\*\
> \
> When a search text is provided, the system queries Elasticsearch using\
> multiple match types to find the best matches:\
> \- Multi-match query across product search text fields\
> \- Phrase match for exact phrase matching\
> \- Phrase prefix match for partial phrase completion\
> \
> If \`ES\_MIN\_SCORE\_COEFFICIENT\` is greater than zero, a minimum score\
> threshold is calculated and applied to filter low-relevance results.\
> \
> The search query is then processed through sorting and pre-filtering\
> functions based on current configuration. After processing, the most\
> relevant 4 product results are returned. These 4 results represent\
> product IDs that are automatically displayed in the search interface.\
> \
> In addition to products, category suggestions are also generated. If\
> categories match the search text, up to 4 category suggestions are\
> returned and displayed at the top of the autocomplete results.\
> \
> \*\*Suggestion Details:\*\*\
> \
> Product suggestions include product name, URL, image, price, and retail\
> price. Category suggestions include category name, URL, and parent\
> category hierarchy showing the full category path.\
> \
> If no search text is provided, an empty list of suggestions is returned.\
> \
> \*\*Caching:\*\*\
> \
> Results are cached for optimal performance using a two-layer cache system: 540 seconds expiration\
> \
> The cache duration is configured to balance freshness with response speed.

```json
{"openapi":"3.1.0","info":{"title":"Search API - Product Discovery & Image Search","version":"1.0.0"},"tags":[{"name":"Autocomplete","description":"Search suggestions"}],"servers":[{"description":"Default commerce site","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce storefront hostname"}}}],"paths":{"/autocomplete/":{"get":{"tags":["Autocomplete"],"operationId":"getAutocompleteSuggestions","summary":"Get search suggestions","description":"Returns search suggestions grouped by type (products and categories)\nthat match the provided search text. This endpoint is automatically\ntriggered as users type in the search field.\n\n**How Autocomplete Works:**\n\nWhen a search text is provided, the system queries Elasticsearch using\nmultiple match types to find the best matches:\n- Multi-match query across product search text fields\n- Phrase match for exact phrase matching\n- Phrase prefix match for partial phrase completion\n\nIf `ES_MIN_SCORE_COEFFICIENT` is greater than zero, a minimum score\nthreshold is calculated and applied to filter low-relevance results.\n\nThe search query is then processed through sorting and pre-filtering\nfunctions based on current configuration. After processing, the most\nrelevant 4 product results are returned. These 4 results represent\nproduct IDs that are automatically displayed in the search interface.\n\nIn addition to products, category suggestions are also generated. If\ncategories match the search text, up to 4 category suggestions are\nreturned and displayed at the top of the autocomplete results.\n\n**Suggestion Details:**\n\nProduct suggestions include product name, URL, image, price, and retail\nprice. Category suggestions include category name, URL, and parent\ncategory hierarchy showing the full category path.\n\nIf no search text is provided, an empty list of suggestions is returned.\n\n**Caching:**\n\nResults are cached for optimal performance using a two-layer cache system: 540 seconds expiration\n\nThe cache duration is configured to balance freshness with response speed.","parameters":[{"$ref":"#/components/parameters/SearchTextParameter"}],"responses":{"200":{"description":"Autocomplete suggestions retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutocompleteResponse"}}}}}}}},"components":{"parameters":{"SearchTextParameter":{"name":"search_text","in":"query","description":"Search query text","required":false,"schema":{"type":"string"}}},"schemas":{"AutocompleteResponse":{"type":"object","description":"Autocomplete suggestions grouped by type","required":["groups"],"properties":{"groups":{"type":"array","description":"Suggestion groups","items":{"$ref":"#/components/schemas/SuggestionGroup"}}}},"SuggestionGroup":{"type":"object","description":"Group of suggestions of the same type","required":["suggestion_type","entries"],"properties":{"suggestion_type":{"type":"string","description":"Type of suggestions in this group","enum":["product","category"]},"entries":{"type":"array","description":"Suggestion entries","items":{"$ref":"#/components/schemas/SuggestionEntry"}}}},"SuggestionEntry":{"type":"object","description":"Individual search suggestion","required":["label","url","suggestion_type","extra"],"properties":{"label":{"type":"string","description":"Display label"},"url":{"type":"string","description":"URL to navigate to"},"suggestion_type":{"type":"string","description":"Type of suggestion","enum":["product","category"]},"extra":{"type":"object","description":"Additional suggestion data","properties":{"image":{"type":["string","null"],"format":"uri","description":"Product image URL (for product suggestions)"},"price":{"type":["string","null"],"description":"Product price (for product suggestions)"},"retail_price":{"type":["string","null"],"description":"Product retail price (for product suggestions)"},"product_type":{"type":"string","description":"Product type (for product suggestions)"},"parent_categories":{"type":"array","items":{"type":"string"},"description":"Parent category names (for category suggestions)"},"category_id":{"type":"integer","description":"Category identifier (for category suggestions)"}},"additionalProperties":true}}}}}}
```