Query Suggestions

The Query Suggestions API provides autocomplete functionality for your search interface, including suggestions, categories, facets, filtered tabs, and dropdown recommendations.

Basic Usage

By default getSuggestions() returns an array of suggestion hits. Use returnFullResponse: true to get the full response with extensions (dropdown recommendations, filtered_tabs).

const suggestions = await client.getSuggestions('lap', {
  hitsPerPage: 5,
});

console.log(suggestions);
// ['laptop', 'laptop bag', 'laptop stand', 'laptop sleeve', 'laptop charger']

Options Reference

Option	Type	Default	Description
`hitsPerPage`	number	5	Number of suggestions to return
`page`	number	0	Page number (zero-indexed)
`analytics_tags`	string \| string[]	-	Tags for analytics
`tags_match_mode`	'any' \| 'all'	'any'	How to match tags
`include_categories`	boolean	false	Include category suggestions
`include_facets`	boolean	false	Include facet suggestions
`max_categories`	number	3	Max categories to return
`max_facets`	number	5	Max facets to return
`min_popularity`	number	1	Minimum popularity threshold
`time_range`	'7d' \| '30d' \| '90d'	'30d'	Time range for suggestions
`disable_typo_tolerance`	boolean	false	Disable typo tolerance
`include_dropdown_recommendations`	boolean	false	Include rich recommendations
`include_dropdown_product_list`	boolean	true	Include product hits in dropdown
`include_filtered_tabs`	boolean	true	Include filtered tab results
`include_empty_query_recommendations`	boolean	false	Trending suggestions for empty query
`filtered_tabs`	FilteredTab[]	-	Tab definitions sent in request
`returnFullResponse`	boolean	false	Return full response with extensions

Simple Suggestions

Get a list of query suggestions as strings:

const suggestions = await client.getSuggestions('laptop', {
  hitsPerPage: 10,
});
// Returns: string[]

Include category and facet suggestions for richer autocomplete:

const suggestions = await client.getSuggestions('laptop', {
  hitsPerPage: 10,
  include_categories: true,
  include_facets: true,
  max_categories: 5,
  max_facets: 5,
});

Get rich dropdown recommendations including trending searches, top searches, related searches, and popular brands:

import { QuerySuggestionsFullResponse } from '@seekora-ai/search-sdk';

const response = await client.getSuggestions('lap', {
  include_dropdown_recommendations: true,
  returnFullResponse: true,
}) as QuerySuggestionsFullResponse;

console.log('Suggestions:', response.suggestions);
console.log('Trending:', response.extensions?.trending_searches);
console.log('Top Searches:', response.extensions?.top_searches);
console.log('Related:', response.extensions?.related_searches);
console.log('Popular Brands:', response.extensions?.popular_brands);

Full Response Structure

interface QuerySuggestionsFullResponse {
  suggestions: any[];              // Suggestion hits
  results?: any[];                 // Full results array (first = suggestions, second = extensions)
  extensions?: {
    trending_searches?: any[];     // Trending search queries
    top_searches?: any[];          // Top search queries
    related_searches?: any[];      // Related search queries
    popular_brands?: any[];        // Popular brands
    filtered_tabs?: any[];         // Filtered tabs with products
  };
  raw?: any;                       // Raw API response
}

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.

const response = await client.getSuggestions('laptop', {
  include_filtered_tabs: true,
  filtered_tabs: [
    { id: 'all', label: 'All', enabled: true, limit: 4 },
    { id: 'electronics', label: 'Electronics', enabled: true, limit: 4, filters: { category: 'Electronics' } },
    { id: 'accessories', label: 'Accessories', enabled: true, limit: 4, filters: { category: 'Accessories' } },
    { id: 'sale', label: 'On Sale', enabled: true, limit: 4, filters: { on_sale: 'true' } },
  ],
  returnFullResponse: true,
}) as QuerySuggestionsFullResponse;

// Each tab has its products and count
response.extensions?.filtered_tabs?.forEach(tab => {
  console.log(`${tab.label}: ${tab.nb_hits} results, ${tab.products.length} shown`);
});

FilteredTab Interface

// Request tab definition
interface FilteredTab {
  id?: string;      // Unique tab identifier
  label: string;    // Display label
  enabled?: boolean; // Whether tab is active (default true)
  limit?: number;   // Max products per tab
  filters?: Record<string, string>;  // Key-value filter criteria
}

// Response tab data
interface FilteredTabResponse {
  id: string;
  label: string;
  products: Array<{
    id: string;
    title: string;
    url: string;
    metadata: Record<string, any>;
  }>;
  nb_hits: number;
  processing_time_ms: number;
}

