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.
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.
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. |
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]"
Comments
0 comments
Please sign in to leave a comment.