API Reference
API Reference

Search Result Pages

The Search API endpoint first and foremost should be used to source data needed for search result pages. Below is a list that covers the main functionality your team will need to implement in order to allow a customer to refine search results. There are also query string parameters notated here for reporting (required) and personalization functionality (if applicable). Other query string parameters to further enhance your search functionality are also available in the Search API documentation.

Search Results


Query

The Query query string parameter (q) value should be sourced from the value the shopper typed in the searchbar and submitted a search to refine results. The API will consume the data passed and 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:



Background Filters

In the case your team needs to pre-filter results based on specific product data, the background filter parameter (bgfilter) should be used in Search API Requests and not the filter parameter (filter). Some examples of what fields you can pre-filter search results by could be search_only, availability, on_sale, etc. This allows for our reporting to differentiate between customer applied filters and background filter parameters for pre-filtering results.


Documentation:



Filtering

Filtering Results

All filtering should be done by making requests to the Search API and using the filter query string parameter. Attempting to handle filtering client side will adversely affect Searchspring’s reporting and merchandising capabilities.


Documentation:


Rendering Filter Data

The filters displayed on a results page should be displayed in the order they are returned by the Search API in the facets object and be displayed as collapsed or expanded per the Search API response. It is important that the order of the filters follows the order seen in the Search API response. It is also important that the extra data returned for each facet in the API response is implemented as well as that data is used to describe each filters appearance and behavior. This is important as the data found within each facet can be configured within our tool.


Documentation:

  • Search API - See facets object in the 200 response code below the query string parameters
  • Filtering - How to configure filters
  • Merchandising - Custom Filter Order


Sorting

The sorting options displayed on a results page should be displayed in the order they are returned and use the labels returned in the Search API response. When initially loading a page a sort query string parameter should not be passed as part of the API request. This will allow for merchandising rules to be applied to the results.


All sorting should be done by making requests to the Search API, attempting to handle sorting client side will adversely affect Searchspring’s reporting and merchandising capabilities.


Documentation:



Results Per Page

Only the required number of results for the current page should be requested from the Search API. This is used to limit the number of results that should be returned in the API response. All results returned must be rendered.


Documentation:



Pagination

Your team can choose to utilize traditional pagination or opt to build an infinite scroll feature within your integration. To do this your team can reference the data returned within the pagination object in the API response to build this navigation.


All pagination should be done by making requests to the Search API, attempting to handle pagination client side will adversely affect Searchspring’s reporting and merchandising capabilities.


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:



Search Personalization Parameters

The Preflight API endpoint and the Search 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