SearchSpring API: Search and Navigation

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 or XML 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
http://api.searchspring.net/api/search/search.xml

Use an extension of .json or .xml to return results in the desired format.

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.

Examples:

q=shoes
q=running%20shoes

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.

Examples:

$10 to $120: filter.price.low=10&filter.price.high=120
Over $1,000: filter.price.low=1000

Search Results Format: "resultsFormat=[json | html]" (only applies for the JSON response type)

This option drives the format each individual search result is returned in. For AJAX UI applications, returning each search result in prepopulated HTML format may be advantageous for speed and convenience. Alternativately, search results may be return the raw key/value pairs in native JSON or XML formats for rendering by your client application.

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

Examples:

sort.price=desc
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.

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=1