Search Suggestions
Search suggestions
POST /api/v1/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 | Accepted for consistency with the other recommendation endpoints, but currently has no effect: suggestions are not personalised. | "abc123" |
| sessionId | string | no | Accepted but currently has no effect (see userId). | "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" |
* q must be present. Send an empty string to get the top limit queries. The endpoint uses strict validation: any unrecognised parameter returns a 400 error.
limit must be a whole, positive number. The API does not check this itself: a fractional, zero or negative value is passed on and rejected upstream with Suggestions failed: <reason>.
** 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. |
| suggestions[].metadata | object | Extra attributes stored with the suggestion. Only present when suggestion metadata is enabled for your index (contact Marqo) and the suggestion has metadata. |
| Header | Description |
|---|---|
x-marqo-cache-hit | true when the response was served from cache, false otherwise. |
Errors
Error responses have the body {"error": "<message>"}.
| Status | Message |
|---|---|
| 400 | Parameter 'q' is required and must be a string |
| 400 | Unrecognized param(s): '<name>' for any parameter not listed above |
| 400 | Suggestions failed: <reason> when the underlying request is rejected (for example, an invalid namespace) |
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.