Versions Compared

Old Version 3

changes.mady.by.user Andrey Veprikov

Saved on

compared with

New Version Current

changes.mady.by.user Andrey Veprikov

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Method Objective

The method returns an API response when requesting product recommendations.

Request

EndpointRequest Type
https://api.personaclick.com/recommend/{% recommender_code %}GET

Parameters

Name

TypeRequirement

Description

recommender_codestringrequiredUnique code of the recommendation block. See this value in the "data-recommender-code" attribute of the block created in PersonaClick account. The parameter builds the endpoint for the recommendation request.
shop_idstringrequiredUnique Store Key in PersonaClick. Located there: Account > Settings > Store Settings
didstringrequiredUnique Device ID. See "Initialization (REST API)" for information about getting and using Device ID.
seancestringrequiredUnique ID of the current user session. See "Initialization (REST API)" for information about getting and using User Session ID.
segmentstringoptionallyCan take one of the values: "A" or "B" according to the segment to which the user is assigned. You can use your algorithm to divide users evenly between the segments.
itemnumber/stringrequired in some casesProduct ID. This  This parameter is mandatory for the requests of blocks with algorithms that use the algorithms depend on the current product. Algorithms: "Similar" and "Also bought"", "Products usually purchased with this product", "Store recommendations", etc.
excludestringoptionallyProduct IDs (splitted by comma), which should be excluded from the recommended products list.
categorynumber/stringrequired in some casesCategory ID. This parameter is mandatory for all blocks set on category pages.
search_querystringrequired in some casesThe text of the search query. This parameter is mandatory for the requests of blocks that use the "Search" algorithm.
limitnumberoptionallyA maximum number of products in the API response.
locationsstringoptionallyLocation IDs, splitted by comma. If used, the API response will return products available in the listed locations.
brandsstringoptionallyBrand names, splitted by comma. If used, only the products of the listed brands will be returned in the API response.
exclude_brandsstringoptionallyBrand names, splitted by comma. If used, the API response will exclude the products of the listed brands.
categoriesstringoptionallyCategory IDs, splitted by comma. If used, the API response will only return products that are included in the listed categories.
discountbooleanoptionallyIf used with "true" value, then only those products, the value of which is less than the "oldprice" value, will be returned in the API response.
resize_imagenumberoptionallyProduct Image Size. Available values (px): 120, 140, 160, 180, 200, 220. The default is the original size.
extendednumberbooleanoptionallyIf it's set to 1 value, the API will return extended product information in the recommends property. Otherwise, only product IDs will be returned.Allows getting extended information about products for self-rendering of the recommended products widget. See the "recommends" property of the API response. Default: false
prevent_shufflebooleanoptionallyIf set to true value this will disable product shuffling in the API response.
pagenumberoptionallyUsed when pagination is needed. The API returns products of the specified page and limit (limit is set in the block's settings in the account or as an additional parameter in the request).

API Response Code

HTTP status code

Description
200 OK

The request was successful.

404 Not FoundThere are no mandatory parameters in the queryrequest.

API Response Data

The API returns an array of category objects. Below are the properties of a single object.

NameTypeDescription
htmlstringHTML-code of the block with products. The template is customized in the PersonaClick account.
titlestringThe block title. Corresponds to the value of the "Action" element in the block rules.
recommendsarray/Object arrayThis property will contain an array of products by default, or an object array with extended product information if the extended parameter is used in the API request.Array/Object Array

Depending on the value of the "extended" parameter in the API request, it returns either an Array or an Object Array.

The Array contains only product IDs.

The Object Array contains objects with the following properties:

  • barcode – product barcode, if it was imported in the product catalog (type: string)
  • brand – product vendor (type: string)
  • categories – an Object array with details of the product category hierarchy, where each object has properties:
    "id" – category ID (type: string)
    "level" – сategory level in the hierarchy (type: string)
    "name" – category name (type: string)
    "name_with_parent" – string name from the name of the parent and main product categories, separated by a "-" (type: string)
    "parent_id" – parent category ID (type: string)
    "url" – category page url (type: string)
  • category_ids – an array of IDs of the product category hierarchy (type: String array)
  • currency – product currency (type: string, matches the currency of the PersonaClick account, or the user value set in the settings of the PersonaClick account)
  • discount – the percentage difference between the old price and the current price (type: number)
  • discount_formatted – the percentage difference between the old and the current price that is formatted as a string with the "%" symbol (type: string)
  • discount_percent – user-defined discount value (type: number)
  • gift – specifies whether the product is a gift (type: boolean)
  • installment – the payment cost if purchasing the product in installments (type: number)
  • id – product ID (type: string)
  • image_url – URL of the original product image (type: string)
  • image_url_handle – relative URL of the original product image (type: string)
  • image_url_resized – the object with the URLs of the resize product image. Available object keys matching the size of the image in pixels: 120, 140, 160, 180, 200, 220, 310, 520 (type: object)
  • is_new – new arrival product (type: boolean). See the parameter in the product catalog import (XML, HTTP API)
  • leftovers – rough number of the products left in stock. Available values are: 
    "one" - one product
    "few" - 2-10 products
    "lot" - over 10 products
  • model –  model and product name (type: string)
  • name – product name (type: string)
  • oldprice – integer old price of the product (type: number)
  • oldprice_formatted – formatted integer old price of the product, including currency (type: string)
  • oldprice_full – old price of the product (type: number)
  • oldprice_full_formatted – formatted old price of the product, including currency (type: string)
  • params – object array with pairs of "key" (type: string), "values" (type: array) properties. The data matches the values of the "param" parameter of the product feed/catalog (XML, HTTP API).
  • picture – link to the product image in the PersonaClick image repository (type: string)
  • price – integer current price of the product (type: number)
  • price_formatted – formatted integer current price of the product, including currency (type: string)
  • price_full – current price of the product (type: number)
  • price_full_formatted – formatted current price of the product, including currency (type: string)
  • price_with_promocode – the product price when using the promo code specified for the product (type: number)
  • price_with_promocode_formatted – formatted product price when using the promo code specified for the product, including currency (type: string)
  • promocode – the promo code is for a specific product (type: string)
  • rating – product rating (type: number)
  • relative_sales_rate – level of sales of current product ( in percentage) in relation to the maximum level of sales of products in the store (type: number)
  • sales_rate – level of product sales (absolute value) (type: number)
  • url – product page URL (type: string)
  • url_handle - relative product page URL (type: string)
idnumberUnique block identifier. Corresponds to the block ID in the list of blocks in the PersonaClick account.
snippetstringJS snippet code attached to the recommender.

Request Examples

For blocks with algorithms that require the "Product ID":

Code Block
languagejs
themeFadeToGrey
curl 'https://api.personaclick.com/recommend/1fd1b3495137bc3c9299816026acf36f?shop_id=0d42fd8b713d0752776ca589cc0056&did=iVxRcAaGzA&seance=C6vpfZPlpz&segment=A&item_id=100500'


For blocks with algorithms that require the "Category ID":

Code Block
languagejs
themeFadeToGrey
curl 'https://api.personaclick.com/recommend/1fd1b3495137bc3c9299816026acf36f?shop_id=0d42fd8b713d0752776ca589cc0056&did=iVxRcAaGzA&seance=C6vpfZPlpz&segment=A&category=146'


For blocks with an algorithm that requires the "Search Query":

Code Block
languagejs
themeFadeToGrey
curl 'https://api.personaclick.com/recommend/1fd1b3495137bc3c9299816026acf36f?shop_id=0d42fd8b713d0752776ca589cc0056&did=iVxRcAaGzA&seance=C6vpfZPlpz&segment=A&search_query=To%20be%20or%20not%20to%20be'


Full example:

Code Block
languagejs
themeFadeToGrey
curl 'https://api.personaclick.com/recommend/1fd1b3495137bc3c9299816026acf36f?shop_id=0d42fd8b713d0752776ca589cc0056&did=iVxRcAaGzA&seance=C6vpfZPlpz&segment=A&search_query=To%20be%20or%20not%20to%20be&category=146&categories=1%2C146%2C100500&exclude=3%2C14%2C159%2C26535&item_id=60496856&limit=15&brands=Alas%2Cpoor%2CYorick'
Table of Contentsclasspersonaclick-fixed-position
&extended=true



Column

Page Navigation

Table of Contents
maxLevel2
indent0px
stylenone



Related Pages

Filter by label (Content by label)
showLabelsfalse
showSpacefalse
sorttitle
cqllabel = "recommenders"