> For the complete documentation index, see [llms.txt](https://apidocs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.akinon.com/commerce/autocomplete.md).

# Autocomplete

The Autocomplete feature allows you to retrieve the most relevant products and categories based on a user's search query. This guide outlines how to use this feature to enhance search functionality in your application. By sending a `GET` request with a specific search text to the provided endpoint, you can retrieve a structured response containing product and category suggestions. This guide also provides insights into filtering options and customization settings to optimize search results for your application.

### `GET` Most Relevant Products via Searched Text

Returns the most relevant products and categories upon searching the word sent with ‘search\_text.’

**Path:** `https://{commerce_url}/autocomplete/?search_text=<SEARCH_TEXT>`

**Example Response**

```json
{
"groups": [
    	{
        	"entries": [
            	{
                	"label": "Electro Guitar",
                	"url": "/electro-guitar/",
                	"suggestion_type": "category",
                	"extra": {
                    	"category_id": 3,
                    	"parent_categories": [
                        	"Music"
                    	]
                	}
            	},
            	…
        	],
        	"suggestion_type": "Category"
    	},
    	{
        	"entries": [
            	{
                	"label": "Bass Guitar",
                	"url": "/bass-guitar/",
                	"suggestion_type": "product",
                	"extra": {
                    	"image": null,
                    	"retail_price": 249.98,
                    	"product_type": 1,
                    	"price": 99.99,
                    	"attributes": {}
                	}
            	},
            	…
        	],
        	"suggestion_type": "Product"
    	}
	]
}
```

Filtering is limited to the first four words of the search text; any additional words are disregarded.

Additionally, there are customizable settings available to refine the filtering of the most relevant products and categories. These settings are evaluated using the `and` logical operator in conjunction with the search text. The following sections provide insights into these settings.

#### Group Size

Each suggestion group returns at most `AUTOCOMPLETE_GROUP_SIZE` entries — a dynamic setting with a default of `4` and an allowed range of `1`–`20`. The cap applies to the product group and the category group independently, and a group returns fewer entries when there are fewer matches.

#### Product Attributes

Product suggestions can carry product attributes under `extra.attributes`, for example to send brand and category with search suggestion analytics events. List the attribute keys in the `AUTOCOMPLETE_PRODUCT_ATTRIBUTES` dynamic setting. It defaults to an empty list, in which case `extra.attributes` is `{}`.

Values are keyed by attribute key:

* Single-value attributes with an option label, such as dropdowns, return the label in the request language.
* Multi-value attributes return the list of stored option values, not their labels.
* Other attributes return their stored value, translated for localizable attributes.
* An attribute the product does not have returns `null`.

**Example**

`AUTOCOMPLETE_PRODUCT_ATTRIBUTES`:

```json
["integration_marka", "integration_kategori"]
```

`extra` of a product suggestion:

```json
{
    "image": null,
    "retail_price": 249.98,
    "product_type": 1,
    "price": 99.99,
    "attributes": {
        "integration_marka": "Fender",
        "integration_kategori": "Bass Guitars"
    }
}
```

#### Product Filtering

For products, the provided search text is compared to the `name` field as an exact match and the `search_text` field as a prefix match, utilizing the `or` logical operator.

#### Category Filtering

When filtering categories, the provided search text is divided by spaces, and each word is compared to the `name` field of the categories using a case-insensitive contain lookup operator. The results are then evaluated with the `and` logical operator.

**Custom Settings**

The `CATEGORY_PRE_FILTER` is used to configure Django Q object or its combination.

**Example**

```py
CATEGORY_PRE_FILTER = Q(path__startswith='000100010') | Q(order=1)
```

In this example, the system will return categories that match the search text and meet one of two conditions: either the path starts with `000100010` or the order equals `1`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://apidocs.akinon.com/commerce/autocomplete.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
