Query Suggestions

Query suggestions power autocomplete and type-ahead experiences by returning popular and relevant search terms as users type. The suggestions API draws from your store's historical search data, trending queries, and personalization signals to surface the most useful completions.

Authentication

All suggestions endpoints require read credentials:

Header	Description
`x-storeid`	Your store identifier
`x-storesecret`	Read-only API secret

Fetching Suggestions

GET Request

The simplest way to fetch suggestions is with a GET request and query parameters.

curl -X GET "https://api.seekora.ai/v1/suggestions/queries?q=lap&hitsPerPage=5" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-read-secret"

The q and query parameters are interchangeable. Use whichever you prefer.

POST Request

For more complex queries with filtering and analytics options, use the POST endpoint with a JSON body.

curl -X POST "https://api.seekora.ai/v1/suggestions/queries" \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-read-secret" \
  -d '{
    "query": "lap",
    "hitsPerPage": 5,
    "page": 0,
    "include_categories": true,
    "include_facets": true,
    "max_categories": 3,
    "max_facets": 5,
    "min_popularity": 10,
    "time_range": "30d",
    "analytics_tags": ["homepage", "desktop"],
    "tags_match_mode": "any"
  }'

Example Response

{
  "suggestions": [
    { "query": "laptop", "popularity": 1842 },
    { "query": "laptop bag", "popularity": 674 },
    { "query": "laptop stand", "popularity": 312 },
    { "query": "laptop sleeve", "popularity": 205 },
    { "query": "lap desk", "popularity": 118 }
  ],
  "categories": [
    { "name": "Electronics", "count": 245 },
    { "name": "Accessories", "count": 89 },
    { "name": "Office Supplies", "count": 34 }
  ],
  "facets": [
    { "field": "brand", "values": ["Apple", "Dell", "Lenovo", "HP", "ASUS"] }
  ],
  "meta": {
    "query": "lap",
    "page": 0,
    "hitsPerPage": 5,
    "totalHits": 12
  }
}

Parameters Reference

Core Parameters

Parameter	Type	Default	Description
`q` / `query`	string	`""`	The partial search query to complete
`hitsPerPage`	integer	`10`	Number of suggestions to return per page
`page`	integer	`0`	Zero-based page index for pagination

Enrichment Options

These parameters control what additional data is returned alongside query suggestions.

Parameter	Type	Default	Description
`include_categories`	boolean	`false`	Return matching category names
`include_facets`	boolean	`false`	Return facet values relevant to the suggestions
`include_dropdown_recommendations`	boolean	`false`	Include product recommendations for dropdown display
`include_dropdown_product_list`	boolean	`true`	Include a product list tailored for dropdown UI
`include_filtered_tabs`	boolean	`true`	Return tab groupings based on filtered results
`include_empty_query_recommendations`	boolean	`false`	Return trending/popular suggestions when the query is empty

Filtering and Tuning

Parameter	Type	Default	Description
`max_categories`	integer	`5`	Maximum number of categories to return
`max_facets`	integer	`5`	Maximum number of facet fields to return
`min_popularity`	integer	`0`	Exclude suggestions below this popularity threshold
`time_range`	string	`"30d"`	Time window for popularity data. Accepted values: `7d`, `30d`, `90d`
`disable_typo_tolerance`	boolean	`false`	When `true`, only return exact prefix matches
`analytics_tags`	string[]	`[]`	Filter suggestions by analytics tags
`tags_match_mode`	string	`"any"`	How to match tags: `any` (OR) or `all` (AND)
`filtered_tabs`	array	`null`	Custom tab definitions for filtered grouping (see below)

Filtered Tabs

Filtered tabs let you show categorized result groups (e.g., "All", "Clothing", "Accessories") alongside suggestions. You can send tab definitions directly in the request — no pre-configuration needed.

POST Request with Filtered Tabs

curl -X POST "https://api.seekora.ai/v1/suggestions/queries" \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-read-secret" \
  -d '{
    "query": "shirt",
    "hitsPerPage": 5,
    "include_filtered_tabs": true,
    "filtered_tabs": [
      { "id": "all", "label": "All Results", "enabled": true, "limit": 4 },
      { "id": "clothing", "label": "Clothing", "enabled": true, "limit": 4, "filters": { "category": "Clothing" } },
      { "id": "sale", "label": "On Sale", "enabled": true, "limit": 4, "filters": { "on_sale": "true" } }
    ]
  }'

