Segmentations Definition

Segmentations allow you to group the Items into various segments: For example segment articles or products by categories, segment movies by genres, etc. The Segmentations can be used in recommendations (e.g. return the most relevant categories for a user).

See this section for more info.

Property Based Segmentation

Property-based Segmentation groups the Items by the value of a particular property. See this section for more info.

put

Create Property Based Segmentation

Creates a Segmentation that splits the items into segments based on values of a particular item property.

A segment is created for each unique value of the property. In case of set properties, a segment is created for each value in the set. Item belongs to all these segments.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new requests.CreatePropertyBasedSegmentation(segmentationId, sourceType, propertyName, {
  // optional parameters:
  title: 'Categories',                                    // string
  description: 'Segmentation based on item categories.',  // string
}));

Since version

4.1.0

Parameters

databaseId

String

Located in: path

Required: Yes

Since version: 4.1.0

ID of your database.

segmentationId

String

Located in: path

Required: Yes

Since version: 4.1.0

ID of the newly created Segmentation

sourceType

String

Located in: body

Required: Yes

Since version: 4.1.0

What type of data should be segmented. Currently only items are supported.

propertyName

String

Located in: body

Required: Yes

Since version: 4.1.0

Name of the property on which the Segmentation should be based

title

String

Located in: body

Required: No

Since version: 4.1.0

Human-readable name that is shown in the Recombee Admin UI.

description

String

Located in: body

Required: No

Since version: 4.1.0

Description that is shown in the Recombee Admin UI.

Responses

201

successful operation

400

segmentationId does not match ^[a-zA-Z0-9_-:@.]+$, property is not of supported type (string or set).

404

Property does not exist.

post

Update Property Based Segmentation

Updates a Property Based Segmentation

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new requests.UpdatePropertyBasedSegmentation(segmentationId, {
  // optional parameters:
  propertyName: 'categories',                             // string
  title: 'Categories',                                    // string
  description: 'Segmentation based on item categories.',  // string
}));

Since version

4.1.0

Parameters

databaseId

String

Located in: path

Required: Yes

Since version: 4.1.0

ID of your database.

segmentationId

String

Located in: path

Required: Yes

Since version: 4.1.0

ID of the updated Segmentation

propertyName

String

Located in: body

Required: No

Since version: 4.1.0

Name of the property on which the Segmentation should be based

title

String

Located in: body

Required: No

Since version: 4.1.0

Human-readable name that is shown in the Recombee Admin UI.

description

String

Located in: body

Required: No

Since version: 4.1.0

Description that is shown in the Recombee Admin UI.

Responses

201

successful operation

400

segmentationId does not match ^[a-zA-Z0-9_-:@.]+$, property is not of supported type (string or set).

404

Property does not exist. Segmentation with given ID does not exist.

Manual ReQL Segmentation

Segmentation whose Segments are defined by ReQL filters. See this section for more info.

put

Create Manual ReQL Segmentation

Segment the items using multiple ReQL filters.

Use the Add Manual ReQL Items Segment endpoint to create the individual segments.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new requests.CreateManualReqlSegmentation(segmentationId, sourceType, {
  // optional parameters:
  title: 'Homepage Rows',                                                       // string
  description: 'Segmentation grouping items into rows shown on the homepage.',  // string
}));

Since version

4.1.0

Parameters

databaseId

String

Located in: path

Required: Yes

Since version: 4.1.0

ID of your database.

segmentationId

String

Located in: path

Required: Yes

Since version: 4.1.0

ID of the newly created Segmentation

sourceType

String

Located in: body

Required: Yes

Since version: 4.1.0

What type of data should be segmented. Currently only items are supported.

title

String

Located in: body

Required: No

Since version: 4.1.0

Human-readable name that is shown in the Recombee Admin UI.

description

String

Located in: body

Required: No

Since version: 4.1.0

Description that is shown in the Recombee Admin UI.

Responses

201

successful operation

400

segmentationId does not match ^[a-zA-Z0-9_-:@.]+$.

Examples

Example Create a Manual ReQL Segmentation and set up its Segments

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

Here we create two Segments in the homepage-rows Segmentation:

made-in-us contains items that were created in the US
short-laughs contains comedies with runtime under 30 minutes

See this section for more info.

Python Ruby Java Node.js PHP C#Go

Copy

reqs = [
  CreateManualReqlSegmentation("homepage-rows", "items"),
  AddManualReqlSegment("homepage-rows", "made-in-us", "'country' == \"US\" "),
  AddManualReqlSegment("homepage-rows", "short-laughs", "\"Comedy\" in 'genres' and 'runtime' < 30")
]

