Shelves: cross-category recommendations

Our Shelves API is a versatile intra and cross-category recommendation solution, thoughtfully designed to assist eCommerce and marketplaces revenue growth experts in delivering unique user experiences such as complete-the-look, complete-the-room, how to style it, and digital changing rooms. This API analyses your catalogue data, including images, tags, descriptions, reviews, and pricing, as well as behavioral, contextual, and personal data (see Analytics API).

Shelves responds to real-time inputs, providing highly personalised recommendations, and seamlessly handles and optimizes seasonality, trends, or sudden high product focus. As a scalable automated solution, Shelves adapts to time and catalogue changes, taking over the complex task of optimizing the personalisation process to enhance customer engagement and boost sales.

How does this work?

All items in the dataset are grouped in categories (shelves) based one or more metadata fields. Usually the categories are following the user navigation on your website. So, for example, if you are having a fashion website you would have top level categories (Men, Women, Kids), secondary level categories (Clothing, Shoes, Accessories) and so on. Based on that category tree we identify the probability of what other categories (including the one for the current product) would the user more likely interact with.

For each category we then look to find the right products so that a specific goal is obtain, like complete the look, match the style, etc. Engaged users can then expand the category / shelf with more related items or apply additional filters (brand, price range, etc.).

Currently he main starting point is an item from the dataset. The shelves ordering can change in real time, keeping in sync with all the types of data we analyse.

Input

Endpoint

GET /orgs/:organisation/datasets/:dataset/models/shelves/:model-version

Field	Type	Required	Value Description
organisation	String	yes	The organisation name
dataset	String	yes	The dataset name
model-version	String	yes	The version name will be confirmed once the solution has been enabled for the dataset. The default value is v1.
id	String	no	The id of the selected item
categories_count	Number	no	The maximum number of shelves returned. Only shelves that are determined to be related are returned. For items in more standalone categories fewer shelves could be detected as being impactful. Maximum value is 10.
items_count	Number	yes	Maximum number of items in a shelf. Maximum value is 50.
include_current_category	Number	no	Use 1 to include a shelf with current product's category items or 0 to exclude. Default value is 0.
category_filter	String	no	Get more results in a specific shelf, by expanding the initial shelf. The value is taken from the list of category names received in the previous call.
category_filter_page	Number	no	Get more results in a specific category, for a specific page. The page size is the items_count value. Defaults to 1.
category_filter_offset	Number	no	The offset to get more results in a specific category, depending on how many results you previously loaded already. Defaults to 0. Value is ignored when category_filter_page is defined. The parameter is useful when previously loaded results have different sizes (e.g. Load 4 items to start, then 8, then 16 more).
q	String	no	The filter criteria based on the associated metadata attribute. See Querying for more details.
fields	String	no	A comma separated list of associated item metadata fields to be added to the response (i.e fields=category,colour). Request all metadata using fields=*.
v	String		The vars querystring containing key-value pairs (key:value comma separated) of action information, support both specific (such as page_view_id) and other custom parameters. Details of Vars Querystring. E.g.: v=a:exit,id:abc-123,user_id:abc,page_view_id:12345

Request

Note

my-dataset-api-token is a dataset token, not an organisation token.

Get recommendations for an item that is in the "boots" category.

curl -X GET \
     -H "Authorization: token <my-dataset-token>" \
     -H "Accept: application/vnd.visii.v2+json" \
     "https://api.visii.com/orgs/my-org/datasets/my-dataset/models/shelves/v1?id=123&categories_count=3&items_count=2&include_current_category=1&fields=category,price&q=price:10:"

Response

Field	Type	Value Description
status	String	The status of the response
results	Object	The list of results to be shown for this step of the journey
results.$.category	String	The shelf name
results.$.items.$.id	String	The id of the item
results.$.items.$.metadata	Object	A selection of metadata fields for the item
results.$.total_results	String	Total number of results in the current category

HTTP/1.1 200 OK
{
  "results": [
    {
      "category": "boots",
      "items": [
        {
          "id": "222",
          "metadata": {
            "category": "boots",
            "price": 79.99
          }
        },
        {
          "id": "333",
          "metadata": {
            "category": "boots",
            "price": 89.99
          }
        }
      ],
      "total_results": 32
    },
    {
      "category": "heels",
      "items": [
        {
          "id": "444",
          "metadata": {
            "category": "heels",
            "price": 75.99
          }
        },
        {
          "id": "555",
          "metadata": {
            "category": "heels",
            "price": 85.99
          }
        }
      ],
      "total_results": 58
    },
    {
      "category": "sneakers",
      "items": [
        {
          "id": "688",
          "metadata": {
            "category": "sneakers",
            "price": 65.99
          }
        },
        {
          "id": "355",
          "metadata": {
            "category": "sneakers",
            "price": 55.99
          }
        }
      ],
      "total_results": 14
    }
  ],
  "status": "ok"
}