Item Segmentations

Item Segmentation is an abstraction on top of the catalog of Items. It allows you to group the Items into Segments based on their properties. The Segments can be then recommended to your users.

_images/segmentations.png

It is common to Segment the Items for example by:

  • category or brand in the case of products

  • genre in the case of movies

  • artist in the case of songs

  • belonging to particular homepage rows - see this section for other advanced use cases

Recommend Item Segments To User can be then used to recommend the top categories / top brands / top genres / top artists for a particular user.

It is also possible to get related Segments to a particular item (e.g. brands related to a product, artists related to a song), Segments related to another Item Segment (e.g. artists similar to a particular artist, brands related to a brand), or search within the Segments (search brands, artists, etc. with a search query).

A step-by-step video tutorial on Item Segmentations:

Creating an Item Segmentation

There are multiple ways how a Segmentation can be defined.

The most frequently used and the easiest to set up is Property-based Segmentation.

See this section for info on more advanced options for creating the Segmentations.

Property-based Segmentation

Property-based Segmentation groups the Items by the value of a particular property.

The property can be of string or set type.

NULL values are ignored.

Examples

Consider the following data about the Items:

Items used in the examples
Example 1

Segmentation based on the country property (of type string) will create the following three Segments:

Items segmented by the country property

For example, the value of the country property for the it_crowd is GB, and therefore the it_crowd belongs to the GB Segment.

Example 2

Segmentation based on the genres property (of type set) will create the following three Segments:

Items segmented by the genres property

Note that an Item can belong to multiple Segments: In that case, the_silence_of_the_lambs belongs to both Horror and Thriller Segments.

Creating in the Admin UI

Property-based Segmentation in the Admin UI

You can create the Property-based Segmentation in the Admin UI by picking the name of the property

  • Navigate to the Segmentations section

  • Create a new Segmentation of the Property-based type and select by which Item property the Items shall be segmented.

  • Check the preview of the resulting Segments and confirm the setup

Creating via the API

Recommending Segments

Requesting recommendations

The Segments can be recommended or searched using the following endpoints:

Before you can use any of that endpoints, you need to create an Item Segmentation and then set up a Scenario in the Admin UI which will use that Segmentation.

Choose Recommendation type

Create a Scenario which returns Segments

Segmentations picker

Choose the Segmentation which shall be used in the Scenario

The ID of that Scenario needs to be provided in the scenario parameter of the recommendation request:

client.send(new recombee.RecommendItemSegmentsToUser('2c169e575644d840838e', 5,
      {
          'scenario': 'top_categories',
          'cascadeCreate': true
      }
    ),
    (err, recommended) => {
    //...
    }
);
recommended = client.send(RecommendItemSegmentsToUser('2c169e575644d840838e', 5,
                                               scenario='top_categories',
                                               cascade_create=True))
recommended = client.send(RecommendItemSegmentsToUser.new('2c169e575644d840838e', 5,
  {
    'scenario' => 'top_categories',
    'cascadeCreate' => true
  })
)
RecommendationResponse recommended = client.send(new RecommendItemSegmentsToUser("2c169e575644d840838e", 5))
.setScenario("top_categories")
.setCascadeCreate(true);
<?php
$recommended = $client -> send(new Reqs\RecommendItemSegmentsToUser('2c169e575644d840838e', 5,
                                                                    [
                                                                        'scenario' => 'top_categories',
                                                                        'cascadeCreate' => true
                                                                    ])
                              );
?>
RecommendationResponse recommended = client.Send(new RecommendItemSegmentsToUser("2c169e575644d840838e", 5,
                                                                                 scenario: "top_categories",
                                                                                 cascadeCreate: true));
client.send(new rqs.RecommendItemSegmentsToUser('2c169e575644d840838e', 5,
      {
          'scenario': 'top_categories',
          'cascadeCreate': true
      }
    ),
    (err, recommended) => {
    //...
    }
);
GET /myDb/recomms/users/2c169e575644d840838e/item-segments/?count=10&scenario=top_categories&cascadeCreate=true

These are some examples of how recommending Segments can be used on your website or in your app:

Filtering and Boosting

Recommended Segments can be filtered or boosted using ReQL. You can access the ID of a Segment in ReQL using 'segmentId'.

Examples of filters:

  • Do not recommend the coupons category to the users

'segmentId' != "coupons"
  • Do not recommend horror movies to kids

if context_user["is_child_profile"] then 'segmentId' != "Horror" else true

Example of a booster:

  • Boosting the Editors Pick section

if 'segmentId' == "Editors Pick" then 2 else 1

Advanced options for creating the Segmentations

Manual ReQL Segmentation

With Manual ReQL Segmentation, you specify individual Segments of the Segmentation.

Each Segment is defined by a ReQL filter: Items passing the filter belong to the Segment.

Example

Consider the same data about the Items as in this section.

You can create an Item Segmentation where each Segment will represent one row on the homepage.

With defined Segments as follows:

Manual defined Segments

Items get segmented in this way:

Items segmented to the defined manual Segments

You will get the optimal order of these homepage rows for the particular user by calling the Recommend Item Segments To User endpoint.

Creating in the Admin UI

Manual ReQL Segmentation in the Admin UI

You can create individual Segments of the Manual ReQL Segmentation in the Admin UI

  • Navigate to the Segmentations section

  • Give the Segmentation a title, which gets translated into the Segmentation ID, and optionally give also a description

  • Create the first Segment by giving it a name (which gets again translated into the Segment’s ID) and providing the ReQL filter

    • You can check which Items belong to the Segment by clicking on Preview items

  • Click Add Segment to add another Segment

  • When satisfied with the setup, click Create to confirm it

Creating via the API

Auto ReQL Segmentation

Auto ReQL Segmentation is specified by a ReQL expression that for each Item returns a set of Segments to which the Item belongs.

The individual Segments don’t need to be predefined in any way.

Examples

Example 1

The following expression returns the set of genres:

'genres'

For example, for johnny_english it returns {"Comedy"} and for the_silence_of_the_lambs it returns {"Horror", "Thriller"}.

Therefore it behaves the same as the Property-based Segmentation using the genres property:

Items segmented by the genres property
Example 2

The following Segmentation put the Items into Segments according to their genres and also adds a Critically Acclaimed Segment for items with 'critically_acclaimed' == true.

'genres' + (if 'critically_acclaimed' then {"Critically Acclaimed"} else {})

For example, for johnny_english it returns {"Comedy"}, for friends it returns {"Comedy", "Critically Acclaimed"}, and for the_silence_of_the_lambs it returns {"Horror", "Thriller", "Critically Acclaimed"}.

Items segmented by the ReQL expression
Example 3

The Segments of the following Segmentation are a combination of the Item’s genres and country (British comedies, US thrillers, etc.).

map(lambda 'genre': 'genre' + "-" + 'country', 'genres')

For example, for johnny_english it returns {"Comedy-GB"}, for friends it returns {"Comedy-US"}, and for the_silence_of_the_lambs it returns {"Horror-US", "Thriller-US"}.

Items segmented by the ReQL expression

Creating in the Admin UI

Auto ReQL Segmentation in the Admin UI

You can specify the ReQL expression for the Auto ReQL Segmentation in the Admin UI

  • Navigate to the Segmentations section

  • Create a new Segmentation of the Auto ReQL type

  • Give the Segmentation a title, which gets translated into the Segmentation ID, and optionally give also a description

  • Provide the ReQL expression which returns a set of Segments to which an Item belongs

  • Check the preview of the resulting Segments and confirm the setup

Creating via the API