responses = client.send(Batch(reqs))

post

Update Manual ReQL Segmentation

Update an existing Segmentation.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new requests.UpdateManualReqlSegmentation(segmentationId, {
  // optional parameters:
  title: 'Homepage Rows',                                                       // string
  description: 'Segmentation grouping items into rows shown on the homepage.',  // string
}));

Since version

4.1.0

Parameters

databaseId

String

Located in: path

Required: Yes

Since version: 4.1.0

ID of your database.

segmentationId

String

Located in: path

Required: Yes

Since version: 4.1.0

ID of the updated Segmentation

title

String

Located in: body

Required: No

Since version: 4.1.0

Human-readable name that is shown in the Recombee Admin UI.

description

String

Located in: body

Required: No

Since version: 4.1.0

Description that is shown in the Recombee Admin UI.

Responses

201

successful operation

400

segmentationId does not match ^[a-zA-Z0-9_-:@.]+$. Given Segmentation is of different type.

404

Segmentation with given ID does not exist.

put

Add Manual ReQL Segment

Adds a new Segment into a Manual ReQL Segmentation.

The new Segment is defined by a ReQL filter that returns true for an item in case that this item belongs to the segment.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new requests.AddManualReqlSegment(segmentationId, segmentId, filter, {
  // optional parameters:
  title: 'Newly published',  // string
}));

Since version

4.1.0

Parameters

databaseId

String

Located in: path

Required: Yes

Since version: 4.1.0

ID of your database.

segmentationId

String

Located in: path

Required: Yes

Since version: 4.1.0

ID of the Segmentation to which the new Segment should be added

segmentId

String

Located in: path

Required: Yes

Since version: 4.1.0

ID of the newly created Segment

filter

String

Located in: body

Required: Yes

Since version: 4.1.0

ReQL filter that returns true for items that belong to this Segment. Otherwise returns false.

title

String

Located in: body

Required: No

Since version: 4.1.0

Human-readable name of the Segment that is shown in the Recombee Admin UI.

Responses

201

successful operation

400

segmentationId or segmentId does not match ^[a-zA-Z0-9_-:@.]+$. Segmentation is of wrong type.

404

Segmentation with given ID does not exist.

post

Update Manual ReQL Segment

Update definition of the Segment.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new requests.UpdateManualReqlSegment(segmentationId, segmentId, filter, {
  // optional parameters:
  title: 'Newly published',  // string
}));

Since version

4.1.0

Parameters

databaseId

String

Located in: path

Required: Yes

Since version: 4.1.0

ID of your database.

segmentationId

String

Located in: path

Required: Yes

Since version: 4.1.0

ID of the Segmentation to which the updated Segment belongs

segmentId

String

Located in: path

Required: Yes

Since version: 4.1.0

ID of the Segment that will be updated

filter

String

Located in: body

Required: Yes

Since version: 4.1.0

ReQL filter that returns true for items that belong to this Segment. Otherwise returns false.

title

String

Located in: body

Required: No

Since version: 4.1.0

Human-readable name of the Segment that is shown in the Recombee Admin UI.

Responses

201

successful operation

400

segmentationId or segmentId does not match ^[a-zA-Z0-9_-:@.]+$. Segmentation is of wrong type.

404

Segmentation with given ID does not exist. Segment with given ID does not exist in the Segmentation.

delete

Delete Manual ReQL Segment

Delete a Segment from a Manual ReQL Segmentation.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new requests.DeleteManualReqlSegment(segmentationId, segmentId));

Since version

4.1.0

Parameters

databaseId

String

Located in: path

Required: Yes

Since version: 4.1.0

ID of your database.

segmentationId

String

Located in: path

Required: Yes

Since version: 4.1.0

ID of the Segmentation from which the Segment should be deleted

segmentId

String

Located in: path

Required: Yes

Since version: 4.1.0

ID of the Segment that should be deleted

Responses

201

successful operation

400

segmentationId or segmentId does not match ^[a-zA-Z0-9_-:@.]+$. Segmentation is of wrong type.

404

Segmentation with given ID does not exist. Segment with given ID does not exist in the Segmentation.

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. See this section for more info.

put

Create Auto ReQL Segmentation

Segment the items using a ReQL expression.

For each item, the expression should return a set that contains IDs of segments to which the item belongs to.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new requests.CreateAutoReqlSegmentation(segmentationId, sourceType, expression, {
  // optional parameters:
  title: 'Country and Genre',                                               // string
  description: 'Segmentation combining item genre and country of origin.',  // string
}));

