API Reference
API Reference

Category API

get
https://{siteId}.a.searchspring.io/api/search/category.json

Returns category page results, filters, sort options, pagination, active filters (if active), configured merchandising data (if triggered), and spell correction information to build a category results page. See Category Result Pages to see where this endpoint is used. This endpoint should be used specifically for category page requests instead of the Search API endpoint.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Query Params
string
required

Unique identifier to associate the Searchspring account making the request to the database. This can be found on the My Account page in the Searchspring Management Console under the Account details section.

string
required
Defaults to json

For API integrations this parameter with a value of json is required to return results data as JSON. Other results formats are deprecated and no longer available.

string

Optional refinement query value to search within category results for terms that match the query. Will support up to 256 characters.

filter
object

Filters the array of results. Filter parameter is used when a customer applies a filter in the UI.

Parameter names should be "filter.[field]", value is case sensitive.

Examples:

  • filter.color=blue
  • filter.size=Large

If a filter is configured to have a type of slider or if a range is specified in the advanced section, in order to use the range functionality a low and/or high value will need to be chained after the field.

Examples:

  • filter.price.low=2
  • filter.price.high=120
bgfilter
object

Required for category pages - Functions the same as the filter parameter except it is used to define the category scope by filtering initial results. This parameter is typically used to filter by collection_handle, category_hierarchy, or similar category-defining fields. This parameter should not be usable in the UI by a customer, see the filter parameter for customer interactions to filter results.

Parameter names should be "bgfilter.[field]", value is case sensitive.

Examples:

  • bgfilter.collection_handle=mens-shoes
  • bgfilter.category_hierarchy=Mens/Shoes
  • bgfilter.is_published=1

If a filter is configured to have a type of slider or if a range is specified in the advanced section, in order to use the range functionality a low and/or high value will need to be chained after the field.

Examples:

  • bgfilter.price.low=2
  • bgfilter.price.high=120
sort
object

Used to sort returned results.

Parameter names should be "sort.[field]=[asc/desc]"

Examples:

  • sort.price=asc
  • sort.is_bestseller=desc
string
required

If the cookie "ssUserId" is currently set, use the value as the userId value.

If it doesn't exist yet, generate a new ID and store it in the "ssUserId" cookie.

string
required

If the cookie "ssSessionId" is currently set, use the value as the sessionId value.

If it doesn't exist yet, generate a new ID and store it in the "ssSessionId" cookie.

string
required

Create a new ID for this parameter on every page load. If using a headless build create a new ID for this parameter on every URL route change.

If it doesn't exist yet, generate a new ID.

string
required

The full URL of the current page.

integer
Defaults to 24

This will allow you to override the number of results per page that are returned in the Category API response in the results array.

integer
Defaults to 1

The page of results to be loaded.

string
enum
Defaults to minimal

Note: Redirects are not recommended for category pages. Will change how redirects behave in the Category API response.

  • direct - will return a 302 and redirect a shopper to the returned URL within merchandising.redirect in the response. Direct is best for API integrations as it is the most performant.
  • minimal - returns a partial API response without results data. Redirect URL will be returned in the merchandising object. If redirectResponse is not passed the default behavior is minimal.
  • full - returns the full API response with results data. Redirect URL will be returned in the merchandising object.
Allowed:
string

Will allow the API to search the database for products that are a part of a configured landing page campaign.

Landing page campaign example: landing-page=black-friday

string

Will allow our API to search the database for products that are a part of a configured segmented merchandising campaign. To trigger a segmented merchandising campaign the value must follow this format, tag=merch.segment/[your-tag-here].

Segmented Merchandising campaign example: tag=merch.segment/logged-in-black-friday

string

Will allow you to specify specific facets you would like returned in the API response. The specified value passed must be the name of the facet field for it to be included. If the parameter is included, but the value is blank, facets will not be returned in the response.

string

Will allow you to remove a specified facet from the facets array returned in the API response. The specified value passed must be the name of the facet field for removal to function as expected.

string

Will disable inline banners from being returned in the API response.

string

Comma seperated list of product SKUs or UIDs that the customer has recently viewed. The most recently viewed product SKU or UID being at the front of the string of product SKUs or UIDs passed. This is required to allow personalization functionality to personalize products in search results as the customer navigates the site. To learn more about personalized search, please refer to this link for more information.

string

Comma seperated list of product SKUs or UIDs that are in the current customers cart. This is required to allow personalization functionality to personalize products in search results as the customer navigates the site. To learn more about personalized search, please refer to this link for more information.

string

ID of current logged-in shopper from your platform, this is required for personalization features. If the shopper is anonymous this should be omitted. To learn more about personalized search, please refer to this link for more information.

boolean

Specify wether or not using the new Beacon tracking system - this will tell the API to generate an auto-beacon event that is sent to our tracking system.

boolean

Specify that this event is a test event - this prevents our tracking system from processing the event as a real user interaction.

Headers
string

This header is required only for accounts that are making API requests within their server (server-side integration).

In order for requests to be properly handled pass the active customer's IP address to Searchspring as the value for this header.

Responses

302

Note: Redirects are not recommended for category pages. This status code will be returned when a category or query value passed in the API request matches a configured redirect in the Searchspring Management Console and the query parameter redirectResponse=direct is in use.

400

Bad Request

403

403 Request generated a response that was too large

404

404 Not Found

405

405 Method Not Allowed

429

429 Too Many Requests

500

Internal Server Error

502

Bad Gateway

503

This status code will be returned when the request hits a timeout of 5 seconds.

Updated 2 months ago

Language
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 2 months ago