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 filter 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.jsonsiteId 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.jsonThis 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" |
HTTP_X_FORWARDED_FOR
| Format | String |
| Description | If you are making requests to our API via a server-side integration, you will need to pass your customer's IP address to Searchspring. This is not required for client-side integrations. |
| Example | "23.4.8.192" |
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. |
childCount
| Format | Integer |
| Default | 50 |
| Description | Max: 50 Requires Variants Support to be set up in order to function. Specify the number of objects to be returned in the "children" response. Lower numbers help with faster front-end loading times. Higher numbers help with showing more variant info (such as color swatches) on each product, as well as more complex display logic. |
| Examples | 0 ("children" will not be returned at all) 1 30 |
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" |
disableFacetDrillDown
| Format | Boolean |
| Description | Normally for Category Hierarchy filter types, only the current branch and the ones immediately above it will be returned in the response. Setting this to true will return the entire category hierarchy tree. |
| Default | false |
| Example values | true, 1 |
experimentalMode
| Format | String |
| Description | Forces a specific keyword match level for search queries. Overrides the existing setting for the site as it is set in Advanced Search Optimizations. discrete-loose: At least one word must be found in a product for it to be returned. discrete-strict: All words must be found in a product for it to be returned. This is the most common match level on most sites by default. |
| Example values | discrete-loose discrete-strict |
disableEmptyRequestProtection
| Format | Boolean |
| Description | Allows an empty query to build aggregations, slowing down search performance. Overrides the "Empty Request Protection" checkbox on the site's Advanced Settings. |
| Example values | true, 1, false, 0 |
variationId
| Format | Integer |
| Description | Forces the use of a specific variation from an A/B testing experiment. |
| Example | 153 |
userIpAddress
| Format | String |
| Description | Override the user IP address being used. Can be useful in testing Geographic Merchandising. |
| Example | 92.13.103.56 |
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
Article is closed for comments.