Since version

4.1.0

Parameters

databaseId

String

Located in: path

Required: Yes

Since version: 4.1.0

ID of your database.

segmentationId

String

Located in: path

Required: Yes

Since version: 4.1.0

ID of the newly created Segmentation

sourceType

String

Located in: body

Required: Yes

Since version: 4.1.0

What type of data should be segmented. Currently only items are supported.

expression

String

Located in: body

Required: Yes

Since version: 4.1.0

ReQL expression that returns for each item a set with IDs of segments to which the item belongs

title

String

Located in: body

Required: No

Since version: 4.1.0

Human-readable name that is shown in the Recombee Admin UI.

description

String

Located in: body

Required: No

Since version: 4.1.0

Description that is shown in the Recombee Admin UI.

Responses

201

successful operation

400

segmentationId does not match ^[a-zA-Z0-9_-:@.]+$, ReQL expression is invalid.

Examples

Example Create an Auto ReQL Segmentation

Create a Segmentation, whose Segments combine the country of origin and the genre.

See this section for more info.

Python Ruby Java Node.js PHP C#Go

Copy

req = CreateAutoReqlSegmentation(
    "country-and-genre",
    "items",
    "map(lambda 'genre': 'genre' + \"-\" + 'country', 'genres')",
)

response = client.send(req)

post

Update Auto ReQL Segmentation

Update an existing Segmentation.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new requests.UpdateAutoReqlSegmentation(segmentationId, {
  // optional parameters:
  expression: 'map(lambda \'genre\': \'genre\' + "-" + \'country\', \'genres\')',  // string
  title: 'Country and Genre',                                                      // string
  description: 'Segmentation combining item genre and country of origin.',         // string
}));

Since version

4.1.0

Parameters

databaseId

String

Located in: path

Required: Yes

Since version: 4.1.0

ID of your database.

segmentationId

String

Located in: path

Required: Yes

Since version: 4.1.0

ID of the updated Segmentation

expression

String

Located in: body

Required: No

Since version: 4.1.0

ReQL expression that returns for each item a set with IDs of segments to which the item belongs

title

String

Located in: body

Required: No

Since version: 4.1.0

Human-readable name that is shown in the Recombee Admin UI.

description

String

Located in: body

Required: No

Since version: 4.1.0

Description that is shown in the Recombee Admin UI.

Responses

201

successful operation

400

segmentationId does not match ^[a-zA-Z0-9_-:@.]+$. ReQL expression is invalid. Given Segmentation is of different type.

404

Segmentation with given ID does not exist.

General

get

List Segmentations

Return all existing items Segmentations.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

const result = await client.send(new requests.ListSegmentations(sourceType));

Since version

4.1.0

Calls Limit Per Minute

Parameters

databaseId

String

Located in: path

Required: Yes

Since version: 4.1.0

ID of your database.

sourceType

String

Located in: query

Required: Yes

Since version: 4.1.0

List Segmentations based on a particular type of data. Currently only items are supported.

Responses

200

{
  "segmentations": [
    {
      "segmentationId": "category",
      "sourceType": "items",
      "segmentationType": "property",
      "title": "Category Segmentation",
      "description": "Groups items by their category"
    },
    {
      "segmentationId": "homepage-rows",
      "sourceType": "items",
      "segmentationType": "manualReQL",
      "title": "Homepage Rows",
      "description": "Defines individual content rows that can be shown on the homepage"
    }
  ]
}

get

Get Segmentation

Get existing Segmentation.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

const result = await client.send(new requests.GetSegmentation(segmentationId));

Since version

4.1.0

Parameters

databaseId

String

Located in: path

Required: Yes

Since version: 4.1.0

ID of your database.

segmentationId

String

Located in: path

Required: Yes

Since version: 4.1.0

ID of the Segmentation that should be returned

Responses

200

{
  "segmentationId": "category",
  "sourceType": "items",
  "segmentationType": "property",
  "title": "Category Segmentation",
  "description": "Groups items by their category"
}

404

Segmentation with given ID does not exist.

delete

Delete Segmentation

Delete existing Segmentation.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new requests.DeleteSegmentation(segmentationId));

Since version

4.1.0

Parameters

databaseId

String

Located in: path

Required: Yes

Since version: 4.1.0

ID of your database.

segmentationId

String

Located in: path

Required: Yes

Since version: 4.1.0

ID of the Segmentation that should be deleted

Responses

200

successful operation

404

Segmentation with given ID does not exist.

docs.recombee.com