Autocomplete

What autocomplete does

As the shopper types, the search box asks Zaproo for completions: "sams" answers "samsung tv", "samsung", "samsung soundbar". Each index has its own suggestion index, built from three sources:

• Queries that shoppers searched on your store and that found products.
• Field values of the fields you choose, such as every brand.
• Custom suggestions you add by hand, such as a campaign name.

Suggestions only ever come from that suggestion index, so a suggest request stays fast and never touches your products. The index is rebuilt every hour.

In the cabinet, open an index and then Autocomplete. The page has four parts: Settings, Suggestion index (the rebuild button), Preview and Custom suggestions.

Settings

Each index has one suggest config. The first time anyone opens it, in the cabinet or with GET, it is created with the defaults below and a new suggest key.

Autocomplete settings with a live preview

PUT replaces the whole config, so send every setting. A field that is not a keyword field with doc values, or a searchProfileKey that no profile of this index has, answers 400 SUGGEST_CONFIG_INVALID with one issue per problem.

Settings that shape the answer (limit, fuzzy, defaultSuggestions, facetHints, searchProfileKey) apply to the very next suggest request. Settings that shape the build (fields, minQueryCount, lookbackDays) apply with the next build: wait for the hourly one or press Rebuild now.

curl -X PUT https://api.zaproo-search.com/v1/projects/$PROJECT_ID/indices/$INDEX_ID/suggestions/config \
  -H "Authorization: Bearer $ZS_KEY" -H "Content-Type: application/json" \
  -d '{
    "limit": 8,
    "fuzzy": true,
    "defaultSuggestions": {"enabled": true, "count": 5},
    "facetHints": true,
    "searchProfileKey": "PROFILE_KEY",
    "fields": ["brand"],
    "minQueryCount": 2,
    "lookbackDays": 30
  }'

Custom suggestions

A custom suggestion is a text you want offered, with a weight and an optional facet hint. Use it for campaign names, new product lines nobody has searched for yet, or to push one completion above the rest.

curl -X POST https://api.zaproo-search.com/v1/projects/$PROJECT_ID/indices/$INDEX_ID/suggestions/custom \
  -H "Authorization: Bearer $ZS_KEY" -H "Content-Type: application/json" \
  -d '{"text": "black friday deals", "weight": 20, "facetHint": {"key": "category", "value": "Deals"}}'

An index holds up to 1000 custom suggestions; one more answers 409 SUGGESTION_LIMIT_REACHED. A new or deleted custom suggestion shows up with the next build.

Weight

A query scores log1p(searches), the natural log of one plus the number of visitors who searched it. A query searched by 100 visitors scores about 4.6, by 10,000 about 9.2. Your weight is compared with that number directly:

When a custom suggestion has the same text as a query or a field value, the custom one wins: its weight and its hint are used.

Rebuilding

A worker rebuilds every index that has a suggest config once an hour. It reads the queries of the lookback window, the values of the configured fields and the custom suggestions, writes a new suggestion index and swaps it in, so suggest keeps answering during the build. Queries that are a misspelling of a far more popular one ("samsnug tv" next to "samsung tv") are dropped.

Press Rebuild now after adding custom suggestions, changing the field list or uploading a new catalog. It queues a task; the cabinet shows its status and, when it is done, how many suggestions the new index holds.

curl -X POST https://api.zaproo-search.com/v1/projects/$PROJECT_ID/indices/$INDEX_ID/suggestions/rebuild \
  -H "Authorization: Bearer $ZS_KEY"
# 202 {"taskId": "..."}

Poll GET /v1/projects/:projectId/tasks/:taskId like any other task. The hourly schedule skips an index whose build is already queued or running.

The suggest request

The storefront calls one route with the suggest key. The body holds only q, up to 100 characters.

curl -X POST https://api.zaproo-search.com/v1/suggest/$SUGGEST_KEY \
  -H "Authorization: Bearer $ZS_KEY" -H "Content-Type: application/json" \
  -d '{"q": "sams"}'

Suggest completions for "sams" on the products index.

{
  "suggestions": [
    {"text": "samsung tv", "kind": "query", "facetHint": {"key": "category", "value": "TV"}},
    {"text": "Samsung", "kind": "field", "facetHint": {"key": "brand", "value": "Samsung"}},
    {"text": "samsung soundbar", "kind": "query", "facetHint": null}
  ],
  "searchProfileKey": "PROFILE_KEY",
  "tookMs": 4
}

A suggest key of another project, or of an index outside the key's index scope, answers 404 SUGGEST_NOT_FOUND. Before the first build, every request answers an empty list. Suggest has its own rate limit, twice that of search, because it fires on every keystroke: 1200 requests a minute per key and 2400 per client IP.

The cabinet's Preview uses a second route that takes the index id instead of the suggest key and answers the same:

Call the public route from the shopper's browser with a public key whose allowed origins list your shop's domains. From a server, use a secret key with read access, scoped to the index: a server sends no Origin header, so a public key answers 403 ORIGIN_NOT_ALLOWED there.

Suggestion kinds

Queries are shown as they are stored, lowercased with spaces collapsed. Field values and custom suggestions keep the spelling you gave them.

Common mistakes

• No suggestions on a new store. Queries need searches first. Add the brand field under Field values and a few custom suggestions, then press Rebuild now.
• A change to the field list does nothing. Field values, the minimum count and the lookback only apply with the next build.
• Suggestions from tests and the playground. Searches with a saved profile from the cabinet playground are logged like storefront searches. Keep minQueryCount at 2 or more and send a sessionId from the storefront, so a handful of test searches from one person stays out.

Related

• Search analytics
• Search profiles
• MCP tools