GET Request with Filtered Tabs

For GET requests, pass filtered_tabs as a URL-encoded JSON string:

curl -G "https://api.seekora.ai/v1/suggestions/queries" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-read-secret" \
  --data-urlencode "query=shirt" \
  --data-urlencode "include_filtered_tabs=true" \
  --data-urlencode 'filtered_tabs=[{"id":"all","label":"All Results","enabled":true,"limit":4}]'

Response Structure

When filtered tabs are requested, the response contains two result objects:

Suggestions result — query suggestion hits with metadata
Recommendations result — contains filtered_tabs in its extensions

{
  "results": [
    {
      "hits": [ ... ],
      "extensions": { "metadata": { ... }, "queryCategorization": {} }
    },
    {
      "hits": [ ... ],
      "extensions": {
        "filtered_tabs": [
          {
            "id": "all",
            "label": "All Results",
            "products": [
              { "id": "prod_1", "title": "Classic Oxford Shirt", "url": "...", "metadata": { ... } }
            ],
            "nb_hits": 42,
            "processing_time_ms": 12
          },
          {
            "id": "clothing",
            "label": "Clothing",
            "products": [ ... ],
            "nb_hits": 38,
            "processing_time_ms": 8
          }
        ],
        "top_searches": [ ... ],
        "trending_searches": [ ... ],
        "related_searches": [ ... ],
        "popular_brands": [ ... ]
      }
    }
  ]
}

Tab Configuration Fields

Field	Type	Required	Description
`id`	string	No	Unique tab identifier
`label`	string	Yes	Display label for the tab
`enabled`	boolean	No	Whether this tab is active (default `true`)
`limit`	integer	No	Maximum products to return per tab
`filters`	object	No	Key-value filter criteria for this tab

Personalization

Include user identity headers to receive personalized suggestions based on past search and click behavior.

Header	Description
`x-user-id`	Logged-in user identifier
`x-anon-id`	Anonymous visitor identifier (cookie or device ID)
`x-session-id`	Current browsing session identifier

curl -X GET "https://api.seekora.ai/v1/suggestions/queries?q=sho&hitsPerPage=5" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-read-secret" \
  -H "x-user-id: user_8294" \
  -H "x-session-id: sess_a1b2c3"

When personalization headers are provided, the API boosts suggestions that align with the user's recent activity. For example, a user who frequently searches for running gear would see "shoes running" ranked higher than "shoes formal" for the query "sho".

Suggestions Configuration

Retrieve your store's current suggestions configuration and limits.

curl -X GET "https://api.seekora.ai/v1/suggestions/config" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-read-secret"

Example Response

{
  "max_suggestions": 20,
  "max_categories": 10,
  "max_facets": 10,
  "supported_time_ranges": ["7d", "30d", "90d"],
  "personalization_enabled": true,
  "typo_tolerance_enabled": true,
  "min_query_length": 1
}

Use this endpoint to dynamically adapt your frontend autocomplete component to the limits and features available for your store.

Implementation Tips

Debounce requests in your frontend. A 150-300ms debounce on keystrokes prevents unnecessary API calls and improves perceived performance.
Start with include_categories: true to build a richer autocomplete dropdown that lets users jump directly to category pages.
Use min_popularity to filter out rare or low-quality suggestions that may not lead to relevant results.
Set time_range: "7d" for stores with rapidly changing inventory to keep suggestions fresh and relevant.
Empty query suggestions can power a "trending searches" section by setting include_empty_query_recommendations: true with an empty q parameter.

Authentication​

Fetching Suggestions​

GET Request​

POST Request​

Example Response​

Parameters Reference​

Core Parameters​

Enrichment Options​

Filtering and Tuning​

Filtered Tabs​

POST Request with Filtered Tabs​

GET Request with Filtered Tabs​

Response Structure​

Tab Configuration Fields​

Personalization​

Suggestions Configuration​

Example Response​

Implementation Tips​

Authentication

Fetching Suggestions

GET Request

POST Request

Example Response

Parameters Reference

Core Parameters

Enrichment Options

Filtering and Tuning

Filtered Tabs

POST Request with Filtered Tabs

GET Request with Filtered Tabs

Response Structure

Tab Configuration Fields

Personalization

Suggestions Configuration

Example Response

Implementation Tips