User Documentation
API Clients & Integrations
Scenario Recipes
Recommendation Logics
Logic allows you to specify the desired behavior of the recommendation model.
While Recombee is generally a domain-independent recommendation engine and the default model is optimized to work well in most cases, we have used our experience in some frequent domains to setup some tuned models, and you can now easily pick the logic that is tailored for the particular case.
Setting Logic in the Admin UI
You can assign a particular logic to a Scenario in Admin UI.
Alternatively you can use API parameter to set the logic.
List of Logics
There is a list logics available for most of the databases. Some databases tweaked by the Recombee support team may have custom logic.
Tip
See the Integration Tips if you are not sure which logic should be used in your use case.
Universal Models
Universal Recombee models for the most common use-cases.
recombee:default
Default model ensemble aiming to work well in most common use cases. It is an ensemble of collaborative filtering and content-based recommendation, backed by popularity-based models when there's not enough data in the given context. The ensemble is being continuously optimized by AI so it automatically adapts to incoming data.
recombee:homepage
Universal model ensemble suitable for putting recommendations on the homepage / welcome-screen scenarios.
Applicable to endpoints
recombee:personal
Universal model ensemble suitable for user-based recommendations reflecting the personal tastes of the current user.
Applicable to endpoints
Requirements
There must be interaction data for the user.
recombee:similar
Universal model ensemble suitable for either recommending items which are similar to the given item (in case of Items-to-Item recommendation), or recommending users who are similar to the given user (in case of Users-to-User recommendation).
Applicable to endpoints
recombee:popular
Universal model suitable for recommending globally popular items, taking into account all interaction types. More important actions (purchases, cart-additions) have higher weight for computing the popularity than less important actions (detail-views).
Applicable to endpoints
Requirements
Interaction data (Detail Views/Purchases/Cart Additions) must be present.
Parameters
timePeriod
double
Default: 1209600
The time period in seconds (from now to the past) in which the popularity is measured. For example, by providing value of 7200, you will get the items most popular (and possibly trending) in last 2 hours, while when providing 1209600 (that is 14*24*3600), you will get items popular during much longer period of the last 14 days.
userSegmentFilter
string
Default: true
ReQL filter on top of user properties defining the segment of users among whom the popularity is calculated. For example, when user properties like profession and country are provided for some users, you may only ask for items popular among software developers in US and Canada: 'profession'=="software developer" and 'country' in {"US", "CA"}.
interactionTypes
Set of enum values
Default: [bookmarks, cartAdditions, detailViews, purchases, ratings, viewPortions]
Allowed Values: bookmarks | cartAdditions | detailViews | purchases | ratings | viewPortions
Interaction types to be taken into account when computing the popularity. By default, all the interactions are taken into account. But for example by providing only ["purchases"], you will retrieve items which are most frequently purchased, no matter how frequently are they (or the other items) viewed, bookmarked, etc.
recombee:recently-viewed
Model returning the list of recently viewed items for a particular user.
Applicable to endpoints
Requirements
Detail Views must exist for the user.
Parameters
maxAge
double
Default: 1209600
Maximal age of the DetailView in seconds since the current timestamp.
recencyOrdering
enum
Default: descending
Allowed Values: ascending | descending
Order in which the items are returned with regard to the time when they were interacted. When the order is descending, the last interacted item is at the beginning of the list of recommendations. When it is ascending, the first interacted item matching the maxAge condition is at the beginning of the list.
recombee:visually-similar
Model recommending similar items based on visual similarity (using deep-learning neural networks to process the images provided through the image properties). While the image similarity can take part in other logics as well, in recombee:visually-similar, it is explicitly used as the primary model. Image processing may take some time. Therefore, changes in image item properties do not take effect in real-time. The functionality is still in beta mode.
Applicable to endpoints
Requirements
Some image properties must be defined for items, with valid image links provided for the majority of the items in the catalog.
Parameters
useFallbackModels
boolean
Default: false
Enable fallback models to make the recommendations if the model based on visual similarity cannot be used (e.g. due to a missing image for the given source item).
recombee:similar-properties
Model recommending similar items based on item properties (numerical values, sets, and texts). While property values can take part in other logics, in recombee:similar-properties, they are explicitly used as the primary data source for recommending similar items or uses. Various machine-learning methods, including NLP deep-learning networks that process unstructured text descriptions, are used to compute the similarities.
Applicable to endpoints
Requirements
Some properties must exist for the items/users, depending on the used API endpoint.
Parameters
useFallbackModels
boolean
Default: false
Enable fallback models to make recommendations if the model based on item properties cannot be used (e.g. due to missing property values for the given source item).
recombee:emailing
Model ensemble suitable for recommending items in periodic e-mailing campaigns. It contains fine-tuned rotation settings so that the set of recommended items for a particular user changes with each e-mail sent. By default, rotation only takes into account recommendations (e-mails) at most 14 days old. Should a longer time period be needed for your use case, kindly contact support@recombee.com.
Applicable to endpoints
Parameters
rotationPolicy
enum
Default: smart
Allowed Values: smart | total
A policy determining how strictly should already recommended items be rotated. The default option "smart" contains fine-tuned rotation settings, which take into account the position of recommended items and enable some of the items to re-appear in further e-mails. Option "total" never recommends items that have already appeared in previous e-mails.
recombee:custom-sort
Model suitable for recommending items ordered by a ReQL expression given as a booster
Applicable to endpoints
Search
Models for both personalized and non-personalized fulltext search.
search:personalized
Smart personalized fulltext search which takes into account both the search query and the personal preferences of the user.
Applicable to endpoints
Parameters
personalizationImpact
enum
Default: medium
Allowed Values: low | medium | high
Determines whether personalization or full-text should have a higher priority in the ranking of the items.
search:non-personalized
Non-personalized fulltext search, based purely on how well the search query is matched.
Applicable to endpoints
search:semantic
Semantic search utilizes a large language model (LLM) to improve search accuracy by understanding the intent and context behind user queries.
Instead of relying solely on keyword matches, the system comprehends the semantic meaning of queries and retrieves results that align with the user's intentions. This advanced Logic delivers more accurate, context-aware search results, even when the query terms differ from the content in the database.
This Logic can be enabled upon request for Recombee Premium customers.
This Logic is not available in new databases by default. Please contact support@recombee.com if you want to use it.
Applicable to endpoints
E-commerce
Models specifically tuned for E-Commerce use-cases.
ecommerce:homepage
Model ensemble suitable for recommending products on homepage/welcome page in E-Commerce and online retail systems.
Applicable to endpoints
ecommerce:similar-products
Model ensemble suitable for recommending similar products (alternatives) to a source (currently viewed) product.
Applicable to endpoints
ecommerce:cross-sell
Model ensemble suitable for recommending compatible/complementary products. In user-based case, the products are compatible with those that the user has already put to the shopping cart. In item-based case, they are compatible with the source (currently viewed) item.
Applicable to endpoints
Requirements
Purchases must be present for the item/user.
ecommerce:bestseller
Model suitable for recommending globally most purchased items.
Applicable to endpoints
Requirements
Purchases must be present in the database.
ecommerce:similarly-purchasing
Recommends users with similar purchasing behavior as the source user.
Applicable to endpoints
Requirements
Purchases must be present for the user.
Video
Set of fine-tuned Video logics, specifically designed for VOD and similar use cases.
video:continue-watching
Model ensemble suitable for recommending partially watched movies or episodes, or the next episode from a watched series.
This Logic is not available in new databases by default. Please contact support@recombee.com if you want to use it.
Applicable to endpoints
Parameters
watchingStartedPercentage
int
Default: 10
Percentage of an asset length for it to be considered as being watched.
watchingCompletedPercentage
int
Default: 90
Percentage of an asset length for it to be considered as completely watched.
assetType
enum
Default: movies+episodes
Allowed Values: movies | episodes | movies+episodes
Asset type to be recommended.
video:personal
Model ensemble suitable for recommending personalized rows on the homepage or browse pages. Rows with specific content (e.g. award-winning movies) can be set up by applying filters.
This Logic is not available in new databases by default. Please contact support@recombee.com if you want to use it.
Applicable to endpoints
Parameters
assetType
enum
Default: movies+episodes
Allowed Values: movies | episodes | series | movies+episodes | movies+series
Asset type to be recommended.
excludeAlreadyWatched
boolean
Default: true
Exclude already watched assets.
video:segments-for-you
Model ensemble suitable for recommending favorite segments (genres, actors, ...) for a specific user. A particular segmentation must exist beforehand.
This Logic is not available in new databases by default. Please contact support@recombee.com if you want to use it.
Applicable to endpoints
video:popular
Model ensemble suitable for recommending globally popular items.
This Logic is not available in new databases by default. Please contact support@recombee.com if you want to use it.
Applicable to endpoints
Parameters
timePeriod
double
Default: 1209600
The time period in seconds (from now to the past) in which the popularity is measured. For example, by providing value of 7200, you will get the items most popular (and possibly trending) in last 2 hours, while when providing 1209600 (that is 14*24*3600), you will get items popular during much longer period of the last 14 days.
userSegmentFilter
string
Default: true
ReQL filter on top of user properties defining the segment of users among whom the popularity is calculated. For example, when user properties like profession and country are provided for some users, you may only ask for items popular among software developers in US and Canada: 'profession'=="software developer" and 'country' in {"US", "CA"}.
assetType
enum
Default: movies+episodes
Allowed Values: movies | episodes | series | movies+episodes | movies+series
Asset type to be recommended.
excludeAlreadyWatched
boolean
Default: false
Exclude already watched assets.
video:editors-picks
Model ensemble suitable for recommendations of hand-picked editorial content.
This Logic is not available in new databases by default. Please contact support@recombee.com if you want to use it.
Applicable to endpoints
Parameters
picks
item-ids-array
Default: []
List of items to be recommended.
excludeAlreadyWatched
boolean
Default: false
Exclude already watched assets.
personalizedReordering
boolean
Default: false
Reorder picked assets in a personalized way for the user.
video:more-like-this
Model ensemble suitable for recommending similar assets on the asset detail page.
This Logic is not available in new databases by default. Please contact support@recombee.com if you want to use it.
Applicable to endpoints
Parameters
assetType
enum
Default: movies+episodes
Allowed Values: movies | episodes | series | movies+episodes | movies+series
Asset type to be recommended.
excludeAlreadyWatched
boolean
Default: false
Exclude already watched assets.
video:watch-next
Model ensemble suitable for end-of-playback recommendations embedded in a video player.
This Logic is not available in new databases by default. Please contact support@recombee.com if you want to use it.
Applicable to endpoints
Parameters
assetType
enum
Default: movies+episodes
Allowed Values: episodes | movies | movies+episodes
Asset type to be recommended.
excludeAlreadyWatched
boolean
Default: false
Exclude already watched assets.
video:episodes-list
Model ensemble suitable for reverse-chronological listing episodes of a particular series.
This Logic is not available in new databases by default. Please contact support@recombee.com if you want to use it.
Applicable to endpoints
Parameters
excludeAlreadyWatched
boolean
Default: false
Exclude already watched assets.
video:search
Smart personalized full-text search suitable for searching movies, series, and episodes.
This Logic is not available in new databases by default. Please contact support@recombee.com if you want to use it.
Applicable to endpoints
Parameters
assetType
enum
Default: movies+episodes
Allowed Values: movies | episodes | series | movies+episodes | movies+series
Asset type to be recommended.
personalizationImpact
enum
Default: medium
Allowed Values: low | medium | high
Determines whether personalization or full-text should have a higher priority in the ranking of the items.
video:search-segments
Smart personalized full-text search suitable for searching segments (genres, actors, ...). A particular segmentation must exist beforehand.
This Logic is not available in new databases by default. Please contact support@recombee.com if you want to use it.
Applicable to endpoints
video:emailing
Model ensemble suitable for sending personalized emails with personalized content for the user. It contains fine-tuned rotation settings so that the set of recommended assets for a particular user changes with each e-mail sent.
This Logic is not available in new databases by default. Please contact support@recombee.com if you want to use it.
Applicable to endpoints
Parameters
assetType
enum
Default: movies+episodes
Allowed Values: movies | episodes | series | movies+episodes | movies+series
Asset type to be recommended.
rotationPolicy
enum
Default: smart
Allowed Values: smart | total
A policy determining how strictly should already recommended items be rotated. The default option "smart" contains fine-tuned rotation settings, which take into account the position of recommended items and enable some of the items to re-appear in further e-mails. Option "total" never recommends items that have already appeared in previous e-mails.
News
Set of fine-tuned News Logics, specifically crafted to enhance recommendation experiences for news platforms, ensuring relevance and timeliness.
news:daily-news
Model ensemble optimized for high-visibility placements.
It ensures users stay connected to the most significant news stories while maintaining a personalized experience based on their past behavior.
It caters to frequent visitors by consistently offering fresh, relevant content.
Applicable to endpoints
Parameters
editorialPicks
item-ids-array
Default: []
A selection of editorially chosen items that are prepended to the recommended content list, ensuring these highlighted items are seen first by the user.
publishedTimestamp
property
Default: None
Property indicating the publication date of articles, used to assess content freshness.
news:personal
Model ensemble providing individualized content suggestions, carefully selecting the best choices from the catalog to match each user's specific interests.
It is particularly suitable for the For You scenarios, where personalized recommendations are essential.
Applicable to endpoints
news:read-next
Model ensemble recommending personalized articles most likely to engage users after they finish reading the current article.
It considers the content of the current article and analyzes both recent and long-term user behavior to encourage continued reading and extend visit duration.
Suitable for Continue Reading or You Might Also Like scenarios.
Applicable to endpoints
news:trending
Model ensemble recommending news articles that are currently trending, providing users with content that is gaining widespread interest and should not be missed.
Suitable for the Trending Articles scenario.
Applicable to endpoints
Parameters
excludeAlreadyRead
boolean
Default: true
Excludes articles the user has already read.
news:popular
Model ensemble recommending articles that are highly popular within a specified time period.
It is ideal for Popular Articles scenario, allowing users to see what others find interesting.
Applicable to endpoints
Parameters
excludeAlreadyRead
boolean
Default: true
Excludes articles the user has already read.
timePeriod
double
Default: 1209600
The time frame in seconds (from now into the past) used to measure item popularity.
For example, a value of 7200 retrieves items popular in the past 2 hours, while 1209600 (i.e., 14*24*3600) retrieves items popular over the last 14 days.
news:recent
Model ensemble showcasing the most recently published articles, ensuring users stay updated with the latest content.
Suitable for the Latest News scenario.
Applicable to endpoints
Parameters
excludeAlreadyRead
boolean
Default: true
Excludes articles the user has already read.
publishedTimestamp
property
Default: None
Property indicating the publication date of articles, used to assess content freshness.
news:related
Model ensemble recommending articles that are related to the current article, providing users with a seamless continuation of their reading experience on a given topic.
Suitable for the Related Articles scenario.
Applicable to endpoints
Parameters
news:categories-for-you
Model ensemble recommending categories relevant to the user based on their previously read articles.
Suitable, for example, for personalized re-ordering of sections on the homepage.
Assumes the scenario is configured with an Item Segmentation representing article categories.
Applicable to endpoints
Classified Advertising
Models tailored for classified advertising (real estate, automotive, electronics, services, etc.).
classifieds:homepage
Model ensemble suitable for recommending products on homepage/welcome page of a Classified advertising site.
Applicable to endpoints
classifieds:personal
Model ensemble suitable for recommending picked ads right for the given user. Can be used on different places, such as in-category recommendation when augmented with appropriate ReQL filter.
Applicable to endpoints
classifieds:similar-ads
Model ensemble suitable for recommending ads that are similar to the one which is currently viewed.
Applicable to endpoints
Table of contents
Setting Logic Using API Parameter
The logic can be set per individual recommendation request by passing its name, such as ecommerce:homepage, to the logic parameter.
Copy
client.send(new recombee.RecommendItemsToUser('user-x', 10,
{
logic: 'ecommerce:homepage'
}
), callback
);
Copy
val request = RecommendItemsToUser(
userId = "user-x",
count = 10,
logic = Logic(name = "ecommerce:homepage")
)
val result = client.sendAsync(request)
result.onSuccess { recommendationResponse ->
// Handle the successful response
}
...
Copy
client.send(new rqs.RecommendItemsToUser('user-x', 10, {'logic': 'ecommerce:homepage'}), callback);
Copy
result = client.send(RecommendItemsToUser("user-x", 10, logic="ecommerce:homepage"))
Copy
result = client.send(RecommendItemsToUser.new('user-x', 10, {:logic => 'ecommerce:homepage'}))
Copy
import com.recombee.api_client.bindings.Logic;
RecommendationResponse result = client.send(new RecommendItemsToUser("user-x", 10)
.setLogic(new Logic("ecommerce:homepage"))
);
Copy
<?php
$result = $client->send(new RecommendItemsToUser('user-x', 10, ['logic' => 'ecommerce:homepage']));
?>
Copy
using Recombee.ApiClient.Bindings;
RecommendationResponse result = client.Send(RecommendItemsToUser("user-x", 10,
logic: new Logic("ecommerce:homepage")
)
);
Copy
request := client.NewRecommendItemsToUser("user-x", 10).SetLogic(bindings.Logic{Name: "ecommerce:homepage"})
recommended, err := request.Send()
Copy
GET /my-db-id/recomms/users/user-x/items/?count=10&logic=ecommerce:homepage
Some logic can have parameters - if you specify just name, you will get some reasonable default, but you can tweak the parameters according to your particular needs.
Copy
client.send(new recombee.RecommendItemsToUser('user-x', 10,
{
logic:
{
name: 'recombee:recently-viewed',
settings: {
maxAge: 3*24*60*60
}
}
}), callback
);
Copy
val request = RecommendItemsToUser(
userId = "user-x",
count = 10,
logic = Logic(name = "recombee:recently-viewed", settings = mapOf("maxAge" to 3 * 24 * 60 * 60))
)
val result = client.sendAsync(request)
result.onSuccess { recommendationResponse ->
// Handle the successful response
}
...
Copy
client.send(new rqs.RecommendItemsToUser('user-x', 10,
{
'logic': {
'name': 'recombee:recently-viewed',
'settings': {
'maxAge': 3*24*60*60
}
}
}))
.then((recomms) => {
console.log(recomms);
});
Copy
result = client.send(RecommendItemsToUser("user-x", 10,
logic= {
"name": "recombee:recently-viewed",
"settings": {
"maxAge": 3*24*60*60
}
}
))
Copy
result = client.send(RecommendItemsToUser.new('user-x', 10,
{
'logic' => {
'name' => 'recombee:recently-viewed',
'settings' => {
'maxAge' => 3*24*60*60
}
}
}))
Copy
import com.recombee.api_client.bindings.Logic;
Logic l = new Logic("recombee:recently-viewed", new HashMap<String, Object>() {
{ put("maxAge", 3*24*60*60); }
});
RecommendationResponse result = client.send(new RecommendItemsToUser("user-x", 10)
.setLogic(l));
Copy
<?php
$result = $client->send(new RecommendItemsToUser('user-x', 10,
[
'logic' => [
'name' => 'recombee:recently-viewed',
'settings' => [
'maxAge' => 3*24*60*60
]
]
]));
?>
Copy
using Recombee.ApiClient.Bindings;
Logic l = new Logic("recombee:recently-viewed",
new Dictionary<string, object>() {
{"maxAge", 3*24*60*60}
}
);
var recommendationResponse = client.Send(new RecommendItemsToUser("user-x", 5, logic: l));
Copy
logicSettings := map[string]interface{}{"maxAge": 3 * 24 * 60 * 60}
logic := bindings.Logic{Name: "recombee:recently-viewed", Settings: &logicSettings}
recommended, err := client.NewRecommendItemsToUser("user-x", 10).SetLogic(logic).Send()
Copy
POST /my-db-id/recomms/users/user-x/items/
Body:
{
"count": 10,
"logic": {
"name": "recombee:recently-viewed",
"settings": {
"maxAge": 259200
}
}
}