# 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"
}
Last Updated: 6/21/2023, 4:16:55 PM