SearchSpring provides a REST 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 format. 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 REST API URL
http://api.searchspring.net/api/search/search.json
Request Options / Query Parameters
Website Key: "websiteKey" (required)
Your private website key, it can be found on the "My Account" page in the SearchSpring management console.
Search Query: "q=[search query]"
The search query you wish to use. The search query must be properly URL escaped.
Example: q=shoes or q=running%20shoes
Tag: "tag=[tag value]"
Tagged searching. Return results related to a defined tag. Tags are currently used for Landing Pages functionality.
Example: tag=my-landing-page
Filters: "filter.[field]=[value]
You can also include a list of filters to only return results for certain facets. You can also use multiple values for a single facet, depending on your settings for this facet in the SearchSpring Management Console.
Examples: filter.color=Blue filter.department=Mens filter.category=Running%20Shoes
Numeric Range Filters: "filter.[field].low=[starting value]&filter.[field].high=[ending value]"
You can also specify a range of values if the facet is a numeric field.
Example: $10 to $120: filter.price.low=10&filter.price.high=120
Example: Over $1,000: filter.price.low=1000
Search Results Format: "resultsFormat=[native | html]"
This option drives the format each individual search result is returned in. For AJAX UI applications, returning each search result in pre-populated HTML format may be advantageous for speed and convenience. Alternatively, search results may be return the raw key/value pairs in native JSON.
Defaults to: "html".
Accepted Values: html native
Results Layout: "resultLayout=[grid | list]" (only applies when resultsFormat=html)
Controls which template is used for building search results HTML.
Possible Values: grid or list
Sort: "sort.[field]=[direction]"
You can sort by referencing the field you want to sort by and the direction. The format for sorting is "sort.[field]=[direction]". Direction may be "asc" or "desc".
Example:sort.price=desc or sort.brand=asc
Results Per Page: "resultsPerPage=[1 to 100]"
You may change the number of results returned per page using this parameter.
Valid Range: 1 to 100
Page: "page=[1,2,3,...,n]"
The page number of results to return.
User ID: "userId=[userId]"
A unique ID for the user. For non-logged in users this can be a randomly generated ID stored in a cookie. This is used for tracking users for IntelliSuggest.
JSONP Callback: "callback=[JavaScript function name]" (only applies for the JSON response type)
Used for JSONP requests, when a callback function is specified, the SearchSpring API will pass the JSON-encoded response as an argument to the function specified. The jQuery library will automatically pass this request parameter for you if you use a JSONP AJAX request.
Example Requests
http://api.searchspring.net/api/search/search.json?websiteKey=0fc144b759b323b10f9dcb989e118a7d&q=mens%20shoes&resultsFormat=native&resultsPerPage=30&page=1
http://api.searchspring.net/api/search/search.json?websiteKey=0fc144b759b323b10f9dcb989e118a7d&q=mens%20shoes&resultsFormat=html&resultLayout=grid&resultsPerPage=30&page=1
http://api.searchspring.net/api/search/search.json?websiteKey=0fc144b759b323b10f9dcb989e118a7d&q=mens%20shoes&filter.sizes=11.5&resultsFormat=native&resultsPerPage=30&page=1
http://api.searchspring.net/api/search/search.json?websiteKey=0fc144b759b323b10f9dcb989e118a7d&q=mens%20shoes&filter.sizes=11.5&filter.price.low=50&filter.price.high=100&resultsFormat=native&resultsPerPage=30&page=1Headers
If you're using our API directly to have SearchSpring properly track your user behavior and handle bot crawlers you will need to pass your customers IP address and User Agent to SearchSpring as part of your request headers.
Example: (PHP)
curl_setopt( $ch, CURLOPT_HTTPHEADER, array("REMOTE_ADDR: $ip", "HTTP_X_FORWARDED_FOR: $ip"));
curl_setopt($ch, CURLOPT_USERAGENT, $userAgent);
Comments
0 comments
Please sign in to leave a comment.