Search API: Request

Searchspring provides an API for searching and browsing the catalog of products indexed in your Searchspring account. The API provides the ability to return results based on a search query or a filter on a field (e.g. Category is "Running Shoes").

Searchspring will return results in JSON. The response will include products that match the search criteria, available facet options to further refine the results and any configured merchandising content like promotional banner images.

Search API URL

https://[siteId].a.searchspring.io/api/search/search.json

siteId identifies your site. You can find your siteId on the My Account page.

Installing Autocomplete?

While performing a preview search to display product results within an AutoComplete modal, use the following endpoint to avoid muddying up your insights & reporting data:

https://[siteId].a.searchspring.io/api/search/autocomplete.json

This will function exactly the same as a normal search request, but will not affect your reporting.

Installing Product Finders?

If implementing Product Finders, you'll similarly need to use this endpoint to avoid muddying up your insights & reporting data:

https://[siteId].a.searchspring.io/api/search/finders.json

Request Headers

searchspring-session-id

Format	String
Description	If the cookie "ssSessionIdNamespace" is currently set, use that. If if doesn't exist yet, generate a new ID whenever a new web session begins. We recommend using a UUID v4 generator (Such as these examples: JS, PHP, Node).  Be sure to set it as the cookie "ssSessionIdNamespace"
Example	"6576ccfc-1294-4e30-878a-77cc2ca5299f"

searchspring-user-id

Format	String
Description	If the cookie "ssUserId" is currently set, use that.  If if doesn't exist yet, generate a new ID. We recommend using a UUID v4 generator (Such as these examples: JS, PHP, Node). This value should only be generated if it doesn't already exist.  Be sure to set it as the cookie "ssUserId" This will override the userId parameter (see below).
Example	"3022b347-a272-46c3-b676-62266e335a80"

searchspring-page-load-id

Format	String
Description	Create a new ID for this on every page load. We recommend using a UUID v4 generator (Such as these examples: JS, PHP, Node).  This value is not stored in any cookies or local storage.
Example	"945ea9d2-f155-4cf1-81f5-f7c60b3ce0db"

Request Parameters

siteId (required)

Format	String
Description	Identifies the account making the request. This can be found on the My Account page in the Searchspring Management Console.
Example	abc123

q

Format	String
Description	The search Query. Searches the database for the terms in the query. This can be blank or not included for pages without a search query.
Examples	"shoes" "iphone%20charger"

tag

Format	String
Description	The landing page tag. Searches the database for products that are a part of that landing page. This will be blank or not included for non-landing page pages.
Examples	"black-friday" "vip"

resultsFormat

Format	String
Default	"html"
Description	Native will return raw JSON for products. HTML will generate HTML for your products based on Searchspring templates. Accepts "native" or "html".
Example	"native"

redirectResponse

Format	String
Description	Changes how Redirects behave in the response.
Accepted values	direct: Returns a 302 redirect response immediately. Great for API integrations, slightly faster than "minimal" minimal: (Default) Product results are not gathered or returned. Redirect placed in merchandising key as usual.  full: Returns full product results in addition to redirect information. Much slower.

includeChildren

Format	Boolean
Default	false
Description	Returns variant (aka children) objects for each result. Requires Variants Support to be set up in order to function.
Examples	true 1

userId (Legacy)

Format	String
Description	This is to support legacy integrations, and is the same as the searchspring-user-id header above. Passing both will result in the header taking precedence.
Example	"3022b347-a272-46c3-b676-62266e335a80"

variationId

Format	Integer
Description	Forces the use of a specific variation from an A/B testing experiment.
Example	153

Example Request

cURL

curl -X GET -H "searchspring-session-id: 6576ccfc-1294-4e30-878a-77cc2ca5299f" -H "searchspring-user-id: 3022b347-a272-46c3-b676-62266e335a80" -H "searchspring-page-load-id: 945ea9d2-f155-4cf1-81f5-f7c60b3ce0db" "https://[siteId].a.searchspring.io/api/search/search.json?q=dress&resultsFormat=native&siteId=[siteId]"