Advanced Search

This guide covers advanced search features including snippets, typo tolerance, prefix matching, and other parameters for fine-tuning search behavior.

Snippets

Snippets return excerpted portions of field values with matching terms highlighted. They are useful for displaying search result previews with context around the matched terms.

Parameters

Parameter	Type	Default	Description
include_snippets	boolean	false	Enable snippet generation in the response
snippet_fields	array	all searchable	Fields to generate snippets for
full_snippet_fields	array	none	Fields that return their full value with highlights (no truncation)
snippet_prefix	string	<mark>	HTML tag inserted before matched terms
snippet_suffix	string	</mark>	HTML tag inserted after matched terms
snippet_token_limit	integer	30	Maximum number of tokens in each snippet

Example

curl -X POST https://api.seekora.ai/v1/search \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-store-secret" \
  -d '{
    "q": "waterproof hiking boots",
    "include_snippets": true,
    "snippet_fields": ["title", "description"],
    "full_snippet_fields": ["title"],
    "snippet_prefix": "<b>",
    "snippet_suffix": "</b>",
    "snippet_token_limit": 40
  }'

Response:

{
  "found": 56,
  "hits": [
    {
      "document": {
        "id": "prod_4510",
        "title": "TrailMaster Waterproof Hiking Boots",
        "description": "Built for rugged terrain, these waterproof hiking boots feature a Gore-Tex membrane, Vibram outsole, and reinforced toe cap for all-day comfort on the trail."
      },
      "snippets": {
        "title": "TrailMaster <b>Waterproof</b> <b>Hiking</b> <b>Boots</b>",
        "description": "...these <b>waterproof</b> <b>hiking</b> <b>boots</b> feature a Gore-Tex membrane, Vibram outsole, and reinforced toe cap..."
      }
    }
  ]
}

Typo Tolerance

Seekora automatically handles typos so that queries like "runnign shoes" still return relevant results. You can tune how aggressively typos are corrected.

Parameters

Parameter	Type	Default	Description
typo_max	integer	2	Maximum number of typos allowed per word
typo_min_len_1	integer	4	Minimum word length required to allow 1 typo
typo_min_len_2	integer	7	Minimum word length required to allow 2 typos

Example

curl -X POST https://api.seekora.ai/v1/search \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-store-secret" \
  -d '{
    "q": "runnign shoess",
    "typo_max": 2,
    "typo_min_len_1": 4,
    "typo_min_len_2": 7
  }'

With these defaults, "runnign" (7 characters) allows up to 2 typos, and "shoess" (6 characters) allows up to 1 typo. Set typo_max to 0 to disable typo tolerance entirely.

Prefix and Infix Matching

prefix_mode

Controls whether partial word matches (prefix matching) are enabled. This is the foundation of search-as-you-type behavior.

Value	Description
always	Always match prefixes, even if exact matches exist
fallback	Only match prefixes when no exact matches are found
off	Disable prefix matching

curl -X POST https://api.seekora.ai/v1/search \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-store-secret" \
  -d '{
    "q": "sneak",
    "prefix_mode": "always"
  }'

This matches "sneaker", "sneakers", "sneakerhead", and so on.

infix_mode

Enables matching within words, not just at the beginning. Useful for SKU or product code searches.

{
  "q": "4501",
  "infix_mode": "always"
}

This would match a product with SKU "BOOT-4501-BLK" because "4501" appears inside the value.

Strict Matching

require_all_terms

When set to true, every term in the query must appear in the document for it to be considered a match. By default, documents matching a subset of query terms may be returned (ranked lower).

curl -X POST https://api.seekora.ai/v1/search \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-store-secret" \
  -d '{
    "q": "red leather handbag",
    "require_all_terms": true
  }'

Only documents containing all three terms -- "red", "leather", and "handbag" -- will be returned.

exact_match_boost

Boosts documents where a field value is an exact match to the query, pushing them to the top of the results.

{
  "q": "Air Max 90",
  "exact_match_boost": true
}

A product titled exactly "Air Max 90" will rank above "Air Max 90 Premium Edition".

Widget Mode

Use widget_mode to request a lightweight response optimized for autocomplete widgets and search overlays. This typically returns fewer fields and a smaller payload.

curl -X POST https://api.seekora.ai/v1/search \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-store-secret" \
  -d '{
    "q": "blue dre",
    "widget_mode": true,
    "per_page": 5,
    "prefix_mode": "always"
  }'

Inline Suggestions

include_suggestions

Returns query suggestions alongside search results. Useful for showing "Did you mean..." or autocomplete dropdown entries.

{
  "q": "jackt",
  "include_suggestions": true
}

Response includes a suggestions field:

{
  "found": 23,
  "hits": [ ... ],
  "suggestions": [
    { "text": "jacket", "score": 0.95 },
    { "text": "jackets", "score": 0.90 }
  ]
}

Presets

preset_name

Apply a saved search preset that bundles multiple parameters together. Presets are configured in your Seekora dashboard and referenced by name.

{
  "q": "shoes",
  "preset_name": "collection_page_defaults"
}

Parameters in the request body override values from the preset.

Caching

cache_results

Enable server-side caching for identical queries. Cached results are returned faster and do not count against your search quota for repeated requests within the cache window.

{
  "q": "best sellers",
  "cache_results": true
}

Search Rules

apply_rules

Enable or disable search rules (merchandising rules configured in the dashboard). Rules can pin products, boost categories, or inject banners for specific queries.

{
  "q": "sale",
  "apply_rules": true
}

Set to false to bypass all rules for debugging or testing.

Additional Parameters

Parameter	Type	Description
analytics_tags	array of strings	Tags attached to this search event for analytics segmentation (e.g., ["homepage", "autosuggest"])
stopword_sets	array of strings	Named stopword sets to apply, removing common words from the query before matching
synonym_sets	array of strings	Named synonym sets to apply, expanding the query with equivalent terms
search_timeout_ms	integer	Maximum time in milliseconds the search engine will spend on the query before returning partial results

Example with Multiple Advanced Parameters

curl -X POST https://api.seekora.ai/v1/search \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-store-secret" \
  -d '{
    "q": "organic cotton hoodie",
    "filter_by": "in_stock:true && price:[30..120]",
    "sort_by": "popularity:desc",
    "per_page": 20,
    "include_snippets": true,
    "snippet_fields": ["title", "description"],
    "typo_max": 1,
    "prefix_mode": "fallback",
    "require_all_terms": false,
    "exact_match_boost": true,
    "synonym_sets": ["apparel_synonyms"],
    "stopword_sets": ["english_default"],
    "analytics_tags": ["collection_page", "organic"],
    "apply_rules": true,
    "cache_results": true,
    "search_timeout_ms": 500
  }'

This query combines filtering, sorting, snippets, typo tolerance, synonym expansion, and caching in a single request.