API Reference
API Reference

Product Finder Module

Product Finder

Product Finders are a tool to help your shoppers quickly find the products they are looking for - think of it as a way to easily navigate into a more narrow, filtered Product Results set. Commonly implemented as a set of Attribute drop-down selectors, these Finders can exist on your Home Page, globally across the Header of your website, or even on a single Category Page or Landing Page.


Before the shopper submits the selections made within the Product Finder Module, all background filter (bgfilter) and filter (filter) query string parameters should be collected.

Once the shopper submits the search they should then be directed to a search results page. On the search results page all collected background filter (bgfilter) and filter (filter) query string parameters should be passed to the intial Search API request so that the shopper can view the search results that are based on the shoppers selections from the Product Finder Module.


Documentation:



Results Per Page

For a Product Finder this query string parameter is required and should always receive a value of 0. This is because filter data is all that should be sourced from this endpoint to build the Finder Module.


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.

Limiting Returned Facet Data
Your team can utilize the query string parameters, includedFacets or excludedFacets to tell the API what filters you want to be included or excluded from the facets array of facet objects.

Documentation: