Sign in

v1

latestOpenAPI 3.1.02026-07-243452166.7 KB

Finder API

Used to source filters to build a Product Finder Module.

get/api/search/finder.json

Query parameters

siteIdstring required

Unique identifier to associate the Searchspring account making the request to the database. This can be found on the My Account page in the Searchspring Management Console under the Account details section.

resultsPerPageinteger required

Because we only need relevant facet data returned to build a Product Finder, we do not need results. This should always be passed and receive a value of 0.

filterobject

Filters the array of results. Filter parameter is used when a customer applies a filter in the UI.

Parameter names should be "filter.[field]", value is case sensitive.

Examples:

  • filter.color=blue
  • filter.size=Large

If a filter is configured to have a type of slider or if a range is specified in the advanced section, in order to use the range functionality a low and/or high value will need to be chained after the field.

Examples:

  • filter.price.low=2
  • filter.price.high=120
bgfilterobject

Functions the same as the filter parameter except it is used to filter intial results on pages like Category or Collection pages, or can also be used to filter intial results for all pages or specific pages of the site. This parameter should not be usable in the UI by a customer, see the filter parameter for customer interactions to filter results.

Parameter names should be "bgfilter.[field]", value is case sensitive.

Examples:

  • bgfilter.collection_handle=new-arrivals
  • bgfilter.is_published=1

If a filter is configured to have a type of slider or if a range is specified in the advanced section, in order to use the range functionality a low and/or high value will need to be chained after the field.

Examples:

  • filter.price.low=2
  • filter.price.high=120
includedFacetsstring
Example:category_hierarchy

Will allow you to specify specific facets you would like returned in the API response. The specified value passed must be the name of the facet field for it to be included. If the parameter is included, but the value is blank, facets will not be returned in the response.

excludedFacetsstring
Example:category_hierarchy

Will allow you to remove a specified facet from the facets array returned in the API response. The specified value passed must be the name of the facet field for removal to function as expected.

beaconboolean

Specify wether or not using the new Beacon tracking system - this will tell the API to generate an auto-beacon event that is sent to our tracking system.

testboolean

Specify that this event is a test event - this prevents our tracking system from processing the event as a real user interaction.

Response

OK

resultLayoutstring

This field is deprecated as it was previously utilized for Searchspring Integrations.

responseIdstring

A uniquely generated ID used to identify the response. This ID is used by beacon tracking to associate user interactions with specific finder results.

Example response

{
  "responseId": "a7f2e1c4-9b3d-4e8a-b2c1-5d6e7f8a9b0c"
}