Autocomplete

What autocomplete does

As the shopper types, the search box asks Zaproo for completions: "ta" answers "tape", "duct tape", "office tape". Each index has its own suggestion index, built from three sources:

• Popular searches: 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 suggestion index is rebuilt every hour.

To set it up, open an index and click Autocomplete in the menu. Only organization owners and admins can change the settings; other members see them read-only.

The Try it panel shows what the search box suggests now

The page has these parts, in this order:

1. Try it: what the search box suggests right now.
2. Suggest key and Suggestion index, with the Rebuild now button.
3. Where suggestions come from: the settings that shape the build.
4. How suggestions behave: the settings that shape each answer.
5. Custom suggestions: the texts you add yourself.

Settings under Where suggestions come from apply with the next build, so click Rebuild now after you save them. Settings under How suggestions behave apply to the very next request.

Try it

Type in the Try it box as a shopper would. The list shows each suggestion with its source (Popular search, Field value or Custom) and, under it, the category it points at, for example "in Tapes>Duct tapes". Leave the box empty to see what a shopper gets on clicking into the search box.

The panel always uses the saved settings. While you have unsaved changes it says so: click Save settings first, and click Rebuild now when the change concerns the sources.

If the list says No suggestions, the suggestion index has not been built since the last change, or none of the sources holds anything yet. See Common mistakes.

Suggest key and suggestion index

Rebuilding

A worker rebuilds the suggestion index of every index that has autocomplete settings once an hour. It reads the popular searches of the lookback window, the values of the chosen 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 ("tpae" next to "tape") are dropped.

Click Rebuild now to see a change at once, for example after you add custom suggestions, change the field list or upload a new catalog. The button starts a task. While it runs, the line next to it shows Rebuild with the task status, and when it is done, how many suggestions the new index holds. The Try it panel then refreshes by itself.

With the API, start a rebuild like this:

curl -X POST https://api.search.zaproo.cloud/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. Over MCP, the agent calls rebuild_suggestions.

Where suggestions come from

Three sources are merged. When two of them hold the same text, a custom suggestion wins, then a popular search, then a field value. Change the settings below, click Save settings at the bottom of the form, then Rebuild now.

Popular searches

Queries your shoppers searched that found products. Two settings decide which queries qualify: Searched by at least some number of visitors, In the last some number of days. Only shopper traffic counts: searches from the cabinet, from MCP, from excluded IP addresses, from crawlers and with analytics: false are left out. See What counts as real traffic.

The last row, Custom suggestions, counts the texts you added and links to the Custom suggestions section below.

How suggestions behave

These settings apply to the next suggest request, without a rebuild. Change them and click Save settings.

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.

To add one, go to Custom suggestions at the bottom of the Autocomplete page:

1. Enter the Text, for example Black Friday packaging deals.
2. Set the Weight. The default, 10, ranks above most popular searches. See Weight.
3. Optionally pick a Facet hint field and enter a Facet hint value, for example categories and Deals.
4. Click Add. The suggestion appears in the table.
5. Click Rebuild now at the top of the page. A new or deleted custom suggestion only shows up after the next build.

To delete one, click the bin icon in its row. It is deleted at once, without a confirmation.

With the API or MCP

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

An index holds up to 1000 custom suggestions; one more answers 409 SUGGESTION_LIMIT_REACHED. MCP has no tool for custom suggestions.

Weight

A popular search 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 popular search or a field value, the custom one wins: its weight and its hint are used.

Change the settings with the API

The cabinet's two settings forms are one config per index. The first time anyone opens it, in the cabinet or with GET, it is created with the defaults above and a new suggest key.

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. MCP has no tool for the config.

curl -X PUT https://api.search.zaproo.cloud/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
  }'

The suggest request

Your storefront calls one route with the suggest key. The body holds only q, up to 100 characters. Integrate a storefront shows how a search box uses it.

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

Suggest completions for "ta" on the products index.

{
  "suggestions": [
    {"text": "tape", "kind": "query", "facetHint": {"key": "categories", "value": "Tapes"}},
    {"text": "Packwell", "kind": "field", "facetHint": {"key": "brand", "value": "Packwell"}},
    {"text": "duct tape", "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 Try it panel 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

Popular searches 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. Popular searches need searches first. Add the brand field under Field values and a few custom suggestions, then click Rebuild now.
• A change to the sources does nothing. Field values, the minimum count, the lookback and custom suggestions only apply with the next build. Click Rebuild now.
• Test searches on the storefront become suggestions. Searches from the cabinet and from MCP never feed autocomplete, but tests on your live storefront do. Add your office to the excluded IP addresses, keep Searched by at least at 2 or more and send a sessionId from the storefront, so a handful of test searches from one person stays out.
• Clicks on suggestions don't show in analytics. Suggest requests are not logged. Send suggestion_click events to fill the Autocomplete report.

Related

• Quickstart
• Integrate a storefront
• Search profiles
• Mapping and fields
• Search analytics
• Reports
• MCP tools
• Limits