Search Suggestions
Search suggestions
POST /indexes/{index_name}/recommendations/queries
Purpose
Help shoppers find relevant products faster by suggesting query terms as they type. Reduces zero-results and accelerates navigation to high-intent pages.
When to use
- Search bar suggestions on desktop and mobile
- Inline suggestions within site-wide navigation
Example uses
- Search as you type, show popular queries after typing in 2-3 characters
Example (cURL)
curl -X POST "https://ecom.marqo-ep.ai/api/v1/indexes/product-catalog/recommendations/queries" \
-H "x-marqo-index-id: ${MARQO_INDEX_ID}" \
-H "Content-Type: application/json" \
-d '{
"q": "iph",
"limit": 5
}'
Parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| q * | string | yes | Partial query text typed by the user. | "iph" |
| limit | integer | no | Max number of suggestions. Default 10. | 5 |
| userId | string | no | Optional user identifier for personalization. | "abc123" |
| sessionId | string | no | Optional session identifier. | "xyz789" |
| namespace ** | string | no | Restrict suggestions to a single sub-corpus (e.g. one language). Lowercase only; pattern ^[a-z0-9][a-z0-9_-]{0,63}$. When omitted, suggestions across all namespaces (including un-namespaced documents) are returned. | "fr" |
* If q is not provided (or an empty string), top limit queries will be returned.
** The namespace feature is being rolled out gradually. Please contact your accounts team to activate it for your index and to chat through which namespaces best fit your catalog.
Response (example)
{
"suggestions": [
{"suggestion": "iphone 15 case"},
{"suggestion": "iphone charger"},
{"suggestion": "iphone screen protector"},
{"suggestion": "iphone 14 pro"},
{"suggestion": "iphone accessories"}
]
}
Response fields
| Name | Type | Description |
|---|---|---|
| suggestions[].suggestion | string | The suggested query text. |
| suggestions[].namespace | string | Namespace the suggestion was indexed under. Omitted entirely for un-namespaced documents. |
Filtering by namespace
Pass namespace in the request body to restrict suggestions to a single sub-corpus. Useful when one storefront serves multiple languages or regions.
curl -X POST "https://ecom.marqo-ep.ai/api/v1/indexes/product-catalog/recommendations/queries" \
-H "x-marqo-index-id: ${MARQO_INDEX_ID}" \
-H "Content-Type: application/json" \
-d '{
"q": "iphone",
"limit": 3,
"namespace": "fr"
}'
Response (only suggestions indexed under fr are returned):
{
"suggestions": [
{"suggestion": "iphone coque", "namespace": "fr"},
{"suggestion": "iphone chargeur", "namespace": "fr"}
]
}
namespace is case-sensitive and lowercase only. Mixed-case values (e.g. "MyNamespace") return a 400 with a message suggesting the lowercased form. Whitespace, ., /, : and other special characters are rejected. When namespace is omitted from the request, suggestions from all namespaces (and un-namespaced documents, where the namespace field is omitted from the response item) are returned.