Sign in

v1

latestOpenAPI 3.1.02026-07-243452166.7 KB

Autocomplete API

Used to receive data to build a preview of results to the shopper within the Autocomplete Module based on the typed value in the searchbar.

get/api/search/autocomplete.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.

resultsFormatstring required
Example:json

For API integrations this parameter with a value of json is required to return results data as JSON. Other results formats are deprecated and no longer available.

qstring
Example:shoe

Query value will search the index for terms that match the query. Will support up to 256 characters.

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
sortobject

Used to sort returned results.

Parameter names should be "sort.[field]=[asc/desc]"

Examples:

  • sort.price=asc
  • sort.is_bestseller=desc
userIdstring required
Example:3022b347-a272-46c3-b676-62266e335a80

If the cookie "ssUserId" is currently set, use the value as the userId value.

If it doesn't exist yet, generate a new ID and store it in the "ssUserId" cookie.

sessionIdstring required
Example:6576ccfc-1294-4e30-878a-77cc2ca5299f

If the cookie "ssSessionId" is currently set, use the value as the sessionId value.

If it doesn't exist yet, generate a new ID and store it in the "ssSessionId" cookie.

pageLoadIdstring required
Example:945ea9d2-f155-4cf1-81f5-f7c60b3ce0db

Create a new ID for this parameter on every page load. If using a headless build create a new ID for this parameter on every URL route change.

If it doesn't exist yet, generate a new ID.

domainstring required
Example:http://www.searchspring.com/collections/mens?filter:ss_hierarchy=Mens/Clothing/Pants&filter:page=1

The full URL of the current page.

resultsPerPageinteger
Example:48

This will allow you to override the number of results per page that are returned in the Search API response in the results array.

pageinteger
Example:5

The page of results to be loaded.

redirectResponse'direct' | 'minimal' | 'full'
Example:direct

Will change how redirects behave in the API response.

  • Direct - will return a 302 and redirect a shopper to the returned URL within merchandising.redirect in the response. Direct is best for API integrations as it is the most performant.
  • Mininal - returns a partial API response without results data. Redirect URL will be returned in the merchandising object.
  • Full - returns the full API response with results data. Redirect URL will be returned in the merchandising object.
landing-pagestring
Example:black-friday

Will allow the API to search the database for products that are a part of a configured landing page campaign.

Landing page campaign example: landing-page=black-friday

tagstring
Example:black-friday

Will allow our API to search the database for products that are a part of a configured segmented merchandising campaign. To trigger a segmented merchandising campaign the value must follow this format, tag=merch.segment/[your-tag-here].

Segmented Merchandising campaign example: tag=merch.segment/logged-in-black-friday

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.

disableInlineBannersstring

Will disable inline banners from being returned in the API response.

lastViewedstring

Comma seperated list of product SKUs or UIDs that the customer has recently viewed. The most recently viewed product SKU or UID being at the front of the string of product SKUs or UIDs passed. This is required to allow personalization functionality to personalize products in search results as the customer navigates the site. To learn more about personalized search, please refer to this link for more information.

cartstring

Comma seperated list of product SKUs or UIDs that are in the current customers cart. This is required to allow personalization functionality to personalize products in search results as the customer navigates the site. To learn more about personalized search, please refer to this link for more information.

shopperstring

ID of current logged-in shopper from your platform, this is required for personalization features. If the shopper is anonymous this should be omitted. To learn more about personalized search, please refer to this link for more information.

source'historical' | 'input' | 'trending' | 'suggested'
Example:input

The source of the query - must be one of "historical", "input", "trending", or "suggested".

inputstring

The input value - value typed by the user (may differ from the query if using suggestions).

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.

Headers

HTTP_X_FORWARDED_FORstring

This header is required only for accounts that are making API requests within their server (server-side integration).

In order for requests to be properly handled pass the active customer's IP address to Searchspring as the value for this header.

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"
}