API Reference
API Reference

Autocomplete Module

This section will cover the different API endpoints that are available to build a functional Autocomplete module within your integration as well as cover the different features that are available within each endpoint.

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:

input to suggest to autocomplete api flow

  1. As a shopper types into the search bar, use our Suggest API to receive query suggestions.

  2. 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.

how to handle query suggestions

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:


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:


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:


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 ssSessionIdNamespace 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:



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