API Reference
API Reference

Personalized Recommendations API

get
https://{siteId}.a.searchspring.io/boost//recommend

Will return recommended products queried from a configured personalized recommendations profile. Returned results will be personalized to the shopper.

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

Query Params
string
required

Comma-separated list of profile IDs that are associated with a recommendations profile in the Searchspring Management Console.

string

Comma-separated list of the IDs or SKUs of the products being viewed. This parameter is required only for recommendations profiles that use cross-sell or similar recommendations types, and is recommended for all requests made on Product Detail Pages. This parameter will often just be a single value on a PDP but could be multiple on something like a view wishlist page or a page for a bundle of products.

string

Comma-separated list of the IDs or SKUs you wish to block from being returned by the API in this call. This is useful if you have other products that are being displayed on the page that you don't want returned by the recs API, potentially if you have curated products on the page.

string

Comma-separated list of category IDs. When using a Category Trending Recommendation Profile, the categories you want recommendations for are required.

string

Comma-separated list of brand names. When using a Brand Trending Recommendation Profile, the brands you want recommendations for are required.

string

ID of current logged-in shopper from your ecommerce platform; this is required for personalization based on shopper history. If the shopper is anonymous, this parameter should be omitted.

string

Comma-separated list of product IDs or SKUs that are in the current shopper's cart. This is required to curate recommended products as the shopper navigates the site. Required for cart cross-sell.

string

Comma-separated list of product SKUs that the shopper has recently viewed, with the most recently viewed product SKU listed first in the comma-seperated list. This parameter is required to curate recommended products as the shopper navigates the site.

string

Sets the maximum number of products returned by a recommendation profile. Comma-separated list of integers, with one integer per profile. This will apply a limit for each profile in order, corresponding to each profile tag. If no limits are defined for any of the profiles, the default of 20 products will be returned for that profile.

filter
object

Filters the recommendations being returned. A field must have the Recs Filter column selected in the Field Settings page in the SMC in order to be used. Because the data science only creates so many recommendations for each product, there is a high chance of filtering out all of the recommendations; as such, this is best used when showing nothing is better than showing the wrong product.

Parameter names should be: "filter.[field]"; value is not case-sensitive.

Examples:

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

In order to use the range functionality the .low and/or .high should be appended after the field name. This is restricted to numerical values only.

Examples:

  • filter.price.low=2
  • filter.price.high=120
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.

Responses

400

400 Bad Request

403

403 Forbidden

404

404 Not Found

405

405 Method Not Allowed

Updated 2 months ago

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