In this article we’ll show a couple of practical examples which helps to get better recommendations via Kea Labs Recommendations API. We assume you have already basic knowledge in Kea Labs. If not,- please have a look these articles before:

Context-Aware recommendations

Kea Labs makes  personalised recommendations for User, but sometimes it makes sense to tune results based on the current context. For example, a user is interacting with item X right now, and we need to get suggestions which are more relevant to this item. 

Use Cases:

  • In the news website we already have information about the previously read articles, but currently the user is observing the article on some specific theme, and we need to reflect the user’s interests.
  • In e-commerce site a user has just placed a product X into the cart, and we want to show related items, or personalised recommendations which immediately reflect this new change.

These flags have notable impact on the real time events-based recommendations(like personalisation, or related items), but we recommend you specifying context always when you have this information.

Getting Recommendations for New User

A famous theoretical issue for recommendation systems is – what to show for the new user?

When the user is unknown, and there’s no data about his past events, most systems can show only random data. As it’s impossible to detect neither user interests nor compare the user with other users.

But in Kea Labs we have a solution for making Recommendations for New User. Just specify content for recommendation, as we’ve explained before.

For example, when a user opens the item X- just send this information to Kea Labs as a context, and it’ll be considered as the first interaction. Kea Labs will make at least some rough estimations of user interests. With every further interaction this estimation will be getting improved, and recommendations will be more accurate.

Filtering recommendations

It’s very important often when recommended items need to be filtered in some way. For example, we need to exclude products which are not currently in stock. Or, in a music recommendation store- filter by specific genre. In a movie recommendation- by the age group, artists, etc. Or exclude previously bought items in a Store.

Kea Labs API supports custom filters on a request level, and this is a very flexible tool for tuning recommendations.

Filter is a scripting function that takes an Item and returns boolean results.

Which means, you can script any complicated scenarios including mathematical computations based on the Item’s data. Have a look into item’s statistics object, available for item- it might help to return even more advanced strategies, like- recommend less popular queries, or recommend items which have a good quality content.

Custom scoring for recommendations

Another advanced strategy is to use custom scoring to reorder recommendations for your needs.

This brings unlimited control over the recommendations. Here’re some use cases you can easily implement:

  • boost products from some specific brand
  • promote newer articles in the news portal
  • Boost less popular items to represent catalog wider
  • Prefer products  with the higher prices(up-sell)
  • Or, even on the Item level you can decrease a priority of some specific items.

And many others.

Scoring is the function which takes a currently recommended item and returns a double value with the new score. 

We’ll cover more scripting examples in a separate article, as it’s a pretty large and interesting theme.

Accessing Item statistics

Kea Labs analyzes Items and calculates various metrics useful for the scripting function(like filter or score).

For example, how popular the Item is(from the perspective of  View-events and Purchase- events), or what is the conversion rate of the item. What is the ‘data quality’ – how much data fields are filled in comparison to other items.

All these characteristics are available in the scripts as “_stats” object. For example: _stats.purchaseCountRate

Recommendations Serendipity – Surprise the user

Perfectly accurate recommendations are not usually what a user would like to see. Some recommendations are too obvious for customer to buy, that he already knows about it and will purchase both items anyway. So such a recommendation won’t bring any additional sales, it only simplifies discovery.

But with Kea Labs API you can get ‘most surprising’ recommendations to solve this issue.

There’s a predefined re-score function ‘surprise’ which returns items which the user more likely won’t interact with.

Bonus: how to debug and analyze recommendations

It’s a pretty oten case when you, as a developer, wish to understand why the particular product has been recommended to the user. For this purposes we’ve created a special ‘explain’ method, which works like this:


It takes all interactions of userId and checks how much they are related to the item ‘itemId’. It returns Items with an associated weight. Bigger weight means this User interaction has pulled this Item higher into recommendations.

This works only for Event-based recommendations, like Personalized recommendations(Collaborative Filtering) or Related Items support special.

Also, “Explain” method doesn’t execute filters and custom scoring functions.