Suggestions Defaults

Set default options for all getSuggestions() calls when initializing the client. Per-call options override these defaults.

const client = new SeekoraClient({
  storeId: 'your-store-id',
  readSecret: 'your-read-secret',
  suggestionsDefaults: {
    hitsPerPage: 8,
    include_dropdown_recommendations: true,
    include_dropdown_product_list: true,
    include_filtered_tabs: true,
    time_range: '7d',
  },
});

// These calls automatically use the defaults above
const simple = await client.getSuggestions('lap');
const full = await client.getSuggestions('lap', { returnFullResponse: true });

Empty Query Suggestions

Show trending or popular suggestions when the search box is empty or first focused:

const trending = await client.getSuggestions('', {
  include_empty_query_recommendations: true,
  include_filtered_tabs: true,
  filtered_tabs: [
    { id: 'trending', label: 'Trending', enabled: true, limit: 8 },
  ],
  returnFullResponse: true,
}) as QuerySuggestionsFullResponse;

Time-based Suggestions

Get suggestions based on recent popularity:

// Last 7 days — freshest suggestions for fast-moving inventory
const recentSuggestions = await client.getSuggestions('laptop', {
  time_range: '7d',
  hitsPerPage: 10,
});

// Last 30 days (default)
const monthlySuggestions = await client.getSuggestions('laptop', {
  time_range: '30d',
  hitsPerPage: 10,
});

// Last 90 days — broadest coverage
const quarterlySuggestions = await client.getSuggestions('laptop', {
  time_range: '90d',
  hitsPerPage: 10,
});

Popularity Threshold

Filter suggestions by minimum popularity:

const popularSuggestions = await client.getSuggestions('laptop', {
  min_popularity: 10,  // Only show suggestions with 10+ searches
  hitsPerPage: 10,
});

Complete Example

Here's a complete example of implementing a rich autocomplete dropdown:

import { SeekoraClient, QuerySuggestionsFullResponse } from '@seekora-ai/search-sdk';

const client = new SeekoraClient({
  storeId: 'your-store-id',
  readSecret: 'your-read-secret',
  suggestionsDefaults: {
    include_dropdown_recommendations: true,
    include_filtered_tabs: true,
  },
});

async function getAutocompleteData(query: string) {
  // Don't fetch for very short queries
  if (query.length < 2) {
    return null;
  }

  const response = await client.getSuggestions(query, {
    hitsPerPage: 8,
    include_categories: true,
    filtered_tabs: [
      { id: 'all', label: 'All', enabled: true, limit: 4 },
      { id: 'products', label: 'Products', enabled: true, limit: 4, filters: { type: 'product' } },
      { id: 'categories', label: 'Categories', enabled: true, limit: 4, filters: { type: 'category' } },
    ],
    returnFullResponse: true,
  }) as QuerySuggestionsFullResponse;

  return {
    suggestions: response.suggestions,
    trending: response.extensions?.trending_searches || [],
    related: response.extensions?.related_searches || [],
    tabs: response.extensions?.filtered_tabs || [],
  };
}

// React example usage
function SearchInput() {
  const [query, setQuery] = useState('');
  const [autocomplete, setAutocomplete] = useState(null);

  useEffect(() => {
    const timer = setTimeout(async () => {
      const data = await getAutocompleteData(query);
      setAutocomplete(data);
    }, 300); // Debounce

    return () => clearTimeout(timer);
  }, [query]);

  return (
    <div>
      <input
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        placeholder="Search..."
      />
      {autocomplete && (
        <div className="dropdown">
          {/* Render suggestions, trending, tabs, etc. */}
        </div>
      )}
    </div>
  );
}

Configuration

You can configure query suggestions at the store level:

// Get current configuration
const config = await client.getSuggestionsConfig();
console.log('Max suggestions:', config.max_suggestions);
console.log('Minimum letters:', config.minimum_letters);

// Update configuration (requires write secret)
await client.updateQuerySuggestionsConfig({
  enabled: true,
  max_suggestions: 20,
  minimum_letters: 2,
  enable_personalization: false,
});

Next Steps

Analytics - Track suggestion interactions
UI SDK - Pre-built suggestion components

Basic Usage​

Options Reference​

Simple Suggestions​

Suggestions with Categories and Facets​

Dropdown Recommendations​

Full Response Structure​

Filtered Tabs​

FilteredTab Interface​

Suggestions Defaults​

Empty Query Suggestions​

Time-based Suggestions​

Popularity Threshold​

Complete Example​

Configuration​

Next Steps​