Autocomplete Module

An Autocomplete Module is used to perform a preliminary search and display a preview of results and suggestions to the shopper before a search is submitted on the site. This is so shoppers can have a good indicator of what they are searching and generate more meaningful searches on the site.

Below is a flowchart that displays how the Autocomplete Module should function on the site using the Autocomplete and Suggest API endpoints:

As a shopper types into the search bar, use our Suggest API to receive query suggestions.
As a shopper types into the search bar, use our Autocomplete API to fetch products to display as a preview in the Autocomplete Module.

When a shopper hovers over a different rendered query suggestion, simply pass the value to the Autocomplete API to get and render product results for the hovered suggestion.

Below is a more through breakdown of what is available to fully build your own functioning Autocomplete Module.

Trending API

The Searchspring Trending API is an optional feature that will provide you with the most popular searched terms that return valid results in the last 90 day period. Popular terms are used to generate initial suggestions and results before a customer types in the searchbar.

Documentation:

Suggest API

The Searchspring Suggest API is used to fetch suggestions and spelling corrections based on the customer’s currently entered search query.

We recommend when a customer types or removes at least 2 characters, and a 50ms period passes to send a request to the Suggest API endpoint.

Documentation:

Autocomplete API

It is required to use the Autocomplete API endpoint in place of the Search API endpoint for this functionality in order to differentiate these requests for reporting and machine learning purposes. Failure to do so will result in inaccurate reporting and poor spelling corrections.

This endpoint is primarily used to retrieve a preview of search results to display to the end user so that they have the opportunity to refine their search query before submitting a search. This endpoint also supports functionality available from the Search API endpoint like background filtering, filtering, sorting, merchandising, and pagination should you need these features to build your Autocomplete Module.

Documentation:

Autocomplete API

Query

The Query query string parameter (q) value should be sourced from the value the end user types in the searchbar to refine results that match against the indexed product data made available from the fields that are configured as a searchable field on the field settings page (must be logged in) in the Searchspring Management Console. This parameter will support a maximum of 256 characters.

Documentation:

Autocomplete API - See q query string parameter
Managing Field Settings - see Display

Query Source & Input Tracking

To generate accurate reports on how autocomplete queries are being made, it's important to include the source and input parameters when making requests to the Autocomplete API. These parameters help differentiate between user-typed queries and suggested queries.

source Parameter

The source parameter indicates where the query originated from. This parameter is optional and should only be included when your autocomplete experience uses suggestions (from the Suggest API or Trending API).

Valid values:

suggested - Query came from a suggested term
historical - Query came from historical/recent searches
trending - Query came from trending searches
input - Query is directly from user input (default)

input Parameter

The input parameter should contain what the user has actually typed into the search input field. When using suggestions, the input and q parameters may differ:

q contains the suggested query term being used for the search
input contains what the user actually typed

Example Scenario:

User types "sh" into the search bar
Suggested query terms are fetched from the Suggest API
Type-ahead logic determines that "shoes" should be used (as it's the most popular suggested term)
The Autocomplete API request would include:
- q=shoes (the suggested query)
- input=sh (what the user typed)
- source=suggested (indicating the query came from suggestions)

Documentation:

Autocomplete API - See source and input query string parameters
Suggest API

Results Per Page

Only the required number of desired results to be rendered in the Autocomplete module should be requested from the Autocomplete API. This is used to limit the number of results that should be returned in the API response. All results returned must be rendered within the Autocomplete Module.

Documentation:

Sorting & Pagination

User Tracking Parameters

The query string parameters userId, sessionId, pageLoadId, and domain are required for our reporting and personalization features to work properly for API requests.

userId will receive its value from the ssUserId cookie
sessionId will receive its value from the ssSessionId cookie
pageLoadId will be a randomly generated UUID v4 value. This should be updated with every physical page load. If the integration is a Single Page Application(SPA) or Headless, this value will change for every URL route change.
domain will receive its value from the current page URL. This shouled be sourced from window.location.href

Documentation:

Search API - see query string parameters userId, sessionId, pageLoadId, domain
Searchspring Cookies

Autocomplete Personalization Parameters

The Preflight API endpoint and the Autocomplete API query string parameters here are only applicable if the account is signed up and configured for Personalized Search & Merchandising. The first step is to ensure a call to the Preflight API is made when a shopper logs into your website and all relevant data is sent to the endpoint. If any of the relevant data notated in the endpoint changes as the customer is interacting with the website, ensure the new data is sent to the endpoint before a call to the Autocomplete API or Search API endpoints are made so that our system can allow personalization to occur within the returned result sets.

To learn more about the Personalized Search & Merchandising feature and the requirements, please refer to the following documents:

Query string parameters

shopper
cart
lastViewed

Documentation

Preflight API: GET - See query string parameters shopper, cart, and lastViewed
Preflight API: POST - See query string parameters shopper, cart, and lastViewed
Autocomplete API - See query string parameters shopper, cart, and lastViewed
Personalized Search & Merchandising
Can I use Personalized Search & Merchandising?

Beacon Tracking

The Autocomplete Module requires tracking events to capture shopper interactions with the autocomplete dropdown. This includes tracking when results are rendered, which products are viewed, and when items are clicked or added to cart. For complete implementation details and event requirements, see the Autocomplete Tracking Guide.

IMPORTANT: When using the Beacon 2.0 tracking system, you must include the beacon=true parameter in your Autocomplete API requests. This enables automatic tracking event generation by the API.

beacon Parameter

Set beacon=true in your Autocomplete API requests to enable the new Beacon tracking system. This tells the API to generate an auto-beacon event that is sent to the tracking system automatically.

Example:

https://{siteId}.a.searchspring.io/api/search/autocomplete.json?siteId=abc123&q=shoes&beacon=true&...

test Parameter

Set test=true to mark events as test events during development and testing. This prevents the tracking system from processing the event as a real user interaction, ensuring your test data doesn't skew analytics and reporting.

Example:

https://{siteId}.a.searchspring.io/api/search/autocomplete.json?siteId=abc123&q=shoes&beacon=true&test=true&...