API Reference

This section lists all the available API endpoints, that allow you to manage item catalog, users, their interactions and get recommendations.

Version: 4.1.0
Base URL: Based on the region of your database
API consumes: application/json
API produces: application/json
Authentication: HMAC (already implemented in the SDKs)

Items

The following methods allow you to maintain the set of items in the catalog. The items are specified using their ids, which are unique string identifiers matching ^[a-zA-Z0-9_-:@.]+$, i.e., they may consist of digits, Latin letters, underscores, colons, minus signs, at signs, and dots.

put

Add Item

Adds new item of the given itemId to the items catalog.

All the item properties for the newly created items are set to null.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.AddItem(itemId));

Copy

Initialization

client.send(AddItem(item_id))

Copy

Initialization

client.send(AddItem.new(itemId))

Copy

Initialization

client.send(new AddItem(String itemId));

Copy

Initialization

<?php
$client->send(new AddItem($item_id));
?>

Copy

Initialization

client.Send(AddItem(string itemId));

Copy

Initialization

request := client.NewAddItem(itemId string)

_, err := request.Send()

Copy

PUT /{databaseId}/items/{itemId}

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

itemId

string

Located in: path

Required: Yes

ID of the item to be created.

Responses

201

Successful operation.

400

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

409

The itemId is already present in the item catalog. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.

delete

Delete Item

Deletes an item of the given itemId from the catalog.

If there are any purchases, ratings, bookmarks, cart additions, or detail views of the item present in the database, they will be deleted in cascade as well. Also, if the item is present in some series, it will be removed from all the series where present.

If an item becomes obsolete/no longer available, it is meaningful to keep it in the catalog (along with all the interaction data, which are very useful), and only exclude the item from recommendations. In such a case, use ReQL filter instead of deleting the item completely.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.DeleteItem(itemId));

Copy

Initialization

client.send(DeleteItem(item_id))

Copy

Initialization

client.send(DeleteItem.new(itemId))

Copy

Initialization

client.send(new DeleteItem(String itemId));

Copy

Initialization

<?php
$client->send(new DeleteItem($item_id));
?>

Copy

Initialization

client.Send(DeleteItem(string itemId));

Copy

Initialization

request := client.NewDeleteItem(itemId string)

_, err := request.Send()

Copy

DELETE /{databaseId}/items/{itemId}

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

itemId

string

Located in: path

Required: Yes

ID of the item to be deleted.

Responses

200

Successful operation.

400

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

404

The itemId is not present in the item catalog. In many cases, you may consider this code a success – it only tells you that nothing has been deleted from the database since the item was already not present. If there is no additional info in the JSON response, you probably have an error in your URL.

get

List Items

Gets a list of IDs of items currently present in the catalog.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ListItems({
  // optional parameters:
  'filter': <string>,
  'count': <integer>,
  'offset': <integer>,
  'returnProperties': <boolean>,
  'includedProperties': <array>
}))
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(ListItems(
    # optional parameters:
    filter=<string>,
    count=<integer>,
    offset=<integer>,
    return_properties=<boolean>,
    included_properties=<array>
  )
)

Copy

Initialization

result = client.send(ListItems.new({
    # optional parameters:
    :filter => <string>,
    :count => <integer>,
    :offset => <integer>,
    :return_properties => <boolean>,
    :included_properties => <array>
  })
)

Copy

Initialization

Item[] result = client.send(new ListItems()
  .setFilter(String filter)
  .setCount(long count)
  .setOffset(long offset)
  .setReturnProperties(boolean returnProperties)
  .setIncludedProperties(String[] includedProperties)
);

Copy

Initialization

<?php
$result = $client->send(new ListItems([
    // optional parameters:
    'filter' => <string>,
    'count' => <integer>,
    'offset' => <integer>,
    'returnProperties' => <boolean>,
    'includedProperties' => <array>
  ])
);
?>

Copy

Initialization

IEnumerable<Item> result = client.Send(ListItems(
    // optional parameters:
    filter: <string>,
    count: <long>,
    offset: <long>,
    returnProperties: <bool>,
    includedProperties: <string[]>
  )
);

Copy

Initialization

request := client.NewListItems()    
    // optional parameters:
    .SetFilter(filter string)
    .SetCount(count int)
    .SetOffset(offset int)
    .SetReturnProperties(returnProperties bool)
    .SetIncludedProperties(includedProperties []string)


result, err := request.Send() // result is of the type []bindings.Item

Copy

GET /{databaseId}/items/list/?filter=<string>
&count=<integer>
&offset=<integer>
&returnProperties=<boolean>
&includedProperties=<array>

Calls Limit Per Minute

100

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

filter

string

Located in: query

Required: No

Boolean-returning ReQL expression, which allows you to filter items to be listed. Only the items for which the expression is true will be returned.

count

integer

Located in: query

Required: No

The number of items to be listed.

offset

integer

Located in: query

Required: No

Specifies the number of items to skip (ordered by itemId).

returnProperties

boolean

Located in: query

Required: No

Since version: 1.4.0

With returnProperties=true, property values of the listed items are returned along with their IDs in a JSON dictionary.

Example response:

  [
    {
      "itemId": "tv-178",
      "description": "4K TV with 3D feature",
      "categories":   ["Electronics", "Televisions"],
      "price": 342,
      "url": "myshop.com/tv-178"
    },
    {
      "itemId": "mixer-42",
      "description": "Stainless Steel Mixer",
      "categories":   ["Home & Kitchen"],
      "price": 39,
      "url": "myshop.com/mixer-42"
    }
  ]

includedProperties

array

Located in: query

Required: No

Since version: 1.4.0

Allows specifying which properties should be returned when returnProperties=true is set. The properties are given as a comma-separated list.

Example response for includedProperties=description,price:

  [
    {
      "itemId": "tv-178",
      "description": "4K TV with 3D feature",
      "price": 342
    },
    {
      "itemId": "mixer-42",
      "description": "Stainless Steel Mixer",
      "price": 39
    }
  ]

Responses

200

Successful operation.

[
  "item-1",
  "item-2",
  "item-3"
]

404

If present, filter contains a non-existing item property.

delete

Delete More Items

Deletes all the items that pass the filter.

If an item becomes obsolete/no longer available, it is meaningful to keep it in the catalog (along with all the interaction data, which are very useful) and only exclude the item from recommendations. In such a case, use ReQL filter instead of deleting the item completely.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.DeleteMoreItems(filter))
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(DeleteMoreItems(filter))

Copy

Initialization

result = client.send(DeleteMoreItems.new(filter))

Copy

Initialization

DeleteMoreItemsResponse result = client.send(new DeleteMoreItems(String filter));

Copy

Initialization

<?php
$result = $client->send(new DeleteMoreItems($filter));
?>

Copy

Initialization

DeleteMoreItemsResponse result = client.Send(DeleteMoreItems(string filter));

Copy

Initialization

request := client.NewDeleteMoreItems(filter string)

result, err := request.Send() // result is of the type bindings.DeleteMoreItemsResponse

Copy

DELETE /{databaseId}/more-items/
Body (application/json):
{
  "filter" => <string>
}

Since version

3.3.0

Calls Limit Per Minute

1000

Parameters

databaseId

string

Located in: path

Required: Yes

Since version: 3.3.0

ID of your database.

filter

string

Located in: body

Required: Yes

Since version: 3.3.0

A ReQL expression, which returns true for the items that shall be updated.

Responses

200

Successful operation.

{
  "itemIds": [
    "item-42",
    "item-125",
    "item-11"
  ],
  "count": 3
}

400

Invalid filter.

Item Properties

Item properties definition

Item properties are used for modeling your domain. The following methods allow the definition of item properties. The properties may be thought of as columns in a relational database table.

put

Add Item Property

Adding an item property is somewhat equivalent to adding a column to the table of items. The items may be characterized by various properties of different types.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.AddItemProperty(propertyName, type));

Copy

Initialization

client.send(AddItemProperty(property_name, type))

Copy

Initialization

client.send(AddItemProperty.new(propertyName, type))

Copy

Initialization

client.send(new AddItemProperty(String propertyName, String type));

Copy

Initialization

<?php
$client->send(new AddItemProperty($property_name, $type));
?>

Copy

Initialization

client.Send(AddItemProperty(string propertyName, string type));

Copy

Initialization

request := client.NewAddItemProperty(propertyName string, type string)

_, err := request.Send()

Copy

PUT /{databaseId}/items/properties/{propertyName}?type=<string>

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

propertyName

string

Located in: path

Required: Yes

Name of the item property to be created. Currently, the following names are reserved: id, itemid, case-insensitively. Also, the length of the property name must not exceed 63 characters.

type

string

Located in: query

Required: Yes

Value type of the item property to be created. One of: int, double, string, boolean, timestamp, set, image or imageList.

int- Signed integer number.
double - Floating point number. It uses 64-bit base-2 format (IEEE 754 standard).
string - UTF-8 string.
boolean - true / false
timestamp - Value representing date and time.
set - Set of strings.
image - URL of an image (jpeg, png or gif).
imageList - List of URLs that refer to images.

Responses

201

Successful operation.

400

Property name does not match ^[a-zA-Z0-9_-:]+$, or it is a reserved keyword (''id'', ''itemid''), or its length exceeds 63 characters. Type information is missing, or the given type is invalid.

409

Property of the given name is already present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.

delete

Delete Item Property

Deleting an item property is roughly equivalent to removing a column from the table of items.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.DeleteItemProperty(propertyName));

Copy

Initialization

client.send(DeleteItemProperty(property_name))

Copy

Initialization

client.send(DeleteItemProperty.new(propertyName))

Copy

Initialization

client.send(new DeleteItemProperty(String propertyName));

Copy

Initialization

<?php
$client->send(new DeleteItemProperty($property_name));
?>

Copy

Initialization

client.Send(DeleteItemProperty(string propertyName));

Copy

Initialization

request := client.NewDeleteItemProperty(propertyName string)

_, err := request.Send()

Copy

DELETE /{databaseId}/items/properties/{propertyName}

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

propertyName

string

Located in: path

Required: Yes

Name of the property to be deleted.

Responses

200

Successful operation.

400

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

404

Property of the given name is not present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been deleted from the database since the item property was already not present. If there is no additional info in the JSON response, you probably have an error in your URL.

get

Get Item Property Info

Gets information about specified item property.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.GetItemPropertyInfo(propertyName))
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(GetItemPropertyInfo(property_name))

Copy

Initialization

result = client.send(GetItemPropertyInfo.new(propertyName))

Copy

Initialization

PropertyInfo result = client.send(new GetItemPropertyInfo(String propertyName));

Copy

Initialization

<?php
$result = $client->send(new GetItemPropertyInfo($property_name));
?>

Copy

Initialization

PropertyInfo result = client.Send(GetItemPropertyInfo(string propertyName));

Copy

Initialization

request := client.NewGetItemPropertyInfo(propertyName string)

result, err := request.Send() // result is of the type bindings.PropertyInfo

Copy

GET /{databaseId}/items/properties/{propertyName}

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

propertyName

string

Located in: path

Required: Yes

Name of the property about which the information is to be retrieved.

Responses

200

Successful operation.

{
  "name": "num-processors",
  "type": "int"
}

400

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

404

Property of the given name is not present in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

get

List Item Properties

Gets the list of all the item properties in your database.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ListItemProperties())
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(ListItemProperties())

Copy

Initialization

result = client.send(ListItemProperties.new())

Copy

Initialization

PropertyInfo[] result = client.send(new ListItemProperties());

Copy

Initialization

<?php
$result = $client->send(new ListItemProperties());
?>

Copy

Initialization

IEnumerable<PropertyInfo> result = client.Send(ListItemProperties());

Copy

Initialization

request := client.NewListItemProperties()

result, err := request.Send() // result is of the type []bindings.PropertyInfo

Copy

GET /{databaseId}/items/properties/list/

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

Responses

200

Successful operation.

[
  {
    "name": "tags",
    "type": "set"
  },
  {
    "name": "release-date",
    "type": "timestamp"
  },
  {
    "name": "description",
    "type": "string"
  }
]

404

Invalid URL.

Values of item properties

The following methods allow assigning property values to items in the catalog. Set values are examined by content-based algorithms and used for recommendations, especially in the case of cold-start items that have no interactions yet. Properties are also used in ReQL for filtering and boosting according to your business rules.

post

Set Item Values

Sets/updates (some) property values of the given item. The properties (columns) must be previously created by Add item property.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.SetItemValues(itemId, values, {
  // optional parameters:
  'cascadeCreate': <boolean>
}));

Copy

Initialization

client.send(SetItemValues(item_id, values,
    # optional parameters:
    cascade_create=<boolean>
  )
)

Copy

Initialization

client.send(SetItemValues.new(itemId, values, {
    # optional parameters:
    :cascade_create => <boolean>
  })
)

Copy

Initialization

client.send(new SetItemValues(String itemId, Map<String, Object> values)
  .setCascadeCreate(boolean cascadeCreate)
);

Copy

Initialization

<?php
$client->send(new SetItemValues($item_id, $values, [
    // optional parameters:
    'cascadeCreate' => <boolean>
  ])
);
?>

Copy

Initialization

client.Send(SetItemValues(string itemId, Dictionary<string, object> values,
    // optional parameters:
    cascadeCreate: <bool>
  )
);

Copy

Initialization

request := client.NewSetItemValues(itemId string, values map[string]interface{})    
    // optional parameters:
    .SetCascadeCreate(cascadeCreate bool)


_, err := request.Send()

Copy

POST /{databaseId}/items/{itemId}

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

itemId

string

Located in: path

Required: Yes

ID of the item which will be modified.

object

Located in: body

Required: Yes

The values for the individual properties.

Example of the body:

  {
    "product_description": "4K TV with 3D feature",
    "categories":   ["Electronics", "Televisions"],
    "price_usd": 342,
    "in_stock_from": "2016-11-16T08:00Z",
    "image": "http://myexamplesite.com/products/4ktelevision3d/image.jpg",
    "other_images": ["http://myexamplesite.com/products/4ktelevision3d/image2.jpg",
                     "http://myexamplesite.com/products/4ktelevision3d/image3.jpg"]
  }

Set item values can also cascade create the item if it's not already present in the database.

For this functionality:

When using the client libraries: Set the optional cascadeCreate parameter to true, just like when creating an interaction.
When using directly REST API: Set special "property" !cascadeCreate.

Example:
```
  {
    "product_description": "4K TV with 3D feature",
    "!cascadeCreate": true
  }
```
Note the exclamation mark (!) at the beginning of the parameter's name to distinguish it from item property names.

Responses

200

Successful operation.

400

Property name does not match ''^[a-zA-Z0-9_-:]+$'', value does not match the property type.

404

Property of the given name is not present in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

get

Get Item Values

Gets all the current property values of the given item.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.GetItemValues(itemId))
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(GetItemValues(item_id))

Copy

Initialization

result = client.send(GetItemValues.new(itemId))

Copy

Initialization

Map<String, Object> result = client.send(new GetItemValues(String itemId));

Copy

Initialization

<?php
$result = $client->send(new GetItemValues($item_id));
?>

Copy

Initialization

StringBinding result = client.Send(GetItemValues(string itemId));

Copy

Initialization

request := client.NewGetItemValues(itemId string)

result, err := request.Send() // result is of the type map[string]interface{}

Copy

GET /{databaseId}/items/{itemId}

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

itemId

string

Located in: path

Required: Yes

ID of the item whose properties are to be obtained.

Responses

200

Successful operation.

{
  "release-date": null,
  "tags": [
    "electronics",
    "laptops"
  ],
  "num-processors": 12,
  "description": "Very powerful laptop",
  "weight": 1.6
}

400

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

404

Item of the given itemId is not present in the catalog. If there is no additional info in the JSON response, you probably have an error in your URL.

post

Update More Items

Updates (some) property values of all the items that pass the filter.

Example: Setting all the items that are older than a week as unavailable

  {
    "filter": "'releaseDate' < now() - 7*24*3600",
    "changes": {"available": false}
  }

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.UpdateMoreItems(filter, changes))
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(UpdateMoreItems(filter, changes))

Copy

Initialization

result = client.send(UpdateMoreItems.new(filter, changes))

Copy

Initialization

UpdateMoreItemsResponse result = client.send(new UpdateMoreItems(String filter, Map<String, Object> changes));

Copy

Initialization

<?php
$result = $client->send(new UpdateMoreItems($filter, $changes));
?>

Copy

Initialization

UpdateMoreItemsResponse result = client.Send(UpdateMoreItems(string filter, Dictionary<string, object> changes));

Copy

Initialization

request := client.NewUpdateMoreItems(filter string, changes map[string]interface{})

result, err := request.Send() // result is of the type bindings.UpdateMoreItemsResponse

Copy

POST /{databaseId}/more-items/
Body (application/json):
{
  "filter" => <string>,
  "changes" => <Object>
}

Since version

3.3.0

Parameters

databaseId

string

Located in: path

Required: Yes

Since version: 3.3.0

ID of your database.

filter

string

Located in: body

Required: Yes

Since version: 3.3.0

A ReQL expression, which returns true for the items that shall be updated.

changes

object

Located in: body

Required: Yes

Since version: 3.3.0

A dictionary where the keys are properties that shall be updated.

Responses

200

Successful operation. Returns IDs of updated items and their count.

{
  "itemIds": [
    "item-42",
    "item-125",
    "item-11"
  ],
  "count": 3
}

400

Invalid filter, property name does not match ''^[a-zA-Z0-9_-:]+$'', value does not match the property type.

404

Property of the given name is not present in the database.

Users

The following methods allow you to manage users in your database.

put

Add User

Adds a new user to the database.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.AddUser(userId));

Copy

Initialization

client.send(AddUser(user_id))

Copy

Initialization

client.send(AddUser.new(userId))

Copy

Initialization

client.send(new AddUser(String userId));

Copy

Initialization

<?php
$client->send(new AddUser($user_id));
?>

Copy

Initialization

client.Send(AddUser(string userId));

Copy

Initialization

request := client.NewAddUser(userId string)

_, err := request.Send()

Copy

PUT /{databaseId}/users/{userId}

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

userId

string

Located in: path

Required: Yes

ID of the user to be added.

Responses

201

Successful operation.

400

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

409

User of the given userId is already present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.

delete

Delete User

Deletes a user of the given userId from the database.

If there are any purchases, ratings, bookmarks, cart additions or detail views made by the user present in the database, they will be deleted in cascade as well.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.DeleteUser(userId));

Copy

Initialization

client.send(DeleteUser(user_id))

Copy

Initialization

client.send(DeleteUser.new(userId))

Copy

Initialization

client.send(new DeleteUser(String userId));

Copy

Initialization

<?php
$client->send(new DeleteUser($user_id));
?>

Copy

Initialization

client.Send(DeleteUser(string userId));

Copy

Initialization

request := client.NewDeleteUser(userId string)

_, err := request.Send()

Copy

DELETE /{databaseId}/users/{userId}

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

userId

string

Located in: path

Required: Yes

ID of the user to be deleted.

Responses

200

Successful operation.

400

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

404

User of the given userId is not present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been deleted from the database since the user was already not present. If there is no additional info in the JSON response, you probably have an error in your URL.

put

Merge Users

Allowed on Client-Side

Merges interactions (purchases, ratings, bookmarks, detail views ...) of two different users under a single user ID. This is especially useful for online e-commerce applications working with anonymous users identified by unique tokens such as the session ID. In such applications, it may often happen that a user owns a persistent account, yet accesses the system anonymously while, e.g., putting items into a shopping cart. At some point in time, such as when the user wishes to confirm the purchase, (s)he logs into the system using his/her username and password. The interactions made under anonymous session ID then become connected with the persistent account, and merging these two becomes desirable.

Merging happens between two users referred to as the target and the source. After the merge, all the interactions of the source user are attributed to the target user, and the source user is deleted.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.MergeUsers(targetUserId, sourceUserId, {
  // optional parameters:
  'cascadeCreate': <boolean>
}));

Copy

Initialization

client.send(MergeUsers(target_user_id, source_user_id,
    # optional parameters:
    cascade_create=<boolean>
  )
)

Copy

Initialization

client.send(MergeUsers.new(targetUserId, sourceUserId, {
    # optional parameters:
    :cascade_create => <boolean>
  })
)

Copy

Initialization

client.send(new MergeUsers(String targetUserId, String sourceUserId)
  .setCascadeCreate(boolean cascadeCreate)
);

Copy

Initialization

<?php
$client->send(new MergeUsers($target_user_id, $source_user_id, [
    // optional parameters:
    'cascadeCreate' => <boolean>
  ])
);
?>

Copy

Initialization

client.Send(MergeUsers(string targetUserId, string sourceUserId,
    // optional parameters:
    cascadeCreate: <bool>
  )
);

Copy

Initialization

request := client.NewMergeUsers(targetUserId string, sourceUserId string)    
    // optional parameters:
    .SetCascadeCreate(cascadeCreate bool)


_, err := request.Send()

Copy

PUT /{databaseId}/users/{targetUserId}/merge/{sourceUserId}?cascadeCreate=<boolean>

Calls Limit Per Minute

100

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

targetUserId

string

Located in: path

Required: Yes

ID of the target user.

sourceUserId

string

Located in: path

Required: Yes

ID of the source user.

cascadeCreate

boolean

Located in: query

Required: No

Sets whether the user targetUserId should be created if not present in the database.

Responses

201

Successful operation.

400

The sourceUserId or targetUserId does not match ^[a-zA-Z0-9_-:@.]+$

404

The sourceUserId or targetUserId does not exist in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

get

List Users

Gets a list of IDs of users currently present in the catalog.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ListUsers({
  // optional parameters:
  'filter': <string>,
  'count': <integer>,
  'offset': <integer>,
  'returnProperties': <boolean>,
  'includedProperties': <array>
}))
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(ListUsers(
    # optional parameters:
    filter=<string>,
    count=<integer>,
    offset=<integer>,
    return_properties=<boolean>,
    included_properties=<array>
  )
)

Copy

Initialization

result = client.send(ListUsers.new({
    # optional parameters:
    :filter => <string>,
    :count => <integer>,
    :offset => <integer>,
    :return_properties => <boolean>,
    :included_properties => <array>
  })
)

Copy

Initialization

User[] result = client.send(new ListUsers()
  .setFilter(String filter)
  .setCount(long count)
  .setOffset(long offset)
  .setReturnProperties(boolean returnProperties)
  .setIncludedProperties(String[] includedProperties)
);

Copy

Initialization

<?php
$result = $client->send(new ListUsers([
    // optional parameters:
    'filter' => <string>,
    'count' => <integer>,
    'offset' => <integer>,
    'returnProperties' => <boolean>,
    'includedProperties' => <array>
  ])
);
?>

Copy

Initialization

IEnumerable<User> result = client.Send(ListUsers(
    // optional parameters:
    filter: <string>,
    count: <long>,
    offset: <long>,
    returnProperties: <bool>,
    includedProperties: <string[]>
  )
);

Copy

Initialization

request := client.NewListUsers()    
    // optional parameters:
    .SetFilter(filter string)
    .SetCount(count int)
    .SetOffset(offset int)
    .SetReturnProperties(returnProperties bool)
    .SetIncludedProperties(includedProperties []string)


result, err := request.Send() // result is of the type []bindings.User

Copy

GET /{databaseId}/users/list/?filter=<string>
&count=<integer>
&offset=<integer>
&returnProperties=<boolean>
&includedProperties=<array>

Calls Limit Per Minute

100

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

filter

string

Located in: query

Required: No

Boolean-returning ReQL expression, which allows you to filter users to be listed. Only the users for which the expression is true will be returned.

count

integer

Located in: query

Required: No

The number of users to be listed.

offset

integer

Located in: query

Required: No

Specifies the number of users to skip (ordered by userId).

returnProperties

boolean

Located in: query

Required: No

Since version: 1.4.0

With returnProperties=true, property values of the listed users are returned along with their IDs in a JSON dictionary.

Example response:

  [
    {
      "userId": "user-81",
      "country": "US",
      "sex": "M"
    },
    {
      "userId": "user-314",
      "country": "CAN",
      "sex": "F"
    }
  ]

includedProperties

array

Located in: query

Required: No

Since version: 1.4.0

Allows specifying which properties should be returned when returnProperties=true is set. The properties are given as a comma-separated list.

Example response for includedProperties=country:

  [
    {
      "userId": "user-81",
      "country": "US"
    },
    {
      "userId": "user-314",
      "country": "CAN"
    }
  ]

Responses

200

Successful operation.

[
  "user-1",
  "user-2",
  "user-3"
]

404

Invalid URL.

User Properties

User properties definition

User properties are used for modeling users. The following methods allow the definition of user properties. The properties may be thought of as columns in a relational database table.

put

Add User Property

Adding a user property is somewhat equivalent to adding a column to the table of users. The users may be characterized by various properties of different types.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.AddUserProperty(propertyName, type));

Copy

Initialization

client.send(AddUserProperty(property_name, type))

Copy

Initialization

client.send(AddUserProperty.new(propertyName, type))

Copy

Initialization

client.send(new AddUserProperty(String propertyName, String type));

Copy

Initialization

<?php
$client->send(new AddUserProperty($property_name, $type));
?>

Copy

Initialization

client.Send(AddUserProperty(string propertyName, string type));

Copy

Initialization

request := client.NewAddUserProperty(propertyName string, type string)

_, err := request.Send()

Copy

PUT /{databaseId}/users/properties/{propertyName}?type=<string>

Since version

1.3.0

Parameters

databaseId

string

Located in: path

Required: Yes

Since version: 1.3.0

ID of your database.

propertyName

string

Located in: path

Required: Yes

Since version: 1.3.0

Name of the user property to be created. Currently, the following names are reserved: id, userid, case-insensitively. Also, the length of the property name must not exceed 63 characters.

type

string

Located in: query

Required: Yes

Since version: 1.3.0

Value type of the user property to be created. One of: int, double, string, boolean, timestamp, set.

int - Signed integer number.
double - Floating point number. It uses 64-bit base-2 format (IEEE 754 standard).
string - UTF-8 string.
boolean - true / false
timestamp - Value representing date and time.
set - Set of strings.

Responses

201

Successful operation.

400

Property name does not match ^[a-zA-Z0-9_-:]+$, or it is a reserved keyword (''id'', ''userid''), or its length exceeds 63 characters. Type information is missing, or the given type is invalid.

409

Property of the given name is already present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.

delete

Delete User Property

Deleting a user property is roughly equivalent to removing a column from the table of users.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.DeleteUserProperty(propertyName));

Copy

Initialization

client.send(DeleteUserProperty(property_name))

Copy

Initialization

client.send(DeleteUserProperty.new(propertyName))

Copy

Initialization

client.send(new DeleteUserProperty(String propertyName));

Copy

Initialization

<?php
$client->send(new DeleteUserProperty($property_name));
?>

Copy

Initialization

client.Send(DeleteUserProperty(string propertyName));

Copy

Initialization

request := client.NewDeleteUserProperty(propertyName string)

_, err := request.Send()

Copy

DELETE /{databaseId}/users/properties/{propertyName}

Since version

1.3.0

Parameters

databaseId

string

Located in: path

Required: Yes

Since version: 1.3.0

ID of your database.

propertyName

string

Located in: path

Required: Yes

Since version: 1.3.0

Name of the property to be deleted.

Responses

200

Successful operation.

400

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

404

Property of the given name is not present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been deleted from the database since the user property was already not present. If there is no additional info in the JSON response, you probably have an error in your URL.

get

Get User Property Info

Gets information about specified user property.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.GetUserPropertyInfo(propertyName))
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(GetUserPropertyInfo(property_name))

Copy

Initialization

result = client.send(GetUserPropertyInfo.new(propertyName))

Copy

Initialization

PropertyInfo result = client.send(new GetUserPropertyInfo(String propertyName));

Copy

Initialization

<?php
$result = $client->send(new GetUserPropertyInfo($property_name));
?>

Copy

Initialization

PropertyInfo result = client.Send(GetUserPropertyInfo(string propertyName));

Copy

Initialization

request := client.NewGetUserPropertyInfo(propertyName string)

result, err := request.Send() // result is of the type bindings.PropertyInfo

Copy

GET /{databaseId}/users/properties/{propertyName}

Since version

1.3.0

Parameters

databaseId

string

Located in: path

Required: Yes

Since version: 1.3.0

ID of your database.

propertyName

string

Located in: path

Required: Yes

Since version: 1.3.0

Name of the property about which the information is to be retrieved.

Responses

200

Successful operation.

{
  "name": "country",
  "type": "string"
}

400

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

404

Property of the given name is not present in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

get

List User Properties

Gets the list of all the user properties in your database.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ListUserProperties())
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(ListUserProperties())

Copy

Initialization

result = client.send(ListUserProperties.new())

Copy

Initialization

PropertyInfo[] result = client.send(new ListUserProperties());

Copy

Initialization

<?php
$result = $client->send(new ListUserProperties());
?>

Copy

Initialization

IEnumerable<PropertyInfo> result = client.Send(ListUserProperties());

Copy

Initialization

request := client.NewListUserProperties()

result, err := request.Send() // result is of the type []bindings.PropertyInfo

Copy

GET /{databaseId}/users/properties/list/

Since version

1.3.0

Parameters

databaseId

string

Located in: path

Required: Yes

Since version: 1.3.0

ID of your database.

Responses

200

Successful operation.

[
  {
    "name": "country",
    "type": "string"
  },
  {
    "name": "sex",
    "type": "string"
  }
]

404

Invalid URL.

Values of user properties

The following methods allow assigning property values to the user. Set values are examined by content-based algorithms and used in building recommendations, especially for users that have only a few interactions (e.g., new users). Useful properties may be, for example, gender or region. The values can be used in filtering using the context_user ReQL function.

post

Set User Values

Sets/updates (some) property values of the given user. The properties (columns) must be previously created by Add user property.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.SetUserValues(userId, values, {
  // optional parameters:
  'cascadeCreate': <boolean>
}));

Copy

Initialization

client.send(SetUserValues(user_id, values,
    # optional parameters:
    cascade_create=<boolean>
  )
)

Copy

Initialization

client.send(SetUserValues.new(userId, values, {
    # optional parameters:
    :cascade_create => <boolean>
  })
)

Copy

Initialization

client.send(new SetUserValues(String userId, Map<String, Object> values)
  .setCascadeCreate(boolean cascadeCreate)
);

Copy

Initialization

<?php
$client->send(new SetUserValues($user_id, $values, [
    // optional parameters:
    'cascadeCreate' => <boolean>
  ])
);
?>

Copy

Initialization

client.Send(SetUserValues(string userId, Dictionary<string, object> values,
    // optional parameters:
    cascadeCreate: <bool>
  )
);

Copy

Initialization

request := client.NewSetUserValues(userId string, values map[string]interface{})    
    // optional parameters:
    .SetCascadeCreate(cascadeCreate bool)


_, err := request.Send()

Copy

POST /{databaseId}/users/{userId}

Since version

1.3.0

Parameters

databaseId

string

Located in: path

Required: Yes

Since version: 1.3.0

ID of your database.

userId

string

Located in: path

Required: Yes

Since version: 1.3.0

ID of the user which will be modified.

object

Located in: body

Required: Yes

Since version: 1.3.0

The values for the individual properties.

Example of the body:

  {
    "country": "US",
    "sex": "F"
  }

Set user values can also cascade create the user if it's not already present in the database.

For this functionality:

When using the client libraries: Set the optional cascadeCreate parameter to true, just like when creating an interaction.
When using directly REST API: Set special "property" !cascadeCreate.

Example:
```
  {
    "country": "US",
    "!cascadeCreate": true
  }
```
Note the exclamation mark (!) at the beginning of the parameter's name to distinguish it from item property names.

Responses

200

Successful operation.

400

Property name does not match ''^[a-zA-Z0-9_-:]+$'', value does not agree to property type.

404

Property of the given name is not present in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

get

Get User Values

Gets all the current property values of the given user.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.GetUserValues(userId))
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(GetUserValues(user_id))

Copy

Initialization

result = client.send(GetUserValues.new(userId))

Copy

Initialization

Map<String, Object> result = client.send(new GetUserValues(String userId));

Copy

Initialization

<?php
$result = $client->send(new GetUserValues($user_id));
?>

Copy

Initialization

StringBinding result = client.Send(GetUserValues(string userId));

Copy

Initialization

request := client.NewGetUserValues(userId string)

result, err := request.Send() // result is of the type map[string]interface{}

Copy

GET /{databaseId}/users/{userId}

Since version

1.3.0

Parameters

databaseId

string

Located in: path

Required: Yes

Since version: 1.3.0

ID of your database.

userId

string

Located in: path

Required: Yes

Since version: 1.3.0

ID of the user whose properties are to be obtained.

Responses

200

Successful operation.

{
  "country": "US",
  "sex": "F"
}

400

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

404

User of the given userId is not present in the catalog. If there is no additional info in the JSON response, you probably have an error in your URL.

User-Item Interactions

The following methods allow adding, deleting, and listing interactions between the users and the items.

Detail Views

post

Add Detail View

Allowed on Client-Side

Adds a detail view of the given item made by the given user.

Javascript Kotlin Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new recombee.AddDetailView(userId, itemId, {
  // optional parameters:
  'timestamp': <string / number>,
  'duration': <integer>,
  'cascadeCreate': <boolean>,
  'recommId': <string>
}));

Copy

Initialization

client.send(AddDetailView(userId: String, itemId: String,
    // optional parameters:
    timestamp: Instant,
    duration: Long,
    cascadeCreate: Boolean,
    recommId: String
  )
)

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.AddDetailView(userId, itemId, {
  // optional parameters:
  'timestamp': <string / number>,
  'duration': <integer>,
  'cascadeCreate': <boolean>,
  'recommId': <string>
}));

Copy

Initialization

client.send(AddDetailView(user_id, item_id,
    # optional parameters:
    timestamp=<string / number>,
    duration=<integer>,
    cascade_create=<boolean>,
    recomm_id=<string>
  )
)

Copy

Initialization

client.send(AddDetailView.new(userId, itemId, {
    # optional parameters:
    :timestamp => <string / number>,
    :duration => <integer>,
    :cascade_create => <boolean>,
    :recomm_id => <string>
  })
)

Copy

Initialization

client.send(new AddDetailView(String userId, String itemId)
  .setTimestamp(Date timestamp)
  .setDuration(long duration)
  .setCascadeCreate(boolean cascadeCreate)
  .setRecommId(String recommId)
);

Copy

Initialization

<?php
$client->send(new AddDetailView($user_id, $item_id, [
    // optional parameters:
    'timestamp' => <string / number>,
    'duration' => <integer>,
    'cascadeCreate' => <boolean>,
    'recommId' => <string>
  ])
);
?>

Copy

Initialization

client.Send(AddDetailView(string userId, string itemId,
    // optional parameters:
    timestamp: <DateTime>,
    duration: <long>,
    cascadeCreate: <bool>,
    recommId: <string>
  )
);

Copy

Initialization

request := client.NewAddDetailView(userId string, itemId string)    
    // optional parameters:
    .SetTimestamp(timestamp time.Time)
    .SetDuration(duration int)
    .SetCascadeCreate(cascadeCreate bool)
    .SetRecommId(recommId string)


_, err := request.Send()

Copy

POST /{databaseId}/detailviews/
Body (application/json):
{
  "userId" => <string>,
  "itemId" => <string>,
  "timestamp" => <string / number>,
  "duration" => <integer>,
  "cascadeCreate" => <boolean>,
  "recommId" => <string>
}

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

userId

string

Located in: body

Required: Yes

User who viewed the item

itemId

string

Located in: body

Required: Yes

Viewed item

timestamp

string

number

Located in: body

Required: No

UTC timestamp of the view as ISO8601-1 pattern or UTC epoch time. The default value is the current time.

duration

integer

Located in: body

Required: No

Duration of the view

cascadeCreate

boolean

Located in: body

Required: No

Sets whether the given user/item should be created if not present in the database.

recommId

string

Located in: body

Required: No

Since version: 2.2.0

If this detail view is based on a recommendation request, recommId is the id of the clicked recommendation.

Responses

200

Successful operation.

400

Given userId or itemId does not match ^[a-zA-Z0-9_-:@.]+$. timestamp or duration is not a real number ≥ 0.

404

The cascadeCreate is not set true and the userId or the itemId were found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

409

A detail view of the exact same userId, itemId, and timestamp is already present in the database. Note that a user may view an item's details multiple times, yet triplets (userId, itemId, timestamp) must be unique. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.

delete

Delete Detail View

Deletes an existing detail view uniquely specified by (userId, itemId, and timestamp) or all the detail views with the given userId and itemId if timestamp is omitted.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.DeleteDetailView(userId, itemId, {
  // optional parameters:
  'timestamp': <number>
}));

Copy

Initialization

client.send(DeleteDetailView(user_id, item_id,
    # optional parameters:
    timestamp=<number>
  )
)

Copy

Initialization

client.send(DeleteDetailView.new(userId, itemId, {
    # optional parameters:
    :timestamp => <number>
  })
)

Copy

Initialization

client.send(new DeleteDetailView(String userId, String itemId)
  .setTimestamp(Date timestamp)
);

Copy

Initialization

<?php
$client->send(new DeleteDetailView($user_id, $item_id, [
    // optional parameters:
    'timestamp' => <number>
  ])
);
?>

Copy

Initialization

client.Send(DeleteDetailView(string userId, string itemId,
    // optional parameters:
    timestamp: <DateTime>
  )
);

Copy

Initialization

request := client.NewDeleteDetailView(userId string, itemId string)    
    // optional parameters:
    .SetTimestamp(timestamp time.Time)


_, err := request.Send()

Copy

DELETE /{databaseId}/detailviews/?userId=<string>
&itemId=<string>
&timestamp=<number>

Calls Limit Per Minute

1000

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

userId

string

Located in: query

Required: Yes

ID of the user who made the detail view.

itemId

string

Located in: query

Required: Yes

ID of the item whose details were viewed.

timestamp

number

Located in: query

Required: No

Unix timestamp of the detail view. If the timestamp is omitted, then all the detail views with the given userId and itemId are deleted.

Responses

200

Successful operation.

400

Given userId or itemId does not match ^[a-zA-Z0-9_-:@.]+$, or timestamp is not a real number ≥ 0.

404

The userId, itemId, or detail view with the given (userId, itemId, timestamp) not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

get

List Item Detail Views

Lists all the detail views of the given item ever made by different users.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ListItemDetailViews(itemId))
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(ListItemDetailViews(item_id))

Copy

Initialization

result = client.send(ListItemDetailViews.new(itemId))

Copy

Initialization

DetailView[] result = client.send(new ListItemDetailViews(String itemId));

Copy

Initialization

<?php
$result = $client->send(new ListItemDetailViews($item_id));
?>

Copy

Initialization

IEnumerable<DetailView> result = client.Send(ListItemDetailViews(string itemId));

Copy

Initialization

request := client.NewListItemDetailViews(itemId string)

result, err := request.Send() // result is of the type []bindings.DetailView

Copy

GET /{databaseId}/items/{itemId}/detailviews/

Calls Limit Per Minute

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

itemId

string

Located in: path

Required: Yes

ID of the item whose detail views are to be listed.

Responses

200

Successful operation.

[
  {
    "itemId": "item-x",
    "userId": "user-a",
    "duration": 14.23,
    "timestamp": 1348151906.0
  },
  {
    "itemId": "item-x",
    "userId": "user-b",
    "duration": null,
    "timestamp": 1348239363.0
  }
]

400

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

404

Given itemId not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

get

List User Detail Views

Lists all the detail views of different items ever made by the given user.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ListUserDetailViews(userId))
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(ListUserDetailViews(user_id))

Copy

Initialization

result = client.send(ListUserDetailViews.new(userId))

Copy

Initialization

DetailView[] result = client.send(new ListUserDetailViews(String userId));

Copy

Initialization

<?php
$result = $client->send(new ListUserDetailViews($user_id));
?>

Copy

Initialization

IEnumerable<DetailView> result = client.Send(ListUserDetailViews(string userId));

Copy

Initialization

request := client.NewListUserDetailViews(userId string)

result, err := request.Send() // result is of the type []bindings.DetailView

Copy

GET /{databaseId}/users/{userId}/detailviews/

Calls Limit Per Minute

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

userId

string

Located in: path

Required: Yes

ID of the user whose detail views are to be listed.

Responses

200

Successful operation.

[
  {
    "itemId": "item-y",
    "userId": "user-a",
    "duration": 134.03,
    "timestamp": 1348139180.0
  },
  {
    "itemId": "item-x",
    "userId": "user-a",
    "duration": 14.23,
    "timestamp": 1348151906.0
  }
]

400

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

404

Given userId not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

Purchases

post

Add Purchase

Allowed on Client-Side

Adds a purchase of the given item made by the given user.

Javascript Kotlin Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new recombee.AddPurchase(userId, itemId, {
  // optional parameters:
  'timestamp': <string / number>,
  'cascadeCreate': <boolean>,
  'amount': <number>,
  'price': <number>,
  'profit': <number>,
  'recommId': <string>
}));

Copy

Initialization

client.send(AddPurchase(userId: String, itemId: String,
    // optional parameters:
    timestamp: Instant,
    cascadeCreate: Boolean,
    amount: Double,
    price: Double,
    profit: Double,
    recommId: String
  )
)

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.AddPurchase(userId, itemId, {
  // optional parameters:
  'timestamp': <string / number>,
  'cascadeCreate': <boolean>,
  'amount': <number>,
  'price': <number>,
  'profit': <number>,
  'recommId': <string>
}));

Copy

Initialization

client.send(AddPurchase(user_id, item_id,
    # optional parameters:
    timestamp=<string / number>,
    cascade_create=<boolean>,
    amount=<number>,
    price=<number>,
    profit=<number>,
    recomm_id=<string>
  )
)

Copy

Initialization

client.send(AddPurchase.new(userId, itemId, {
    # optional parameters:
    :timestamp => <string / number>,
    :cascade_create => <boolean>,
    :amount => <number>,
    :price => <number>,
    :profit => <number>,
    :recomm_id => <string>
  })
)

Copy

Initialization

client.send(new AddPurchase(String userId, String itemId)
  .setTimestamp(Date timestamp)
  .setCascadeCreate(boolean cascadeCreate)
  .setAmount(double amount)
  .setPrice(double price)
  .setProfit(double profit)
  .setRecommId(String recommId)
);

Copy

Initialization

<?php
$client->send(new AddPurchase($user_id, $item_id, [
    // optional parameters:
    'timestamp' => <string / number>,
    'cascadeCreate' => <boolean>,
    'amount' => <number>,
    'price' => <number>,
    'profit' => <number>,
    'recommId' => <string>
  ])
);
?>

Copy

Initialization

client.Send(AddPurchase(string userId, string itemId,
    // optional parameters:
    timestamp: <DateTime>,
    cascadeCreate: <bool>,
    amount: <double>,
    price: <double>,
    profit: <double>,
    recommId: <string>
  )
);

Copy

Initialization

request := client.NewAddPurchase(userId string, itemId string)    
    // optional parameters:
    .SetTimestamp(timestamp time.Time)
    .SetCascadeCreate(cascadeCreate bool)
    .SetAmount(amount float64)
    .SetPrice(price float64)
    .SetProfit(profit float64)
    .SetRecommId(recommId string)


_, err := request.Send()

Copy

POST /{databaseId}/purchases/
Body (application/json):
{
  "userId" => <string>,
  "itemId" => <string>,
  "timestamp" => <string / number>,
  "cascadeCreate" => <boolean>,
  "amount" => <number>,
  "price" => <number>,
  "profit" => <number>,
  "recommId" => <string>
}

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

userId

string

Located in: body

Required: Yes

User who purchased the item

itemId

string

Located in: body

Required: Yes

Purchased item

timestamp

string

number

Located in: body

Required: No

UTC timestamp of the purchase as ISO8601-1 pattern or UTC epoch time. The default value is the current time.

cascadeCreate

boolean

Located in: body

Required: No

Sets whether the given user/item should be created if not present in the database.

amount

number

Located in: body

Required: No

Since version: 1.6.0

Amount (number) of purchased items. The default is 1. For example, if user-x purchases two item-y during a single order (session...), the amount should equal 2.

price

number

Located in: body

Required: No

Since version: 1.6.0

Price paid by the user for the item. If amount is greater than 1, the sum of prices of all the items should be given.

profit

number

Located in: body

Required: No

Since version: 1.6.0

Your profit from the purchased item. The profit is natural in the e-commerce domain (for example, if user-x purchases item-y for $100 and the gross margin is 30 %, then the profit is $30) but is also applicable in other domains (for example, at a news company it may be income from a displayed advertisement on article page). If amount is greater than 1, the sum of profit of all the items should be given.

recommId

string

Located in: body

Required: No

Since version: 2.2.0

If this purchase is based on a recommendation request, recommId is the id of the clicked recommendation.

Responses

200

Successful operation.

400

The userId or itemId does not match ^[a-zA-Z0-9_-:@.]+$. timestamp is not a real number ≥ 0.

404

The cascadeCreate is not set true and the userId or the itemId were found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

409

A purchase of the exact same userId, itemId, and timestamp is already present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.

delete

Delete Purchase

Deletes an existing purchase uniquely specified by userId, itemId, and timestamp or all the purchases with the given userId and itemId if timestamp is omitted.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.DeletePurchase(userId, itemId, {
  // optional parameters:
  'timestamp': <number>
}));

Copy

Initialization

client.send(DeletePurchase(user_id, item_id,
    # optional parameters:
    timestamp=<number>
  )
)

Copy

Initialization

client.send(DeletePurchase.new(userId, itemId, {
    # optional parameters:
    :timestamp => <number>
  })
)

Copy

Initialization

client.send(new DeletePurchase(String userId, String itemId)
  .setTimestamp(Date timestamp)
);

Copy

Initialization

<?php
$client->send(new DeletePurchase($user_id, $item_id, [
    // optional parameters:
    'timestamp' => <number>
  ])
);
?>

Copy

Initialization

client.Send(DeletePurchase(string userId, string itemId,
    // optional parameters:
    timestamp: <DateTime>
  )
);

Copy

Initialization

request := client.NewDeletePurchase(userId string, itemId string)    
    // optional parameters:
    .SetTimestamp(timestamp time.Time)


_, err := request.Send()

Copy

DELETE /{databaseId}/purchases/?userId=<string>
&itemId=<string>
&timestamp=<number>

Calls Limit Per Minute

1000

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

userId

string

Located in: query

Required: Yes

ID of the user who made the purchase.

itemId

string

Located in: query

Required: Yes

ID of the item which was purchased.

timestamp

number

Located in: query

Required: No

Unix timestamp of the purchase. If the timestamp is omitted, then all the purchases with the given userId and itemId are deleted.

Responses

200

Successful operation.

400

Given userId or itemId does not match ^[a-zA-Z0-9_-:@.]+$, or timestamp is not a real number ≥ 0.

404

The userId, itemId, or purchase with the given (userId, itemId, timestamp) not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

get

List Item Purchases

Lists all the ever-made purchases of the given item.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ListItemPurchases(itemId))
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(ListItemPurchases(item_id))

Copy

Initialization

result = client.send(ListItemPurchases.new(itemId))

Copy

Initialization

Purchase[] result = client.send(new ListItemPurchases(String itemId));

Copy

Initialization

<?php
$result = $client->send(new ListItemPurchases($item_id));
?>

Copy

Initialization

IEnumerable<Purchase> result = client.Send(ListItemPurchases(string itemId));

Copy

Initialization

request := client.NewListItemPurchases(itemId string)

result, err := request.Send() // result is of the type []bindings.Purchase

Copy

GET /{databaseId}/items/{itemId}/purchases/

Calls Limit Per Minute

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

itemId

string

Located in: path

Required: Yes

ID of the item whose purchases are to be listed.

Responses

200

Successful operation.

[
  {
    "itemId": "item-x",
    "userId": "user-a",
    "timestamp": 1348151906.0
  },
  {
    "itemId": "item-x",
    "userId": "user-b",
    "timestamp": 1348327154.0
  }
]

400

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

404

Given itemId not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

get

List User Purchases

Lists all the purchases ever made by the given user.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ListUserPurchases(userId))
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(ListUserPurchases(user_id))

Copy

Initialization

result = client.send(ListUserPurchases.new(userId))

Copy

Initialization

Purchase[] result = client.send(new ListUserPurchases(String userId));

Copy

Initialization

<?php
$result = $client->send(new ListUserPurchases($user_id));
?>

Copy

Initialization

IEnumerable<Purchase> result = client.Send(ListUserPurchases(string userId));

Copy

Initialization

request := client.NewListUserPurchases(userId string)

result, err := request.Send() // result is of the type []bindings.Purchase

Copy

GET /{databaseId}/users/{userId}/purchases/

Calls Limit Per Minute

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

userId

string

Located in: path

Required: Yes

ID of the user whose purchases are to be listed.

Responses

200

Successful operation.

[
  {
    "itemId": "item-x",
    "timestamp": 1348151906.0,
    "userId": "user-a"
  },
  {
    "itemId": "item-z",
    "timestamp": 1348239363.0,
    "userId": "user-a"
  }
]

400

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

404

Given userId not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

Ratings

post

Add Rating

Allowed on Client-Side

Adds a rating of the given item made by the given user.

Javascript Kotlin Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new recombee.AddRating(userId, itemId, rating, {
  // optional parameters:
  'timestamp': <string / number>,
  'cascadeCreate': <boolean>,
  'recommId': <string>
}));

Copy

Initialization

client.send(AddRating(userId: String, itemId: String, rating: Double,
    // optional parameters:
    timestamp: Instant,
    cascadeCreate: Boolean,
    recommId: String
  )
)

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.AddRating(userId, itemId, rating, {
  // optional parameters:
  'timestamp': <string / number>,
  'cascadeCreate': <boolean>,
  'recommId': <string>
}));

Copy

Initialization

client.send(AddRating(user_id, item_id, rating,
    # optional parameters:
    timestamp=<string / number>,
    cascade_create=<boolean>,
    recomm_id=<string>
  )
)

Copy

Initialization

client.send(AddRating.new(userId, itemId, rating, {
    # optional parameters:
    :timestamp => <string / number>,
    :cascade_create => <boolean>,
    :recomm_id => <string>
  })
)

Copy

Initialization

client.send(new AddRating(String userId, String itemId, double rating)
  .setTimestamp(Date timestamp)
  .setCascadeCreate(boolean cascadeCreate)
  .setRecommId(String recommId)
);

Copy

Initialization

<?php
$client->send(new AddRating($user_id, $item_id, $rating, [
    // optional parameters:
    'timestamp' => <string / number>,
    'cascadeCreate' => <boolean>,
    'recommId' => <string>
  ])
);
?>

Copy

Initialization

client.Send(AddRating(string userId, string itemId, double rating,
    // optional parameters:
    timestamp: <DateTime>,
    cascadeCreate: <bool>,
    recommId: <string>
  )
);

Copy

Initialization

request := client.NewAddRating(userId string, itemId string, rating float64)    
    // optional parameters:
    .SetTimestamp(timestamp time.Time)
    .SetCascadeCreate(cascadeCreate bool)
    .SetRecommId(recommId string)


_, err := request.Send()

Copy

POST /{databaseId}/ratings/
Body (application/json):
{
  "userId" => <string>,
  "itemId" => <string>,
  "timestamp" => <string / number>,
  "rating" => <number>,
  "cascadeCreate" => <boolean>,
  "recommId" => <string>
}

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

userId

string

Located in: body

Required: Yes

User who submitted the rating

itemId

string

Located in: body

Required: Yes

Rated item

timestamp

string

number

Located in: body

Required: No

UTC timestamp of the rating as ISO8601-1 pattern or UTC epoch time. The default value is the current time.

rating

number

Located in: body

Required: Yes

Rating rescaled to interval [-1.0,1.0], where -1.0 means the worst rating possible, 0.0 means neutral, and 1.0 means absolutely positive rating. For example, in the case of 5-star evaluations, rating = (numStars-3)/2 formula may be used for the conversion.

cascadeCreate

boolean

Located in: body

Required: No

Sets whether the given user/item should be created if not present in the database.

recommId

string

Located in: body

Required: No

Since version: 2.2.0

If this rating is based on a recommendation request, recommId is the id of the clicked recommendation.

Responses

200

Successful operation.

400

The userId or itemId does not match ^[a-zA-Z0-9_-:@.]+$, or rating is not a real number from [-1.0,1.0], or timestamp is not a real number ≥ 0.

404

The cascadeCreate is not set true and the userId or the itemId were found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

409

A rating of the exact same userId, itemId, and timestamp is already present in the database. Note that a user may view an item's details multiple times, yet triplets (userId, itemId, timestamp) must be unique. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.

delete

Delete Rating

Deletes an existing rating specified by (userId, itemId, timestamp) from the database or all the ratings with the given userId and itemId if timestamp is omitted.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.DeleteRating(userId, itemId, {
  // optional parameters:
  'timestamp': <number>
}));

Copy

Initialization

client.send(DeleteRating(user_id, item_id,
    # optional parameters:
    timestamp=<number>
  )
)

Copy

Initialization

client.send(DeleteRating.new(userId, itemId, {
    # optional parameters:
    :timestamp => <number>
  })
)

Copy

Initialization

client.send(new DeleteRating(String userId, String itemId)
  .setTimestamp(Date timestamp)
);

Copy

Initialization

<?php
$client->send(new DeleteRating($user_id, $item_id, [
    // optional parameters:
    'timestamp' => <number>
  ])
);
?>

Copy

Initialization

client.Send(DeleteRating(string userId, string itemId,
    // optional parameters:
    timestamp: <DateTime>
  )
);

Copy

Initialization

request := client.NewDeleteRating(userId string, itemId string)    
    // optional parameters:
    .SetTimestamp(timestamp time.Time)


_, err := request.Send()

Copy

DELETE /{databaseId}/ratings/?userId=<string>
&itemId=<string>
&timestamp=<number>

Calls Limit Per Minute

1000

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

userId

string

Located in: query

Required: Yes

ID of the user who rated the item.

itemId

string

Located in: query

Required: Yes

ID of the item which was rated.

timestamp

number

Located in: query

Required: No

Unix timestamp of the rating. If the timestamp is omitted, then all the ratings with the given userId and itemId are deleted.

Responses

200

Successful operation.

400

Given userId or itemId does not match ^[a-zA-Z0-9_-:@.]+$, or timestamp is not a real number ≥ 0.

404

The userId, itemId or rating with the given (userId, itemId, timestamp) not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

get

List Item Ratings

Lists all the ratings of an item ever submitted by different users.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ListItemRatings(itemId))
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(ListItemRatings(item_id))

Copy

Initialization

result = client.send(ListItemRatings.new(itemId))

Copy

Initialization

Rating[] result = client.send(new ListItemRatings(String itemId));

Copy

Initialization

<?php
$result = $client->send(new ListItemRatings($item_id));
?>

Copy

Initialization

IEnumerable<Rating> result = client.Send(ListItemRatings(string itemId));

Copy

Initialization

request := client.NewListItemRatings(itemId string)

result, err := request.Send() // result is of the type []bindings.Rating

Copy

GET /{databaseId}/items/{itemId}/ratings/

Calls Limit Per Minute

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

itemId

string

Located in: path

Required: Yes

ID of the item whose ratings are to be listed.

Responses

200

Successful operation.

[
  {
    "itemId": "item-x",
    "userId": "user-a",
    "rating": -0.25,
    "timestamp": 1348151906.0
  },
  {
    "itemId": "item-x",
    "userId": "user-b",
    "rating": 0.0,
    "timestamp": 1348239363.0
  }
]

400

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

404

Given itemId not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

get

List User Ratings

Lists all the ratings ever submitted by the given user.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ListUserRatings(userId))
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(ListUserRatings(user_id))

Copy

Initialization

result = client.send(ListUserRatings.new(userId))

Copy

Initialization

Rating[] result = client.send(new ListUserRatings(String userId));

Copy

Initialization

<?php
$result = $client->send(new ListUserRatings($user_id));
?>

Copy

Initialization

IEnumerable<Rating> result = client.Send(ListUserRatings(string userId));

Copy

Initialization

request := client.NewListUserRatings(userId string)

result, err := request.Send() // result is of the type []bindings.Rating

Copy

GET /{databaseId}/users/{userId}/ratings/

Calls Limit Per Minute

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

userId

string

Located in: path

Required: Yes

ID of the user whose ratings are to be listed.

Responses

200

Successful operation.

[
  {
    "itemId": "item-y",
    "userId": "user-a",
    "rating": 0.5,
    "timestamp": 1348139180.0
  },
  {
    "itemId": "item-x",
    "userId": "user-a",
    "rating": -0.25,
    "timestamp": 1348151906.0
  }
]

400

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

404

Given userId not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

Cart Additions

post

Add Cart Addition

Allowed on Client-Side

Adds a cart addition of the given item made by the given user.

Javascript Kotlin Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new recombee.AddCartAddition(userId, itemId, {
  // optional parameters:
  'timestamp': <string / number>,
  'cascadeCreate': <boolean>,
  'amount': <number>,
  'price': <number>,
  'recommId': <string>
}));

Copy

Initialization

client.send(AddCartAddition(userId: String, itemId: String,
    // optional parameters:
    timestamp: Instant,
    cascadeCreate: Boolean,
    amount: Double,
    price: Double,
    recommId: String
  )
)

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.AddCartAddition(userId, itemId, {
  // optional parameters:
  'timestamp': <string / number>,
  'cascadeCreate': <boolean>,
  'amount': <number>,
  'price': <number>,
  'recommId': <string>
}));

Copy

Initialization

client.send(AddCartAddition(user_id, item_id,
    # optional parameters:
    timestamp=<string / number>,
    cascade_create=<boolean>,
    amount=<number>,
    price=<number>,
    recomm_id=<string>
  )
)

Copy

Initialization

client.send(AddCartAddition.new(userId, itemId, {
    # optional parameters:
    :timestamp => <string / number>,
    :cascade_create => <boolean>,
    :amount => <number>,
    :price => <number>,
    :recomm_id => <string>
  })
)

Copy

Initialization

client.send(new AddCartAddition(String userId, String itemId)
  .setTimestamp(Date timestamp)
  .setCascadeCreate(boolean cascadeCreate)
  .setAmount(double amount)
  .setPrice(double price)
  .setRecommId(String recommId)
);

Copy

Initialization

<?php
$client->send(new AddCartAddition($user_id, $item_id, [
    // optional parameters:
    'timestamp' => <string / number>,
    'cascadeCreate' => <boolean>,
    'amount' => <number>,
    'price' => <number>,
    'recommId' => <string>
  ])
);
?>

Copy

Initialization

client.Send(AddCartAddition(string userId, string itemId,
    // optional parameters:
    timestamp: <DateTime>,
    cascadeCreate: <bool>,
    amount: <double>,
    price: <double>,
    recommId: <string>
  )
);

Copy

Initialization

request := client.NewAddCartAddition(userId string, itemId string)    
    // optional parameters:
    .SetTimestamp(timestamp time.Time)
    .SetCascadeCreate(cascadeCreate bool)
    .SetAmount(amount float64)
    .SetPrice(price float64)
    .SetRecommId(recommId string)


_, err := request.Send()

Copy

POST /{databaseId}/cartadditions/
Body (application/json):
{
  "userId" => <string>,
  "itemId" => <string>,
  "timestamp" => <string / number>,
  "cascadeCreate" => <boolean>,
  "amount" => <number>,
  "price" => <number>,
  "recommId" => <string>
}

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

userId

string

Located in: body

Required: Yes

User who added the item to the cart

itemId

string

Located in: body

Required: Yes

Item added to the cart

timestamp

string

number

Located in: body

Required: No

UTC timestamp of the cart addition as ISO8601-1 pattern or UTC epoch time. The default value is the current time.

cascadeCreate

boolean

Located in: body

Required: No

Sets whether the given user/item should be created if not present in the database.

amount

number

Located in: body

Required: No

Since version: 1.6.0

Amount (number) added to cart. The default is 1. For example, if user-x adds two item-y during a single order (session...), the amount should equal 2.

price

number

Located in: body

Required: No

Since version: 1.6.0

Price of the added item. If amount is greater than 1, the sum of prices of all the items should be given.

recommId

string

Located in: body

Required: No

Since version: 2.2.0

If this cart addition is based on a recommendation request, recommId is the id of the clicked recommendation.

Responses

200

Successful operation.

400

The userId or itemId does not match ^[a-zA-Z0-9_-:@.]+$, timestamp is not a real number ≥ 0.

404

The cascadeCreate is not set true and the userId or the itemId were found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

409

A cart addition of the exact same userId, itemId, and timestamp is already present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.

delete

Delete Cart Addition

Deletes an existing cart addition uniquely specified by userId, itemId, and timestamp or all the cart additions with the given userId and itemId if timestamp is omitted.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.DeleteCartAddition(userId, itemId, {
  // optional parameters:
  'timestamp': <number>
}));

Copy

Initialization

client.send(DeleteCartAddition(user_id, item_id,
    # optional parameters:
    timestamp=<number>
  )
)

Copy

Initialization

client.send(DeleteCartAddition.new(userId, itemId, {
    # optional parameters:
    :timestamp => <number>
  })
)

Copy

Initialization

client.send(new DeleteCartAddition(String userId, String itemId)
  .setTimestamp(Date timestamp)
);

Copy

Initialization

<?php
$client->send(new DeleteCartAddition($user_id, $item_id, [
    // optional parameters:
    'timestamp' => <number>
  ])
);
?>

Copy

Initialization

client.Send(DeleteCartAddition(string userId, string itemId,
    // optional parameters:
    timestamp: <DateTime>
  )
);

Copy

Initialization

request := client.NewDeleteCartAddition(userId string, itemId string)    
    // optional parameters:
    .SetTimestamp(timestamp time.Time)


_, err := request.Send()

Copy

DELETE /{databaseId}/cartadditions/?userId=<string>
&itemId=<string>
&timestamp=<number>

Calls Limit Per Minute

1000

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

userId

string

Located in: query

Required: Yes

ID of the user who made the cart addition.

itemId

string

Located in: query

Required: Yes

ID of the item which was added to the cart.

timestamp

number

Located in: query

Required: No

Unix timestamp of the cart addition. If the timestamp is omitted, then all the cart additions with the given userId and itemId are deleted.

Responses

200

Successful operation.

400

Given userId or itemId does not match ^[a-zA-Z0-9_-:@.]+$, or timestamp is not a real number ≥ 0.

404

The userId, itemId, or cart addition with the given (userId, itemId, timestamp) not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

get

List Item Cart Additions

Lists all the ever-made cart additions of the given item.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ListItemCartAdditions(itemId))
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(ListItemCartAdditions(item_id))

Copy

Initialization

result = client.send(ListItemCartAdditions.new(itemId))

Copy

Initialization

CartAddition[] result = client.send(new ListItemCartAdditions(String itemId));

Copy

Initialization

<?php
$result = $client->send(new ListItemCartAdditions($item_id));
?>

Copy

Initialization

IEnumerable<CartAddition> result = client.Send(ListItemCartAdditions(string itemId));

Copy

Initialization

request := client.NewListItemCartAdditions(itemId string)

result, err := request.Send() // result is of the type []bindings.CartAddition

Copy

GET /{databaseId}/items/{itemId}/cartadditions/

Calls Limit Per Minute

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

itemId

string

Located in: path

Required: Yes

ID of the item whose cart additions are to be listed.

Responses

200

Successful operation.

[
  {
    "itemId": "item-x",
    "userId": "user-a",
    "timestamp": 1348151906.0
  },
  {
    "itemId": "item-x",
    "userId": "user-a",
    "timestamp": 1348327154.0
  }
]

400

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

404

Given itemId not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

get

List User Cart Additions

Lists all the cart additions ever made by the given user.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ListUserCartAdditions(userId))
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(ListUserCartAdditions(user_id))

Copy

Initialization

result = client.send(ListUserCartAdditions.new(userId))

Copy

Initialization

CartAddition[] result = client.send(new ListUserCartAdditions(String userId));

Copy

Initialization

<?php
$result = $client->send(new ListUserCartAdditions($user_id));
?>

Copy

Initialization

IEnumerable<CartAddition> result = client.Send(ListUserCartAdditions(string userId));

Copy

Initialization

request := client.NewListUserCartAdditions(userId string)

result, err := request.Send() // result is of the type []bindings.CartAddition

Copy

GET /{databaseId}/users/{userId}/cartadditions/

Calls Limit Per Minute

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

userId

string

Located in: path

Required: Yes

ID of the user whose cart additions are to be listed.

Responses

200

Successful operation.

[
  {
    "itemId": "item-x",
    "timestamp": 1348151906.0,
    "userId": "user-a"
  },
  {
    "itemId": "item-z",
    "timestamp": 1348239363.0,
    "userId": "user-a"
  }
]

400

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

404

Given userId not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

Bookmarks

post

Add Bookmark

Allowed on Client-Side

Adds a bookmark of the given item made by the given user.

Javascript Kotlin Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new recombee.AddBookmark(userId, itemId, {
  // optional parameters:
  'timestamp': <string / number>,
  'cascadeCreate': <boolean>,
  'recommId': <string>
}));

Copy

Initialization

client.send(AddBookmark(userId: String, itemId: String,
    // optional parameters:
    timestamp: Instant,
    cascadeCreate: Boolean,
    recommId: String
  )
)

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.AddBookmark(userId, itemId, {
  // optional parameters:
  'timestamp': <string / number>,
  'cascadeCreate': <boolean>,
  'recommId': <string>
}));

Copy

Initialization

client.send(AddBookmark(user_id, item_id,
    # optional parameters:
    timestamp=<string / number>,
    cascade_create=<boolean>,
    recomm_id=<string>
  )
)

Copy

Initialization

client.send(AddBookmark.new(userId, itemId, {
    # optional parameters:
    :timestamp => <string / number>,
    :cascade_create => <boolean>,
    :recomm_id => <string>
  })
)

Copy

Initialization

client.send(new AddBookmark(String userId, String itemId)
  .setTimestamp(Date timestamp)
  .setCascadeCreate(boolean cascadeCreate)
  .setRecommId(String recommId)
);

Copy

Initialization

<?php
$client->send(new AddBookmark($user_id, $item_id, [
    // optional parameters:
    'timestamp' => <string / number>,
    'cascadeCreate' => <boolean>,
    'recommId' => <string>
  ])
);
?>

Copy

Initialization

client.Send(AddBookmark(string userId, string itemId,
    // optional parameters:
    timestamp: <DateTime>,
    cascadeCreate: <bool>,
    recommId: <string>
  )
);

Copy

Initialization

request := client.NewAddBookmark(userId string, itemId string)    
    // optional parameters:
    .SetTimestamp(timestamp time.Time)
    .SetCascadeCreate(cascadeCreate bool)
    .SetRecommId(recommId string)


_, err := request.Send()

Copy

POST /{databaseId}/bookmarks/
Body (application/json):
{
  "userId" => <string>,
  "itemId" => <string>,
  "timestamp" => <string / number>,
  "cascadeCreate" => <boolean>,
  "recommId" => <string>
}

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

userId

string

Located in: body

Required: Yes

User who bookmarked the item

itemId

string

Located in: body

Required: Yes

Bookmarked item

timestamp

string

number

Located in: body

Required: No

UTC timestamp of the bookmark as ISO8601-1 pattern or UTC epoch time. The default value is the current time.

cascadeCreate

boolean

Located in: body

Required: No

Sets whether the given user/item should be created if not present in the database.

recommId

string

Located in: body

Required: No

Since version: 2.2.0

If this bookmark is based on a recommendation request, recommId is the id of the clicked recommendation.

Responses

200

Successful operation.

400

The userId or itemId does not match ^[a-zA-Z0-9_-:@.]+$, timestamp is not a real number ≥ 0.

404

The cascadeCreate is not set true and the userId or the itemId were found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

409

A bookmark of the exact same userId, itemId, and timestamp is already present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.

delete

Delete Bookmark

Deletes a bookmark uniquely specified by userId, itemId, and timestamp or all the bookmarks with the given userId and itemId if timestamp is omitted.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.DeleteBookmark(userId, itemId, {
  // optional parameters:
  'timestamp': <number>
}));

Copy

Initialization

client.send(DeleteBookmark(user_id, item_id,
    # optional parameters:
    timestamp=<number>
  )
)

Copy

Initialization

client.send(DeleteBookmark.new(userId, itemId, {
    # optional parameters:
    :timestamp => <number>
  })
)

Copy

Initialization

client.send(new DeleteBookmark(String userId, String itemId)
  .setTimestamp(Date timestamp)
);

Copy

Initialization

<?php
$client->send(new DeleteBookmark($user_id, $item_id, [
    // optional parameters:
    'timestamp' => <number>
  ])
);
?>

Copy

Initialization

client.Send(DeleteBookmark(string userId, string itemId,
    // optional parameters:
    timestamp: <DateTime>
  )
);

Copy

Initialization

request := client.NewDeleteBookmark(userId string, itemId string)    
    // optional parameters:
    .SetTimestamp(timestamp time.Time)


_, err := request.Send()

Copy

DELETE /{databaseId}/bookmarks/?userId=<string>
&itemId=<string>
&timestamp=<number>

Calls Limit Per Minute

1000

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

userId

string

Located in: query

Required: Yes

ID of the user who made the bookmark.

itemId

string

Located in: query

Required: Yes

ID of the item which was bookmarked.

timestamp

number

Located in: query

Required: No

Unix timestamp of the bookmark. If the timestamp is omitted, then all the bookmarks with the given userId and itemId are deleted.

Responses

200

Successful operation.

400

Given userId or itemId does not match ^[a-zA-Z0-9_-:@.]+$, or timestamp is not a real number ≥ 0.

404

The userId, itemId, or bookmark with the given (userId, itemId, timestamp) not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

get

List Item Bookmarks

Lists all the ever-made bookmarks of the given item.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ListItemBookmarks(itemId))
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(ListItemBookmarks(item_id))

Copy

Initialization

result = client.send(ListItemBookmarks.new(itemId))

Copy

Initialization

Bookmark[] result = client.send(new ListItemBookmarks(String itemId));

Copy

Initialization

<?php
$result = $client->send(new ListItemBookmarks($item_id));
?>

Copy

Initialization

IEnumerable<Bookmark> result = client.Send(ListItemBookmarks(string itemId));

Copy

Initialization

request := client.NewListItemBookmarks(itemId string)

result, err := request.Send() // result is of the type []bindings.Bookmark

Copy

GET /{databaseId}/items/{itemId}/bookmarks/

Calls Limit Per Minute

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

itemId

string

Located in: path

Required: Yes

ID of the item whose bookmarks are to be listed.

Responses

200

Successful operation.

[
  {
    "itemId": "item-x",
    "userId": "user-a",
    "timestamp": 1348151906.0
  },
  {
    "itemId": "item-x",
    "userId": "user-a",
    "timestamp": 1348327154.0
  }
]

400

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

404

Given itemId not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

get

List User Bookmarks

Lists all the bookmarks ever made by the given user.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ListUserBookmarks(userId))
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(ListUserBookmarks(user_id))

Copy

Initialization

result = client.send(ListUserBookmarks.new(userId))

Copy

Initialization

Bookmark[] result = client.send(new ListUserBookmarks(String userId));

Copy

Initialization

<?php
$result = $client->send(new ListUserBookmarks($user_id));
?>

Copy

Initialization

IEnumerable<Bookmark> result = client.Send(ListUserBookmarks(string userId));

Copy

Initialization

request := client.NewListUserBookmarks(userId string)

result, err := request.Send() // result is of the type []bindings.Bookmark

Copy

GET /{databaseId}/users/{userId}/bookmarks/

Calls Limit Per Minute

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

userId

string

Located in: path

Required: Yes

ID of the user whose bookmarks are to be listed.

Responses

200

Successful operation.

[
  {
    "itemId": "item-x",
    "timestamp": 1348151906.0,
    "userId": "user-a"
  },
  {
    "itemId": "item-z",
    "timestamp": 1348239363.0,
    "userId": "user-a"
  }
]

400

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

404

Given userId not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

View Portions

post

Set View Portion

Allowed on Client-Side

Sets viewed portion of an item (for example a video or article) by a user (at a session). If you send a new request with the same (userId, itemId, sessionId), the portion gets updated.

Javascript Kotlin Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new recombee.SetViewPortion(userId, itemId, portion, {
  // optional parameters:
  'sessionId': <string>,
  'timestamp': <string / number>,
  'cascadeCreate': <boolean>,
  'recommId': <string>
}));

Copy

Initialization

client.send(SetViewPortion(userId: String, itemId: String, portion: Double,
    // optional parameters:
    sessionId: String,
    timestamp: Instant,
    cascadeCreate: Boolean,
    recommId: String
  )
)

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.SetViewPortion(userId, itemId, portion, {
  // optional parameters:
  'sessionId': <string>,
  'timestamp': <string / number>,
  'cascadeCreate': <boolean>,
  'recommId': <string>
}));

Copy

Initialization

client.send(SetViewPortion(user_id, item_id, portion,
    # optional parameters:
    session_id=<string>,
    timestamp=<string / number>,
    cascade_create=<boolean>,
    recomm_id=<string>
  )
)

Copy

Initialization

client.send(SetViewPortion.new(userId, itemId, portion, {
    # optional parameters:
    :session_id => <string>,
    :timestamp => <string / number>,
    :cascade_create => <boolean>,
    :recomm_id => <string>
  })
)

Copy

Initialization

client.send(new SetViewPortion(String userId, String itemId, double portion)
  .setSessionId(String sessionId)
  .setTimestamp(Date timestamp)
  .setCascadeCreate(boolean cascadeCreate)
  .setRecommId(String recommId)
);

Copy

Initialization

<?php
$client->send(new SetViewPortion($user_id, $item_id, $portion, [
    // optional parameters:
    'sessionId' => <string>,
    'timestamp' => <string / number>,
    'cascadeCreate' => <boolean>,
    'recommId' => <string>
  ])
);
?>

Copy

Initialization

client.Send(SetViewPortion(string userId, string itemId, double portion,
    // optional parameters:
    sessionId: <string>,
    timestamp: <DateTime>,
    cascadeCreate: <bool>,
    recommId: <string>
  )
);

Copy

Initialization

request := client.NewSetViewPortion(userId string, itemId string, portion float64)    
    // optional parameters:
    .SetSessionId(sessionId string)
    .SetTimestamp(timestamp time.Time)
    .SetCascadeCreate(cascadeCreate bool)
    .SetRecommId(recommId string)


_, err := request.Send()

Copy

POST /{databaseId}/viewportions/
Body (application/json):
{
  "userId" => <string>,
  "itemId" => <string>,
  "portion" => <number>,
  "sessionId" => <string>,
  "timestamp" => <string / number>,
  "cascadeCreate" => <boolean>,
  "recommId" => <string>
}

Since version

2.1.0

Parameters

databaseId

string

Located in: path

Required: Yes

Since version: 2.1.0

ID of your database.

userId

string

Located in: body

Required: Yes

Since version: 2.1.0

User who viewed a portion of the item

itemId

string

Located in: body

Required: Yes

Since version: 2.1.0

Viewed item

portion

number

Located in: body

Required: Yes

Since version: 2.1.0

Viewed portion of the item (number between 0.0 (viewed nothing) and 1.0 (viewed full item) ). It should be the actual viewed part of the item, no matter the seeking. For example, if the user seeked immediately to half of the item and then viewed 10% of the item, the portion should still be 0.1.

sessionId

string

Located in: body

Required: No

Since version: 2.1.0

ID of the session in which the user viewed the item. Default is null (None, nil, NULL etc., depending on the language).

timestamp

string

number

Located in: body

Required: No

Since version: 2.1.0

UTC timestamp of the rating as ISO8601-1 pattern or UTC epoch time. The default value is the current time.

cascadeCreate

boolean

Located in: body

Required: No

Since version: 2.1.0

Sets whether the given user/item should be created if not present in the database.

recommId

string

Located in: body

Required: No

Since version: 2.2.0

If this view portion is based on a recommendation request, recommId is the id of the clicked recommendation.

Responses

200

Successful operation.

400

The userId, itemId or sessionId does not match ^[a-zA-Z0-9_-:@.]+$, or the portion is not a real number from [0.0,1.0].

404

The cascadeCreate is not set true and the userId or the itemId were found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

409

A view portion of the exact same userId, itemId, and a greater or equal timestamp (or a greater portion) is already present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.

delete

Delete View Portion

Deletes an existing view portion specified by (userId, itemId, sessionId) from the database.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.DeleteViewPortion(userId, itemId, {
  // optional parameters:
  'sessionId': <string>
}));

Copy

Initialization

client.send(DeleteViewPortion(user_id, item_id,
    # optional parameters:
    session_id=<string>
  )
)

Copy

Initialization

client.send(DeleteViewPortion.new(userId, itemId, {
    # optional parameters:
    :session_id => <string>
  })
)

Copy

Initialization

client.send(new DeleteViewPortion(String userId, String itemId)
  .setSessionId(String sessionId)
);

Copy

Initialization

<?php
$client->send(new DeleteViewPortion($user_id, $item_id, [
    // optional parameters:
    'sessionId' => <string>
  ])
);
?>

Copy

Initialization

client.Send(DeleteViewPortion(string userId, string itemId,
    // optional parameters:
    sessionId: <string>
  )
);

Copy

Initialization

request := client.NewDeleteViewPortion(userId string, itemId string)    
    // optional parameters:
    .SetSessionId(sessionId string)


_, err := request.Send()

Copy

DELETE /{databaseId}/viewportions/?userId=<string>
&itemId=<string>
&sessionId=<string>

Since version

2.1.0

Calls Limit Per Minute

1000

Parameters

databaseId

string

Located in: path

Required: Yes

Since version: 2.1.0

ID of your database.

userId

string

Located in: query

Required: Yes

Since version: 2.1.0

ID of the user who rated the item.

itemId

string

Located in: query

Required: Yes

Since version: 2.1.0

ID of the item which was rated.

sessionId

string

Located in: query

Required: No

Since version: 2.1.0

Identifier of a session.

Responses

200

Successful operation.

400

Given userId, itemId or sessionId does not match ^[a-zA-Z0-9_-:@.]+$.

404

The userId, itemId or view portion with the given (userId, itemId, sessionId) not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

get

List Item View Portions

Lists all the view portions of an item ever submitted by different users.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ListItemViewPortions(itemId))
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(ListItemViewPortions(item_id))

Copy

Initialization

result = client.send(ListItemViewPortions.new(itemId))

Copy

Initialization

ViewPortion[] result = client.send(new ListItemViewPortions(String itemId));

Copy

Initialization

<?php
$result = $client->send(new ListItemViewPortions($item_id));
?>

Copy

Initialization

IEnumerable<ViewPortion> result = client.Send(ListItemViewPortions(string itemId));

Copy

Initialization

request := client.NewListItemViewPortions(itemId string)

result, err := request.Send() // result is of the type []bindings.ViewPortion

Copy

GET /{databaseId}/items/{itemId}/viewportions/

Since version

2.1.0

Calls Limit Per Minute

Parameters

databaseId

string

Located in: path

Required: Yes

Since version: 2.1.0

ID of your database.

itemId

string

Located in: path

Required: Yes

Since version: 2.1.0

ID of the item whose view portions are to be listed.

Responses

200

Successful operation.

[
  {
    "itemId": "item-x",
    "userId": "user-a",
    "sessionId": "ABAD1D",
    "portion": 0.5,
    "timestamp": 1348151906.0
  },
  {
    "itemId": "item-x",
    "userId": "user-b",
    "sessionId": null,
    "portion": 1,
    "timestamp": 1348239363.0
  }
]

400

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

404

Given itemId not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

get

List User View Portions

Lists all the view portions ever submitted by the given user.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ListUserViewPortions(userId))
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(ListUserViewPortions(user_id))

Copy

Initialization

result = client.send(ListUserViewPortions.new(userId))

Copy

Initialization

ViewPortion[] result = client.send(new ListUserViewPortions(String userId));

Copy

Initialization

<?php
$result = $client->send(new ListUserViewPortions($user_id));
?>

Copy

Initialization

IEnumerable<ViewPortion> result = client.Send(ListUserViewPortions(string userId));

Copy

Initialization

request := client.NewListUserViewPortions(userId string)

result, err := request.Send() // result is of the type []bindings.ViewPortion

Copy

GET /{databaseId}/users/{userId}/viewportions/

Since version

2.1.0

Calls Limit Per Minute

Parameters

databaseId

string

Located in: path

Required: Yes

Since version: 2.1.0

ID of your database.

userId

string

Located in: path

Required: Yes

Since version: 2.1.0

ID of the user whose view portions are to be listed.

Responses

200

Successful operation.

[
  {
    "itemId": "item-x",
    "userId": "user-a",
    "sessionId": "ABAD1D",
    "portion": 0.25,
    "timestamp": 1348151906.0
  },
  {
    "itemId": "item-y",
    "userId": "user-a",
    "sessionId": "EWQKOL",
    "portion": 0.1,
    "timestamp": 1348239363.0
  }
]

400

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

404

Given userId not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

Recommendations

Recommendation methods are capable of recommending items (Recommend items to user, Recommend items to item) or users (Recommend users to item, Recommend users to user).

See Segmentations section for recommendation endpoints that return segments (e.g. recommend categories to a user).

Recommending Items

Recommendation endpoints that return the Items (content, products, etc.).

get

Allowed on Client-Side

Based on the user's past interactions (purchases, ratings, etc.) with the items, recommends top-N items that are most likely to be of high value for the given user.

The most typical use cases are recommendations on the homepage, in some "Picked just for you" section, or in email.

The returned items are sorted by relevance (the first item being the most relevant).

Besides the recommended items, also a unique recommId is returned in the response. It can be used to:

Let Recombee know that this recommendation was successful (e.g., user clicked one of the recommended items). See Reported metrics.
Get subsequent recommended items when the user scrolls down (infinite scroll) or goes to the next page. See Recommend Next Items.

It is also possible to use POST HTTP method (for example in the case of a very long ReQL filter) - query parameters then become body parameters.

Javascript Kotlin Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new recombee.RecommendItemsToUser(userId, count, {
  // optional parameters:
  'scenario': <string>,
  'cascadeCreate': <boolean>,
  'returnProperties': <boolean>,
  'includedProperties': <array>,
  'filter': <string>,
  'booster': <string>,
  'logic': <string / Object>,
  'minRelevance': <string>,
  'rotationRate': <number>,
  'rotationTime': <number>
})).then(function(res) {
  // handle response 
});

Copy

Initialization

val result = client.sendAsync(RecommendItemsToUser(userId: String, count: Long,
    // optional parameters:
    scenario: String,
    cascadeCreate: Boolean,
    returnProperties: Boolean,
    includedProperties: List<String>,
    filter: String,
    booster: String,
    logic: Logic,
    minRelevance: String,
    rotationRate: Double,
    rotationTime: Double
  )
)

result.onSuccess { response: RecommendationResponse ->
    // Handle response
}.onFailure { exception -> // ApiException
    // Handle exception
}

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.RecommendItemsToUser(userId, count, {
  // optional parameters:
  'scenario': <string>,
  'cascadeCreate': <boolean>,
  'returnProperties': <boolean>,
  'includedProperties': <array>,
  'filter': <string>,
  'booster': <string>,
  'logic': <string / Object>,
  'minRelevance': <string>,
  'rotationRate': <number>,
  'rotationTime': <number>
}))
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(RecommendItemsToUser(user_id, count,
    # optional parameters:
    scenario=<string>,
    cascade_create=<boolean>,
    return_properties=<boolean>,
    included_properties=<array>,
    filter=<string>,
    booster=<string>,
    logic=<string / dict>,
    min_relevance=<string>,
    rotation_rate=<number>,
    rotation_time=<number>
  )
)

Copy

Initialization

result = client.send(RecommendItemsToUser.new(userId, count, {
    # optional parameters:
    :scenario => <string>,
    :cascade_create => <boolean>,
    :return_properties => <boolean>,
    :included_properties => <array>,
    :filter => <string>,
    :booster => <string>,
    :logic => <string / Hash>,
    :min_relevance => <string>,
    :rotation_rate => <number>,
    :rotation_time => <number>
  })
)

Copy

Initialization

RecommendationResponse result = client.send(new RecommendItemsToUser(String userId, long count)
  .setScenario(String scenario)
  .setCascadeCreate(boolean cascadeCreate)
  .setReturnProperties(boolean returnProperties)
  .setIncludedProperties(String[] includedProperties)
  .setFilter(String filter)
  .setBooster(String booster)
  .setLogic(Logic logic)
  .setMinRelevance(String minRelevance)
  .setRotationRate(double rotationRate)
  .setRotationTime(double rotationTime)
);

Copy

Initialization

<?php
$result = $client->send(new RecommendItemsToUser($user_id, $count, [
    // optional parameters:
    'scenario' => <string>,
    'cascadeCreate' => <boolean>,
    'returnProperties' => <boolean>,
    'includedProperties' => <array>,
    'filter' => <string>,
    'booster' => <string>,
    'logic' => <string / array (map)>,
    'minRelevance' => <string>,
    'rotationRate' => <number>,
    'rotationTime' => <number>
  ])
);
?>

Copy

Initialization

RecommendationResponse result = client.Send(RecommendItemsToUser(string userId, long count,
    // optional parameters:
    scenario: <string>,
    cascadeCreate: <bool>,
    returnProperties: <bool>,
    includedProperties: <string[]>,
    filter: <string>,
    booster: <string>,
    logic: <Logic>,
    minRelevance: <string>,
    rotationRate: <double>,
    rotationTime: <double>
  )
);

Copy

Initialization

request := client.NewRecommendItemsToUser(userId string, count int)    
    // optional parameters:
    .SetScenario(scenario string)
    .SetCascadeCreate(cascadeCreate bool)
    .SetReturnProperties(returnProperties bool)
    .SetIncludedProperties(includedProperties []string)
    .SetFilter(filter string)
    .SetBooster(booster string)
    .SetLogic(logic bindings.Logic)
    .SetMinRelevance(minRelevance string)
    .SetRotationRate(rotationRate float64)
    .SetRotationTime(rotationTime float64)


result, err := request.Send() // result is of the type bindings.RecommendationResponse

Copy

GET /{databaseId}/recomms/users/{userId}/items/?count=<integer>
&scenario=<string>
&cascadeCreate=<boolean>
&returnProperties=<boolean>
&includedProperties=<array>
&filter=<string>
&booster=<string>
&logic=<string / Object>
&minRelevance=<string>
&rotationRate=<number>
&rotationTime=<number>

Since version

2.0.0

returnProperties

boolean

Located in: query

Required: No

Since version: 2.0.0

With returnProperties=true, property values of the recommended items are returned along with their IDs in a JSON dictionary. The acquired property values can be used to easily display the recommended items to the user.

Example response:

  {
    "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837",
    "recomms": 
      [
        {
          "id": "tv-178",
          "values": {
            "description": "4K TV with 3D feature",
            "categories":   ["Electronics", "Televisions"],
            "price": 342,
            "url": "myshop.com/tv-178"
          }
        },
        {
          "id": "mixer-42",
          "values": {
            "description": "Stainless Steel Mixer",
            "categories":   ["Home & Kitchen"],
            "price": 39,
            "url": "myshop.com/mixer-42"
          }
        }
      ],
     "numberNextRecommsCalls": 0
  }

includedProperties

array

Located in: query

Required: No

Since version: 2.0.0

Allows specifying which properties should be returned when returnProperties=true is set. The properties are given as a comma-separated list.

Example response for includedProperties=description,price:

  {
    "recommId": "a86ee8d5-cd8e-46d1-886c-8b3771d0520b",
    "recomms":
      [
        {
          "id": "tv-178",
          "values": {
            "description": "4K TV with 3D feature",
            "price": 342
          }
        },
        {
          "id": "mixer-42",
          "values": {
            "description": "Stainless Steel Mixer",
            "price": 39
          }
        }
      ],
    "numberNextRecommsCalls": 0
  }

200

Successful operation.

{
  "recommId": "3f6ad2f2-a3f1-4ba1-a690-f4f01f76d4eb",
  "recomms": [
    {
      "id": "item-146"
    },
    {
      "id": "item-462"
    },
    {
      "id": "item-463"
    }
  ],
  "numberNextRecommsCalls": 0
}

400

userId does not match ^[a-zA-Z0-9_-:@.]+$, count is not a positive integer, filter or booster is not valid ReQL expressions, filter expression does not return boolean, booster does not return double or integer.

404

userId not found in the database and cascadeCreate is false. If there is no additional info in the JSON response, you probably have an error in your URL.

get

Allowed on Client-Side

Recommends a set of items that are somehow related to one given item, X. A typical scenario is when the user A is viewing X. Then you may display items to the user that he might also be interested in. Recommend items to item request gives you Top-N such items, optionally taking the target user A into account.

The returned items are sorted by relevance (the first item being the most relevant).

Besides the recommended items, also a unique recommId is returned in the response. It can be used to:

Let Recombee know that this recommendation was successful (e.g., user clicked one of the recommended items). See Reported metrics.
Get subsequent recommended items when the user scrolls down (infinite scroll) or goes to the next page. See Recommend Next Items.

It is also possible to use POST HTTP method (for example in the case of a very long ReQL filter) - query parameters then become body parameters.

Javascript Kotlin Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new recombee.RecommendItemsToItem(itemId, targetUserId, count, {
  // optional parameters:
  'scenario': <string>,
  'cascadeCreate': <boolean>,
  'returnProperties': <boolean>,
  'includedProperties': <array>,
  'filter': <string>,
  'booster': <string>,
  'logic': <string / Object>,
  'minRelevance': <string>,
  'rotationRate': <number>,
  'rotationTime': <number>
})).then(function(res) {
  // handle response 
});

Copy

Initialization

val result = client.sendAsync(RecommendItemsToItem(itemId: String, targetUserId: String, count: Long,
    // optional parameters:
    scenario: String,
    cascadeCreate: Boolean,
    returnProperties: Boolean,
    includedProperties: List<String>,
    filter: String,
    booster: String,
    logic: Logic,
    minRelevance: String,
    rotationRate: Double,
    rotationTime: Double
  )
)

result.onSuccess { response: RecommendationResponse ->
    // Handle response
}.onFailure { exception -> // ApiException
    // Handle exception
}

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.RecommendItemsToItem(itemId, targetUserId, count, {
  // optional parameters:
  'scenario': <string>,
  'cascadeCreate': <boolean>,
  'returnProperties': <boolean>,
  'includedProperties': <array>,
  'filter': <string>,
  'booster': <string>,
  'logic': <string / Object>,
  'minRelevance': <string>,
  'rotationRate': <number>,
  'rotationTime': <number>
}))
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(RecommendItemsToItem(item_id, target_user_id, count,
    # optional parameters:
    scenario=<string>,
    cascade_create=<boolean>,
    return_properties=<boolean>,
    included_properties=<array>,
    filter=<string>,
    booster=<string>,
    logic=<string / dict>,
    min_relevance=<string>,
    rotation_rate=<number>,
    rotation_time=<number>
  )
)

Copy

Initialization

result = client.send(RecommendItemsToItem.new(itemId, targetUserId, count, {
    # optional parameters:
    :scenario => <string>,
    :cascade_create => <boolean>,
    :return_properties => <boolean>,
    :included_properties => <array>,
    :filter => <string>,
    :booster => <string>,
    :logic => <string / Hash>,
    :min_relevance => <string>,
    :rotation_rate => <number>,
    :rotation_time => <number>
  })
)

Copy

Initialization

RecommendationResponse result = client.send(new RecommendItemsToItem(String itemId, String targetUserId, long count)
  .setScenario(String scenario)
  .setCascadeCreate(boolean cascadeCreate)
  .setReturnProperties(boolean returnProperties)
  .setIncludedProperties(String[] includedProperties)
  .setFilter(String filter)
  .setBooster(String booster)
  .setLogic(Logic logic)
  .setMinRelevance(String minRelevance)
  .setRotationRate(double rotationRate)
  .setRotationTime(double rotationTime)
);

Copy

Initialization

<?php
$result = $client->send(new RecommendItemsToItem($item_id, $target_user_id, $count, [
    // optional parameters:
    'scenario' => <string>,
    'cascadeCreate' => <boolean>,
    'returnProperties' => <boolean>,
    'includedProperties' => <array>,
    'filter' => <string>,
    'booster' => <string>,
    'logic' => <string / array (map)>,
    'minRelevance' => <string>,
    'rotationRate' => <number>,
    'rotationTime' => <number>
  ])
);
?>

Copy

Initialization

RecommendationResponse result = client.Send(RecommendItemsToItem(string itemId, string targetUserId, long count,
    // optional parameters:
    scenario: <string>,
    cascadeCreate: <bool>,
    returnProperties: <bool>,
    includedProperties: <string[]>,
    filter: <string>,
    booster: <string>,
    logic: <Logic>,
    minRelevance: <string>,
    rotationRate: <double>,
    rotationTime: <double>
  )
);

Copy

Initialization

request := client.NewRecommendItemsToItem(itemId string, targetUserId string, count int)    
    // optional parameters:
    .SetScenario(scenario string)
    .SetCascadeCreate(cascadeCreate bool)
    .SetReturnProperties(returnProperties bool)
    .SetIncludedProperties(includedProperties []string)
    .SetFilter(filter string)
    .SetBooster(booster string)
    .SetLogic(logic bindings.Logic)
    .SetMinRelevance(minRelevance string)
    .SetRotationRate(rotationRate float64)
    .SetRotationTime(rotationTime float64)


result, err := request.Send() // result is of the type bindings.RecommendationResponse

Copy

GET /{databaseId}/recomms/items/{itemId}/items/?targetUserId=<string>
&count=<integer>
&scenario=<string>
&cascadeCreate=<boolean>
&returnProperties=<boolean>
&includedProperties=<array>
&filter=<string>
&booster=<string>
&logic=<string / Object>
&minRelevance=<string>
&rotationRate=<number>
&rotationTime=<number>

Since version

2.0.0

returnProperties

boolean

Located in: query

Required: No

Since version: 2.0.0

Example response:

  {
    "recommId": "0c6189e7-dc1a-429a-b613-192696309361",
    "recomms":
      [
        {
          "id": "tv-178",
          "values": {
            "description": "4K TV with 3D feature",
            "categories":   ["Electronics", "Televisions"],
            "price": 342,
            "url": "myshop.com/tv-178"
          }
        },
        {
          "id": "mixer-42",
          "values": {
            "description": "Stainless Steel Mixer",
            "categories":   ["Home & Kitchen"],
            "price": 39,
            "url": "myshop.com/mixer-42"
          }
        }
      ],
    "numberNextRecommsCalls": 0
  }

includedProperties

array

Located in: query

Required: No

Since version: 2.0.0

Allows specifying which properties should be returned when returnProperties=true is set. The properties are given as a comma-separated list.

Example response for includedProperties=description,price:

  {
    "recommId": "6842c725-a79f-4537-a02c-f34d668a3f80",
    "recomms": 
      [
        {
          "id": "tv-178",
          "values": {
            "description": "4K TV with 3D feature",
            "price": 342
          }
        },
        {
          "id": "mixer-42",
          "values": {
            "description": "Stainless Steel Mixer",
            "price": 39
          }
        }
      ],
    "numberNextRecommsCalls": 0
  }

200

Successful operation.

{
  "recommId": "768448ea-10b3-4028-bb76-4b2f95121d19",
  "recomms": [
    {
      "id": "item-146"
    },
    {
      "id": "item-462"
    },
    {
      "id": "item-463"
    }
  ],
  "numberNextRecommsCalls": 0
}

400

itemId does not match ^[a-zA-Z0-9_-:@.]+$, count is not a positive integer, filter or booster is not valid ReQL expressions, filter expression does not return boolean, booster does not return double or integer.

404

itemId not found in the database and cascadeCreate is false. If there is no additional info in the JSON response, you probably have an error in your URL.

get

Allowed on Client-Side

Returns items that shall be shown to a user as next recommendations when the user e.g. scrolls the page down (infinite scroll) or goes to the next page.

It accepts recommId of a base recommendation request (e.g., request from the first page) and the number of items that shall be returned (count). The base request can be one of:

All the other parameters are inherited from the base request.

Recommend next items can be called many times for a single recommId and each call returns different (previously not recommended) items. The number of Recommend next items calls performed so far is returned in the numberNextRecommsCalls field.

Recommend next items can be requested up to 30 minutes after the base request or a previous Recommend next items call.

For billing purposes, each call to Recommend next items is counted as a separate recommendation request.

Javascript Kotlin Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new recombee.RecommendNextItems(recommId, count)).then(function(res) {
  // handle response 
});

Copy

Initialization

val result = client.sendAsync(RecommendNextItems(recommId: String, count: Long))

result.onSuccess { response: RecommendationResponse ->
    // Handle response
}.onFailure { exception -> // ApiException
    // Handle exception
}

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.RecommendNextItems(recommId, count))
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(RecommendNextItems(recomm_id, count))

Copy

Initialization

result = client.send(RecommendNextItems.new(recommId, count))

Copy

Initialization

RecommendationResponse result = client.send(new RecommendNextItems(String recommId, long count));

Copy

Initialization

<?php
$result = $client->send(new RecommendNextItems($recomm_id, $count));
?>

Copy

Initialization

RecommendationResponse result = client.Send(RecommendNextItems(string recommId, long count));

Copy

Initialization

request := client.NewRecommendNextItems(recommId string, count int)

result, err := request.Send() // result is of the type bindings.RecommendationResponse

Copy

GET /{databaseId}/recomms/next/items/{recommId}?count=<integer>

Since version

3.1.0

200

Successful operation.

{
  "recommId": "768448ea-10b3-4028-bb76-4b2f95121d19",
  "recomms": [
    {
      "id": "item-176"
    },
    {
      "id": "item-141"
    },
    {
      "id": "item-967"
    }
  ],
  "numberNextRecommsCalls": 4
}

400

Parameter count is not given or is not a positive integer. Parameter recommId is not an UUID.

404

Base request with the given recommId does not exist or has expired.

Recommending Item Segments

Recommendation endpoints that return the Item Segments (categories, genres, artists, etc.).

get

Allowed on Client-Side

Recommends the top Segments from a Segmentation for a particular user, based on the user's past interactions.

Based on the used Segmentation, this endpoint can be used for example for:

Recommending the top categories for the user
Recommending the top genres for the user
Recommending the top brands for the user
Recommending the top artists for the user

You need to set the used Segmentation the Admin UI in the Scenario settings prior to using this endpoint.

The returned segments are sorted by relevance (first segment being the most relevant).

It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.

Javascript Kotlin Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new recombee.RecommendItemSegmentsToUser(userId, count, {
  // optional parameters:
  'scenario': <string>,
  'cascadeCreate': <boolean>,
  'filter': <string>,
  'booster': <string>,
  'logic': <string / Object>
})).then(function(res) {
  // handle response 
});

Copy

Initialization

val result = client.sendAsync(RecommendItemSegmentsToUser(userId: String, count: Long,
    // optional parameters:
    scenario: String,
    cascadeCreate: Boolean,
    filter: String,
    booster: String,
    logic: Logic
  )
)

result.onSuccess { response: RecommendationResponse ->
    // Handle response
}.onFailure { exception -> // ApiException
    // Handle exception
}

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.RecommendItemSegmentsToUser(userId, count, {
  // optional parameters:
  'scenario': <string>,
  'cascadeCreate': <boolean>,
  'filter': <string>,
  'booster': <string>,
  'logic': <string / Object>
}))
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(RecommendItemSegmentsToUser(user_id, count,
    # optional parameters:
    scenario=<string>,
    cascade_create=<boolean>,
    filter=<string>,
    booster=<string>,
    logic=<string / dict>
  )
)

Copy

Initialization

result = client.send(RecommendItemSegmentsToUser.new(userId, count, {
    # optional parameters:
    :scenario => <string>,
    :cascade_create => <boolean>,
    :filter => <string>,
    :booster => <string>,
    :logic => <string / Hash>
  })
)

Copy

Initialization

RecommendationResponse result = client.send(new RecommendItemSegmentsToUser(String userId, long count)
  .setScenario(String scenario)
  .setCascadeCreate(boolean cascadeCreate)
  .setFilter(String filter)
  .setBooster(String booster)
  .setLogic(Logic logic)
);

Copy

Initialization

<?php
$result = $client->send(new RecommendItemSegmentsToUser($user_id, $count, [
    // optional parameters:
    'scenario' => <string>,
    'cascadeCreate' => <boolean>,
    'filter' => <string>,
    'booster' => <string>,
    'logic' => <string / array (map)>
  ])
);
?>

Copy

Initialization

RecommendationResponse result = client.Send(RecommendItemSegmentsToUser(string userId, long count,
    // optional parameters:
    scenario: <string>,
    cascadeCreate: <bool>,
    filter: <string>,
    booster: <string>,
    logic: <Logic>
  )
);

Copy

Initialization

request := client.NewRecommendItemSegmentsToUser(userId string, count int)    
    // optional parameters:
    .SetScenario(scenario string)
    .SetCascadeCreate(cascadeCreate bool)
    .SetFilter(filter string)
    .SetBooster(booster string)
    .SetLogic(logic bindings.Logic)


result, err := request.Send() // result is of the type bindings.RecommendationResponse

Copy

GET /{databaseId}/recomms/users/{userId}/item-segments/?count=<integer>
&scenario=<string>
&cascadeCreate=<boolean>
&filter=<string>
&booster=<string>
&logic=<string / Object>

Since version

4.1.0

200

successful operation

{
  "recommId": "5fbd94fa-2553-422c-bdb5-af82687d8c6a",
  "recomms": [
    {
      "id": "category-rap"
    },
    {
      "id": "category-dnb"
    },
    {
      "id": "category-electronic"
    }
  ],
  "numberNextRecommsCalls": 0
}

400

Used Segmentation not configured for the scenario. userId does not match ^[a-zA-Z0-9_-:@.]+$, count is not a positive integer.

404

userId not found in the database and cascadeCreate is false

get

Allowed on Client-Side

Recommends Segments from a Segmentation that are the most relevant to a particular item.

Based on the used Segmentation, this endpoint can be used for example for:

Recommending the related categories
Recommending the related genres
Recommending the related brands
Recommending the related artists

You need to set the used Segmentation the Admin UI in the Scenario settings prior to using this endpoint.

The returned segments are sorted by relevance (first segment being the most relevant).

It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.

Javascript Kotlin Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new recombee.RecommendItemSegmentsToItem(itemId, targetUserId, count, {
  // optional parameters:
  'scenario': <string>,
  'cascadeCreate': <boolean>,
  'filter': <string>,
  'booster': <string>,
  'logic': <string / Object>
})).then(function(res) {
  // handle response 
});

Copy

Initialization

val result = client.sendAsync(RecommendItemSegmentsToItem(itemId: String, targetUserId: String, count: Long,
    // optional parameters:
    scenario: String,
    cascadeCreate: Boolean,
    filter: String,
    booster: String,
    logic: Logic
  )
)

result.onSuccess { response: RecommendationResponse ->
    // Handle response
}.onFailure { exception -> // ApiException
    // Handle exception
}

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.RecommendItemSegmentsToItem(itemId, targetUserId, count, {
  // optional parameters:
  'scenario': <string>,
  'cascadeCreate': <boolean>,
  'filter': <string>,
  'booster': <string>,
  'logic': <string / Object>
}))
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(RecommendItemSegmentsToItem(item_id, target_user_id, count,
    # optional parameters:
    scenario=<string>,
    cascade_create=<boolean>,
    filter=<string>,
    booster=<string>,
    logic=<string / dict>
  )
)

Copy

Initialization

result = client.send(RecommendItemSegmentsToItem.new(itemId, targetUserId, count, {
    # optional parameters:
    :scenario => <string>,
    :cascade_create => <boolean>,
    :filter => <string>,
    :booster => <string>,
    :logic => <string / Hash>
  })
)

Copy

Initialization

RecommendationResponse result = client.send(new RecommendItemSegmentsToItem(String itemId, String targetUserId, long count)
  .setScenario(String scenario)
  .setCascadeCreate(boolean cascadeCreate)
  .setFilter(String filter)
  .setBooster(String booster)
  .setLogic(Logic logic)
);

Copy

Initialization

<?php
$result = $client->send(new RecommendItemSegmentsToItem($item_id, $target_user_id, $count, [
    // optional parameters:
    'scenario' => <string>,
    'cascadeCreate' => <boolean>,
    'filter' => <string>,
    'booster' => <string>,
    'logic' => <string / array (map)>
  ])
);
?>

Copy

Initialization

RecommendationResponse result = client.Send(RecommendItemSegmentsToItem(string itemId, string targetUserId, long count,
    // optional parameters:
    scenario: <string>,
    cascadeCreate: <bool>,
    filter: <string>,
    booster: <string>,
    logic: <Logic>
  )
);

Copy

Initialization

request := client.NewRecommendItemSegmentsToItem(itemId string, targetUserId string, count int)    
    // optional parameters:
    .SetScenario(scenario string)
    .SetCascadeCreate(cascadeCreate bool)
    .SetFilter(filter string)
    .SetBooster(booster string)
    .SetLogic(logic bindings.Logic)


result, err := request.Send() // result is of the type bindings.RecommendationResponse

Copy

GET /{databaseId}/recomms/items/{itemId}/item-segments/?targetUserId=<string>
&count=<integer>
&scenario=<string>
&cascadeCreate=<boolean>
&filter=<string>
&booster=<string>
&logic=<string / Object>

Since version

4.1.0

200

successful operation

{
  "recommId": "5fbd94fa-2553-422c-bdb5-af82687d8c6a",
  "recomms": [
    {
      "id": "category-rap"
    },
    {
      "id": "category-dnb"
    },
    {
      "id": "category-electronic"
    }
  ],
  "numberNextRecommsCalls": 0
}

400

Used Segmentation not configured for the scenario. itemId does not match ^[a-zA-Z0-9_-:@.]+$, count is not a positive integer.

404

itemId not found in the database and cascadeCreate is false

get

Allowed on Client-Side

Recommends Segments from a result Segmentation that are the most relevant to a particular Segment from a context Segmentation.

Based on the used Segmentations, this endpoint can be used for example for:

Recommending the related brands to particular brand
Recommending the related brands to particular category
Recommending the related artists to a particular genre (assuming songs are the Items)

You need to set the used context and result Segmentation the Admin UI in the Scenario settings prior to using this endpoint.

The returned segments are sorted by relevance (first segment being the most relevant).

It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.

Javascript Kotlin Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new recombee.RecommendItemSegmentsToItemSegment(contextSegmentId, targetUserId, count, {
  // optional parameters:
  'scenario': <string>,
  'cascadeCreate': <boolean>,
  'filter': <string>,
  'booster': <string>,
  'logic': <string / Object>
})).then(function(res) {
  // handle response 
});

Copy

Initialization

val result = client.sendAsync(RecommendItemSegmentsToItemSegment(contextSegmentId: String, targetUserId: String, count: Long,
    // optional parameters:
    scenario: String,
    cascadeCreate: Boolean,
    filter: String,
    booster: String,
    logic: Logic
  )
)

result.onSuccess { response: RecommendationResponse ->
    // Handle response
}.onFailure { exception -> // ApiException
    // Handle exception
}

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.RecommendItemSegmentsToItemSegment(contextSegmentId, targetUserId, count, {
  // optional parameters:
  'scenario': <string>,
  'cascadeCreate': <boolean>,
  'filter': <string>,
  'booster': <string>,
  'logic': <string / Object>
}))
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(RecommendItemSegmentsToItemSegment(context_segment_id, target_user_id, count,
    # optional parameters:
    scenario=<string>,
    cascade_create=<boolean>,
    filter=<string>,
    booster=<string>,
    logic=<string / dict>
  )
)

Copy

Initialization

result = client.send(RecommendItemSegmentsToItemSegment.new(contextSegmentId, targetUserId, count, {
    # optional parameters:
    :scenario => <string>,
    :cascade_create => <boolean>,
    :filter => <string>,
    :booster => <string>,
    :logic => <string / Hash>
  })
)

Copy

Initialization

RecommendationResponse result = client.send(new RecommendItemSegmentsToItemSegment(String contextSegmentId, String targetUserId, long count)
  .setScenario(String scenario)
  .setCascadeCreate(boolean cascadeCreate)
  .setFilter(String filter)
  .setBooster(String booster)
  .setLogic(Logic logic)
);

Copy

Initialization

<?php
$result = $client->send(new RecommendItemSegmentsToItemSegment($context_segment_id, $target_user_id, $count, [
    // optional parameters:
    'scenario' => <string>,
    'cascadeCreate' => <boolean>,
    'filter' => <string>,
    'booster' => <string>,
    'logic' => <string / array (map)>
  ])
);
?>

Copy

Initialization

RecommendationResponse result = client.Send(RecommendItemSegmentsToItemSegment(string contextSegmentId, string targetUserId, long count,
    // optional parameters:
    scenario: <string>,
    cascadeCreate: <bool>,
    filter: <string>,
    booster: <string>,
    logic: <Logic>
  )
);

Copy

Initialization

request := client.NewRecommendItemSegmentsToItemSegment(contextSegmentId string, targetUserId string, count int)    
    // optional parameters:
    .SetScenario(scenario string)
    .SetCascadeCreate(cascadeCreate bool)
    .SetFilter(filter string)
    .SetBooster(booster string)
    .SetLogic(logic bindings.Logic)


result, err := request.Send() // result is of the type bindings.RecommendationResponse

Copy

GET /{databaseId}/recomms/item-segments/item-segments/?contextSegmentId=<string>
&targetUserId=<string>
&count=<integer>
&scenario=<string>
&cascadeCreate=<boolean>
&filter=<string>
&booster=<string>
&logic=<string / Object>

Since version

4.1.0

200

successful operation

{
  "recommId": "5fbd94fa-2553-422c-bdb5-af82687d8c6a",
  "recomms": [
    {
      "id": "category-rap"
    },
    {
      "id": "category-dnb"
    },
    {
      "id": "category-electronic"
    }
  ],
  "numberNextRecommsCalls": 0
}

400

count is not a positive integer.

404

contextSegmentId not found in the context segmentation

Recommending Users

Recommendation endpoints that return the Users.

get

Gets users similar to the given user, based on the user's past interactions (purchases, ratings, etc.) and values of properties.

It is also possible to use POST HTTP method (for example in the case of a very long ReQL filter) - query parameters then become body parameters.

The returned users are sorted by similarity (the first user being the most similar).

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.RecommendUsersToUser(userId, count, {
  // optional parameters:
  'scenario': <string>,
  'cascadeCreate': <boolean>,
  'returnProperties': <boolean>,
  'includedProperties': <array>,
  'filter': <string>,
  'booster': <string>,
  'logic': <string / Object>
}))
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(RecommendUsersToUser(user_id, count,
    # optional parameters:
    scenario=<string>,
    cascade_create=<boolean>,
    return_properties=<boolean>,
    included_properties=<array>,
    filter=<string>,
    booster=<string>,
    logic=<string / dict>
  )
)

Copy

Initialization

result = client.send(RecommendUsersToUser.new(userId, count, {
    # optional parameters:
    :scenario => <string>,
    :cascade_create => <boolean>,
    :return_properties => <boolean>,
    :included_properties => <array>,
    :filter => <string>,
    :booster => <string>,
    :logic => <string / Hash>
  })
)

Copy

Initialization

RecommendationResponse result = client.send(new RecommendUsersToUser(String userId, long count)
  .setScenario(String scenario)
  .setCascadeCreate(boolean cascadeCreate)
  .setReturnProperties(boolean returnProperties)
  .setIncludedProperties(String[] includedProperties)
  .setFilter(String filter)
  .setBooster(String booster)
  .setLogic(Logic logic)
);

Copy

Initialization

<?php
$result = $client->send(new RecommendUsersToUser($user_id, $count, [
    // optional parameters:
    'scenario' => <string>,
    'cascadeCreate' => <boolean>,
    'returnProperties' => <boolean>,
    'includedProperties' => <array>,
    'filter' => <string>,
    'booster' => <string>,
    'logic' => <string / array (map)>
  ])
);
?>

Copy

Initialization

RecommendationResponse result = client.Send(RecommendUsersToUser(string userId, long count,
    // optional parameters:
    scenario: <string>,
    cascadeCreate: <bool>,
    returnProperties: <bool>,
    includedProperties: <string[]>,
    filter: <string>,
    booster: <string>,
    logic: <Logic>
  )
);

Copy

Initialization

request := client.NewRecommendUsersToUser(userId string, count int)    
    // optional parameters:
    .SetScenario(scenario string)
    .SetCascadeCreate(cascadeCreate bool)
    .SetReturnProperties(returnProperties bool)
    .SetIncludedProperties(includedProperties []string)
    .SetFilter(filter string)
    .SetBooster(booster string)
    .SetLogic(logic bindings.Logic)


result, err := request.Send() // result is of the type bindings.RecommendationResponse

Copy

GET /{databaseId}/recomms/users/{userId}/users/?count=<integer>
&scenario=<string>
&cascadeCreate=<boolean>
&returnProperties=<boolean>
&includedProperties=<array>
&filter=<string>
&booster=<string>
&logic=<string / Object>

Since version

2.0.0

returnProperties

boolean

Located in: query

Required: No

Since version: 2.0.0

With returnProperties=true, property values of the recommended users are returned along with their IDs in a JSON dictionary. The acquired property values can be used to easily display the recommended users.

Example response:

  {
    "recommId": "9cb9c55d-50ba-4478-84fd-ab456136156e",
    "recomms": 
      [
        {
          "id": "user-17",
          "values": {
            "country": "US",
            "sex": "F"
          }
        },
        {
          "id": "user-2",
          "values": {
            "country": "CAN",
            "sex": "M"
          }
        }
      ],
    "numberNextRecommsCalls": 0
  }

includedProperties

array

Located in: query

Required: No

Since version: 2.0.0

Allows specifying which properties should be returned when returnProperties=true is set. The properties are given as a comma-separated list.

Example response for includedProperties=country:

  {
    "recommId": "b326d82d-5d57-4b45-b362-c9d6f0895855",
    "recomms":
      [
        {
          "id": "user-17",
          "values": {
            "country": "US"
          }
        },
        {
          "id": "user-2",
          "values": {
            "country": "CAN"
          }
        }
      ],
    "numberNextRecommsCalls": 0
  }

200

Successful operation.

{
  "recommId": "f88d970d-561c-460f-b4d4-faf0478244ca",
  "recomms": [
    {
      "id": "user-64"
    },
    {
      "id": "user-42"
    },
    {
      "id": "user-23"
    }
  ],
  "numberNextRecommsCalls": 0
}

400

404

userId not found in the database and cascadeCreate is false. If there is no additional info in the JSON response, you probably have an error in your URL.

get

Recommends users that are likely to be interested in the given item.

It is also possible to use POST HTTP method (for example in the case of a very long ReQL filter) - query parameters then become body parameters.

The returned users are sorted by predicted interest in the item (the first user being the most interested).

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.RecommendUsersToItem(itemId, count, {
  // optional parameters:
  'scenario': <string>,
  'cascadeCreate': <boolean>,
  'returnProperties': <boolean>,
  'includedProperties': <array>,
  'filter': <string>,
  'booster': <string>,
  'logic': <string / Object>
}))
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(RecommendUsersToItem(item_id, count,
    # optional parameters:
    scenario=<string>,
    cascade_create=<boolean>,
    return_properties=<boolean>,
    included_properties=<array>,
    filter=<string>,
    booster=<string>,
    logic=<string / dict>
  )
)

Copy

Initialization

result = client.send(RecommendUsersToItem.new(itemId, count, {
    # optional parameters:
    :scenario => <string>,
    :cascade_create => <boolean>,
    :return_properties => <boolean>,
    :included_properties => <array>,
    :filter => <string>,
    :booster => <string>,
    :logic => <string / Hash>
  })
)

Copy

Initialization

RecommendationResponse result = client.send(new RecommendUsersToItem(String itemId, long count)
  .setScenario(String scenario)
  .setCascadeCreate(boolean cascadeCreate)
  .setReturnProperties(boolean returnProperties)
  .setIncludedProperties(String[] includedProperties)
  .setFilter(String filter)
  .setBooster(String booster)
  .setLogic(Logic logic)
);

Copy

Initialization

<?php
$result = $client->send(new RecommendUsersToItem($item_id, $count, [
    // optional parameters:
    'scenario' => <string>,
    'cascadeCreate' => <boolean>,
    'returnProperties' => <boolean>,
    'includedProperties' => <array>,
    'filter' => <string>,
    'booster' => <string>,
    'logic' => <string / array (map)>
  ])
);
?>

Copy

Initialization

RecommendationResponse result = client.Send(RecommendUsersToItem(string itemId, long count,
    // optional parameters:
    scenario: <string>,
    cascadeCreate: <bool>,
    returnProperties: <bool>,
    includedProperties: <string[]>,
    filter: <string>,
    booster: <string>,
    logic: <Logic>
  )
);

Copy

Initialization

request := client.NewRecommendUsersToItem(itemId string, count int)    
    // optional parameters:
    .SetScenario(scenario string)
    .SetCascadeCreate(cascadeCreate bool)
    .SetReturnProperties(returnProperties bool)
    .SetIncludedProperties(includedProperties []string)
    .SetFilter(filter string)
    .SetBooster(booster string)
    .SetLogic(logic bindings.Logic)


result, err := request.Send() // result is of the type bindings.RecommendationResponse

Copy

GET /{databaseId}/recomms/items/{itemId}/users/?count=<integer>
&scenario=<string>
&cascadeCreate=<boolean>
&returnProperties=<boolean>
&includedProperties=<array>
&filter=<string>
&booster=<string>
&logic=<string / Object>

Since version

2.0.0

returnProperties

boolean

Located in: query

Required: No

Since version: 2.0.0

Example response:

  {
    "recommId": "039b71dc-b9cc-4645-a84f-62b841eecfce",
    "recomms":
      [
        {
          "id": "user-17",
          "values": {
            "country": "US",
            "sex": "F"
          }
        },
        {
          "id": "user-2",
          "values": {
            "country": "CAN",
            "sex": "M"
          }
        }
      ],
    "numberNextRecommsCalls": 0
  }

includedProperties

array

Located in: query

Required: No

Since version: 2.0.0

Allows specifying which properties should be returned when returnProperties=true is set. The properties are given as a comma-separated list.

Example response for includedProperties=country:

  {
    "recommId": "b2b355dd-972a-4728-9c6b-2dc229db0678",
    "recomms":
      [
        {
          "id": "user-17",
          "values": {
            "country": "US"
          }
        },
        {
          "id": "user-2",
          "values": {
            "country": "CAN"
          }
        }
      ],
    "numberNextRecommsCalls": 0
  }

200

Successful operation.

{
  "recommId": "ee94fa8b-efe7-4b35-abc6-2bc3456d66ed",
  "recomms": [
    {
      "id": "user-64"
    },
    {
      "id": "user-42"
    },
    {
      "id": "user-23"
    }
  ],
  "numberNextRecommsCalls": 0
}

400

404

itemId not found in the database and cascadeCreate is false. If there is no additional info in the JSON response, you probably have an error in your URL.

Search

Full-text personalized search. The results are based on the full-text matching of a search query and the preferences of a particular user.

get

Search Items

Allowed on Client-Side

Full-text personalized search. The results are based on the provided searchQuery and also on the user's past interactions (purchases, ratings, etc.) with the items (items more suitable for the user are preferred in the results).

All the string and set item properties are indexed by the search engine.

This endpoint should be used in a search box on your website/app. It can be called multiple times as the user is typing the query in order to get the most viable suggestions based on the current state of the query, or once after submitting the whole query.

The returned items are sorted by relevance (the first item being the most relevant).

Besides the recommended items, also a unique recommId is returned in the response. It can be used to:

Let Recombee know that this search was successful (e.g., user clicked one of the recommended items). See Reported metrics.
Get subsequent search results when the user scrolls down or goes to the next page. See Recommend Next Items.

It is also possible to use POST HTTP method (for example in the case of a very long ReQL filter) - query parameters then become body parameters.

Javascript Kotlin Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new recombee.SearchItems(userId, searchQuery, count, {
  // optional parameters:
  'scenario': <string>,
  'cascadeCreate': <boolean>,
  'returnProperties': <boolean>,
  'includedProperties': <array>,
  'filter': <string>,
  'booster': <string>,
  'logic': <string / Object>
})).then(function(res) {
  // handle response 
});

Copy

Initialization

val result = client.sendAsync(SearchItems(userId: String, searchQuery: String, count: Long,
    // optional parameters:
    scenario: String,
    cascadeCreate: Boolean,
    returnProperties: Boolean,
    includedProperties: List<String>,
    filter: String,
    booster: String,
    logic: Logic
  )
)

result.onSuccess { response: SearchResponse ->
    // Handle response
}.onFailure { exception -> // ApiException
    // Handle exception
}

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.SearchItems(userId, searchQuery, count, {
  // optional parameters:
  'scenario': <string>,
  'cascadeCreate': <boolean>,
  'returnProperties': <boolean>,
  'includedProperties': <array>,
  'filter': <string>,
  'booster': <string>,
  'logic': <string / Object>
}))
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(SearchItems(user_id, search_query, count,
    # optional parameters:
    scenario=<string>,
    cascade_create=<boolean>,
    return_properties=<boolean>,
    included_properties=<array>,
    filter=<string>,
    booster=<string>,
    logic=<string / dict>
  )
)

Copy

Initialization

result = client.send(SearchItems.new(userId, searchQuery, count, {
    # optional parameters:
    :scenario => <string>,
    :cascade_create => <boolean>,
    :return_properties => <boolean>,
    :included_properties => <array>,
    :filter => <string>,
    :booster => <string>,
    :logic => <string / Hash>
  })
)

Copy

Initialization

SearchResponse result = client.send(new SearchItems(String userId, String searchQuery, long count)
  .setScenario(String scenario)
  .setCascadeCreate(boolean cascadeCreate)
  .setReturnProperties(boolean returnProperties)
  .setIncludedProperties(String[] includedProperties)
  .setFilter(String filter)
  .setBooster(String booster)
  .setLogic(Logic logic)
);

Copy

Initialization

<?php
$result = $client->send(new SearchItems($user_id, $search_query, $count, [
    // optional parameters:
    'scenario' => <string>,
    'cascadeCreate' => <boolean>,
    'returnProperties' => <boolean>,
    'includedProperties' => <array>,
    'filter' => <string>,
    'booster' => <string>,
    'logic' => <string / array (map)>
  ])
);
?>

Copy

Initialization

SearchResponse result = client.Send(SearchItems(string userId, string searchQuery, long count,
    // optional parameters:
    scenario: <string>,
    cascadeCreate: <bool>,
    returnProperties: <bool>,
    includedProperties: <string[]>,
    filter: <string>,
    booster: <string>,
    logic: <Logic>
  )
);

Copy

Initialization

request := client.NewSearchItems(userId string, searchQuery string, count int)    
    // optional parameters:
    .SetScenario(scenario string)
    .SetCascadeCreate(cascadeCreate bool)
    .SetReturnProperties(returnProperties bool)
    .SetIncludedProperties(includedProperties []string)
    .SetFilter(filter string)
    .SetBooster(booster string)
    .SetLogic(logic bindings.Logic)


result, err := request.Send() // result is of the type bindings.SearchResponse

Copy

GET /{databaseId}/search/users/{userId}/items/?searchQuery=<string>
&count=<integer>
&scenario=<string>
&cascadeCreate=<boolean>
&returnProperties=<boolean>
&includedProperties=<array>
&filter=<string>
&booster=<string>
&logic=<string / Object>

Since version

3.0.0

Parameters

databaseId

string

Located in: path

Required: Yes

Since version: 3.0.0

ID of your database.

userId

string

Located in: path

Required: Yes

Since version: 3.0.0

ID of the user for whom personalized search will be performed.

searchQuery

string

Located in: query

Required: Yes

Since version: 3.0.0

Search query provided by the user. It is used for the full-text search.

count

integer

Located in: query

Required: Yes

Since version: 3.0.0

Number of items to be returned (N for the top-N results).

scenario

string

Located in: query

Required: No

Since version: 3.0.0

Scenario defines a particular search field in your user interface.

You can set various settings to the scenario in the Admin UI. You can also see the performance of each scenario in the Admin UI separately, so you can check how well each field performs.

The AI that optimizes models to get the best results may optimize different scenarios separately, or even use different models in each of the scenarios.

cascadeCreate

boolean

Located in: query

Required: No

Since version: 3.0.0

If the user does not exist in the database, returns a list of non-personalized search results and creates the user in the database. This allows, for example, rotations in the following recommendations for that user, as the user will be already known to the system.

returnProperties

boolean

Located in: query

Required: No

Since version: 3.0.0

Example response:

  {
    "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837",
    "recomms": 
      [
        {
          "id": "tv-178",
          "values": {
            "description": "4K TV with 3D feature",
            "categories":   ["Electronics", "Televisions"],
            "price": 342,
            "url": "myshop.com/tv-178"
          }
        },
        {
          "id": "mixer-42",
          "values": {
            "description": "Stainless Steel Mixer",
            "categories":   ["Home & Kitchen"],
            "price": 39,
            "url": "myshop.com/mixer-42"
          }
        }
      ],
    "numberNextRecommsCalls": 0
  }

includedProperties

array

Located in: query

Required: No

Since version: 3.0.0

Allows specifying which properties should be returned when returnProperties=true is set. The properties are given as a comma-separated list.

Example response for includedProperties=description,price:

  {
    "recommId": "a86ee8d5-cd8e-46d1-886c-8b3771d0520b",
    "recomms":
      [
        {
          "id": "tv-178",
          "values": {
            "description": "4K TV with 3D feature",
            "price": 342
          }
        },
        {
          "id": "mixer-42",
          "values": {
            "description": "Stainless Steel Mixer",
            "price": 39
          }
        }
      ],
    "numberNextRecommsCalls": 0
  }

filter

string

Located in: query

Required: No

Since version: 2.0.0

Boolean-returning ReQL expression, which allows you to filter recommended items based on the values of their attributes.

Filters can also be assigned to a scenario in the Admin UI.

booster

string

Located in: query

Required: No

Since version: 2.0.0

Number-returning ReQL expression, which allows you to boost the recommendation rate of some items based on the values of their attributes.

Boosters can also be assigned to a scenario in the Admin UI.

logic

string

object

Located in: query

Required: No

Since version: 2.4.0

Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. See this section for a list of available logics and other details.

The difference between logic and scenario is that logic specifies mainly behavior, while scenario specifies the place where recommendations are shown to the users.

Logic can also be set to a scenario in the Admin UI.

Responses

200

Successful operation.

{
  "recommId": "4fd901fe-4ba1-a3f1-a690-f4f01f76d4eb",
  "recomms": [
    {
      "id": "item-476"
    },
    {
      "id": "item-412"
    },
    {
      "id": "item-773"
    }
  ],
  "numberNextRecommsCalls": 0
}

400

userId does not match ^[a-zA-Z0-9_-:@.]+$, count is not a positive integer, searchQuery is not provided, filter or booster are not valid ReQL expressions, filter expression does not return boolean, booster does not return double or integer.

404

userId not found in the database and cascadeCreate is false. If there is no additional info in the JSON response, you probably have an error in you URL.

get

Search Item Segments

Allowed on Client-Side

Full-text personalized search that returns Segments from a Segmentation. The results are based on the provided searchQuery and also on the user's past interactions (purchases, ratings, etc.).

Based on the used Segmentation, this endpoint can be used for example for:

Searching within categories or brands
Searching within genres or artists

For example if the user is searching for "iPhone" this endpoint can return "cell phones" category.

You need to set the used Segmentation the Admin UI in the Scenario settings prior to using this endpoint.

The returned segments are sorted by relevance (first segment being the most relevant).

It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.

Javascript Kotlin Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new recombee.SearchItemSegments(userId, searchQuery, count, {
  // optional parameters:
  'scenario': <string>,
  'cascadeCreate': <boolean>,
  'filter': <string>,
  'booster': <string>,
  'logic': <string / Object>
})).then(function(res) {
  // handle response 
});

Copy

Initialization

val result = client.sendAsync(SearchItemSegments(userId: String, searchQuery: String, count: Long,
    // optional parameters:
    scenario: String,
    cascadeCreate: Boolean,
    filter: String,
    booster: String,
    logic: Logic
  )
)

result.onSuccess { response: SearchResponse ->
    // Handle response
}.onFailure { exception -> // ApiException
    // Handle exception
}

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.SearchItemSegments(userId, searchQuery, count, {
  // optional parameters:
  'scenario': <string>,
  'cascadeCreate': <boolean>,
  'filter': <string>,
  'booster': <string>,
  'logic': <string / Object>
}))
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(SearchItemSegments(user_id, search_query, count,
    # optional parameters:
    scenario=<string>,
    cascade_create=<boolean>,
    filter=<string>,
    booster=<string>,
    logic=<string / dict>
  )
)

Copy

Initialization

result = client.send(SearchItemSegments.new(userId, searchQuery, count, {
    # optional parameters:
    :scenario => <string>,
    :cascade_create => <boolean>,
    :filter => <string>,
    :booster => <string>,
    :logic => <string / Hash>
  })
)

Copy

Initialization

SearchResponse result = client.send(new SearchItemSegments(String userId, String searchQuery, long count)
  .setScenario(String scenario)
  .setCascadeCreate(boolean cascadeCreate)
  .setFilter(String filter)
  .setBooster(String booster)
  .setLogic(Logic logic)
);

Copy

Initialization

<?php
$result = $client->send(new SearchItemSegments($user_id, $search_query, $count, [
    // optional parameters:
    'scenario' => <string>,
    'cascadeCreate' => <boolean>,
    'filter' => <string>,
    'booster' => <string>,
    'logic' => <string / array (map)>
  ])
);
?>

Copy

Initialization

SearchResponse result = client.Send(SearchItemSegments(string userId, string searchQuery, long count,
    // optional parameters:
    scenario: <string>,
    cascadeCreate: <bool>,
    filter: <string>,
    booster: <string>,
    logic: <Logic>
  )
);

Copy

Initialization

request := client.NewSearchItemSegments(userId string, searchQuery string, count int)    
    // optional parameters:
    .SetScenario(scenario string)
    .SetCascadeCreate(cascadeCreate bool)
    .SetFilter(filter string)
    .SetBooster(booster string)
    .SetLogic(logic bindings.Logic)


result, err := request.Send() // result is of the type bindings.SearchResponse

Copy

GET /{databaseId}/search/users/{userId}/item-segments/?searchQuery=<string>
&count=<integer>
&scenario=<string>
&cascadeCreate=<boolean>
&filter=<string>
&booster=<string>
&logic=<string / Object>

Since version

4.1.0

Parameters

databaseId

string

Located in: path

Required: Yes

Since version: 4.1.0

ID of your database.

userId

string

Located in: path

Required: Yes

Since version: 4.1.0

ID of the user for whom personalized search will be performed.

searchQuery

string

Located in: query

Required: Yes

Since version: 4.1.0

Search query provided by the user. It is used for the full-text search.

count

integer

Located in: query

Required: Yes

Since version: 4.1.0

Number of segments to be returned (N for the top-N results).

scenario

string

Located in: query

Required: No

Since version: 4.1.0

Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing".

You can set various settings to the scenario in the Admin UI. You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs.

The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios.

cascadeCreate

boolean

Located in: query

Required: No

Since version: 4.1.0

If the user does not exist in the database, returns a list of non-personalized recommendations and creates the user in the database. This allows, for example, rotations in the following recommendations for that user, as the user will be already known to the system.

filter

string

Located in: query

Required: No

Since version: 4.1.0

Boolean-returning ReQL expression which allows you to filter recommended segments based on the segmentationId.

booster

string

Located in: query

Required: No

Since version: 4.1.0

Number-returning ReQL expression which allows you to boost recommendation rate of some segments based on the segmentationId.

logic

string

object

Located in: query

Required: No

Since version: 4.1.0

Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. See this section for a list of available logics and other details.

The difference between logic and scenario is that logic specifies mainly behavior, while scenario specifies the place where recommendations are shown to the users.

Logic can also be set to a scenario in the Admin UI.

Responses

200

successful operation

{
  "recommId": "7acdc8b5-f731-44f8-b522-72625044666f",
  "recomms": [
    {
      "id": "cell phones"
    },
    {
      "id": "cell phone accessories"
    }
  ],
  "numberNextRecommsCalls": 0
}

400

userId does not match ^[a-zA-Z0-9_-:@.]+$, count is not a positive integer, searchQuery is not provided, filter or booster is not valid ReQL expressions, filter expression does not return boolean, booster does not return double or integer.

404

userId not found in the database and cascadeCreate is false. If there is no additional info in the JSON response, you probably have an error in your URL.

Synonyms

Define that some words or phrases should be considered equal by the full-text search engine.

post

Add Search Synonym

Adds a new synonym for the Search items.

When the term is used in the search query, the synonym is also used for the full-text search. Unless oneWay=true, it works also in the opposite way (synonym -> term).

An example of a synonym can be science fiction for the term sci-fi.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.AddSearchSynonym(term, synonym, {
  // optional parameters:
  'oneWay': <boolean>
}))
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(AddSearchSynonym(term, synonym,
    # optional parameters:
    one_way=<boolean>
  )
)

Copy

Initialization

result = client.send(AddSearchSynonym.new(term, synonym, {
    # optional parameters:
    :one_way => <boolean>
  })
)

Copy

Initialization

SearchSynonym result = client.send(new AddSearchSynonym(String term, String synonym)
  .setOneWay(boolean oneWay)
);

Copy

Initialization

<?php
$result = $client->send(new AddSearchSynonym($term, $synonym, [
    // optional parameters:
    'oneWay' => <boolean>
  ])
);
?>

Copy

Initialization

SearchSynonym result = client.Send(AddSearchSynonym(string term, string synonym,
    // optional parameters:
    oneWay: <bool>
  )
);

Copy

Initialization

request := client.NewAddSearchSynonym(term string, synonym string)    
    // optional parameters:
    .SetOneWay(oneWay bool)


result, err := request.Send() // result is of the type bindings.SearchSynonym

Copy

POST /{databaseId}/synonyms/items/
Body (application/json):
{
  "term" => <string>,
  "synonym" => <string>,
  "oneWay" => <boolean>
}

Since version

3.2.0

Calls Limit Per Minute

1000

Parameters

databaseId

string

Located in: path

Required: Yes

Since version: 3.2.0

ID of your database.

term

string

Located in: body

Required: Yes

Since version: 3.2.0

A word to which the synonym is specified.

synonym

string

Located in: body

Required: Yes

Since version: 3.2.0

A word that should be considered equal to the term by the full-text search engine.

oneWay

boolean

Located in: body

Required: No

Since version: 3.2.0

If set to true, only term -> synonym is considered. If set to false, also synonym -> term works.

Default: false.

Responses

201

Successful operation. Returns data about the added synonym (including id).

{
  "id": "cc198c86-e015-bb74-b5f4-8f996fd26736",
  "term": "sci-fi",
  "synonym": "science fiction",
  "oneWay": false
}

400

Missing a field, or a field has a wrong type.

409

synonym and term pair already exists in the database. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.

get

List Search Synonyms

Gives the list of synonyms defined in the database.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ListSearchSynonyms({
  // optional parameters:
  'count': <integer>,
  'offset': <integer>
}))
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(ListSearchSynonyms(
    # optional parameters:
    count=<integer>,
    offset=<integer>
  )
)

Copy

Initialization

result = client.send(ListSearchSynonyms.new({
    # optional parameters:
    :count => <integer>,
    :offset => <integer>
  })
)

Copy

Initialization

ListSearchSynonymsResponse result = client.send(new ListSearchSynonyms()
  .setCount(long count)
  .setOffset(long offset)
);

Copy

Initialization

<?php
$result = $client->send(new ListSearchSynonyms([
    // optional parameters:
    'count' => <integer>,
    'offset' => <integer>
  ])
);
?>

Copy

Initialization

ListSearchSynonymsResponse result = client.Send(ListSearchSynonyms(
    // optional parameters:
    count: <long>,
    offset: <long>
  )
);

Copy

Initialization

request := client.NewListSearchSynonyms()    
    // optional parameters:
    .SetCount(count int)
    .SetOffset(offset int)


result, err := request.Send() // result is of the type bindings.ListSearchSynonymsResponse

Copy

GET /{databaseId}/synonyms/items/?count=<integer>
&offset=<integer>

Calls Limit Per Minute

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

count

integer

Located in: query

Required: No

The number of synonyms to be listed.

offset

integer

Located in: query

Required: No

Specifies the number of synonyms to skip (ordered by term).

Responses

200

Successful operation.

{
  "synonyms": [
    {
      "id": "cc198c86-e015-bb74-b5f4-8f996fd26736",
      "term": "sci-fi",
      "synonym": "science fiction",
      "oneWay": false
    },
    {
      "id": "33bef0e5-f6ee-ac04-8b80-7ba8ece1fe63",
      "term": "sitcom",
      "synonym": "situation comedy",
      "oneWay": false
    }
  ]
}

delete

Delete All Search Synonyms

Deletes all synonyms defined in the database.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.DeleteAllSearchSynonyms());

Copy

Initialization

client.send(DeleteAllSearchSynonyms())

Copy

Initialization

client.send(DeleteAllSearchSynonyms.new())

Copy

Initialization

client.send(new DeleteAllSearchSynonyms());

Copy

Initialization

<?php
$client->send(new DeleteAllSearchSynonyms());
?>

Copy

Initialization

client.Send(DeleteAllSearchSynonyms());

Copy

Initialization

request := client.NewDeleteAllSearchSynonyms()

_, err := request.Send()

Copy

DELETE /{databaseId}/synonyms/items/

Calls Limit Per Minute

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

Responses

200

Successful operation.

delete

Delete Search Synonym

Deletes synonym of the given id. This synonym is no longer taken into account in the Search items.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.DeleteSearchSynonym(id));

Copy

Initialization

client.send(DeleteSearchSynonym(id))

Copy

Initialization

client.send(DeleteSearchSynonym.new(id))

Copy

Initialization

client.send(new DeleteSearchSynonym(String id));

Copy

Initialization

<?php
$client->send(new DeleteSearchSynonym($id));
?>

Copy

Initialization

client.Send(DeleteSearchSynonym(string id));

Copy

Initialization

request := client.NewDeleteSearchSynonym(id string)

_, err := request.Send()

Copy

DELETE /{databaseId}/synonyms/items/{id}

Calls Limit Per Minute

1000

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

string

Located in: path

Required: Yes

ID of the synonym that should be deleted.

Responses

200

Successful operation.

404

Synonym with the given id does not exist.

Series

Items in the catalog may be organized into series, expressing an explicit, known ordering of items, if there is any. Typical examples of series may be consecutive TV show episodes, book titles, etc.

Each item may be added to zero or more series, and a series may also be added into another series, resulting in a "meta-series". This may be useful for modeling ordered seasons of a TV show that has the episodes in each season themselves ordered.

Series definition

Methods for managing series - creating, listing, and deleting them.

put

Add Series

Creates a new series in the database.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.AddSeries(seriesId));

Copy

Initialization

client.send(AddSeries(series_id))

Copy

Initialization

client.send(AddSeries.new(seriesId))

Copy

Initialization

client.send(new AddSeries(String seriesId));

Copy

Initialization

<?php
$client->send(new AddSeries($series_id));
?>

Copy

Initialization

client.Send(AddSeries(string seriesId));

Copy

Initialization

request := client.NewAddSeries(seriesId string)

_, err := request.Send()

Copy

PUT /{databaseId}/series/{seriesId}

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

seriesId

string

Located in: path

Required: Yes

ID of the series to be created.

Responses

201

Successful operation.

400

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

409

Series of the given seriesId is already present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.

delete

Delete Series

Deletes the series of the given seriesId from the database.

Deleting a series will only delete assignment of items to it, not the items themselves!

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.DeleteSeries(seriesId));

Copy

Initialization

client.send(DeleteSeries(series_id))

Copy

Initialization

client.send(DeleteSeries.new(seriesId))

Copy

Initialization

client.send(new DeleteSeries(String seriesId));

Copy

Initialization

<?php
$client->send(new DeleteSeries($series_id));
?>

Copy

Initialization

client.Send(DeleteSeries(string seriesId));

Copy

Initialization

request := client.NewDeleteSeries(seriesId string)

_, err := request.Send()

Copy

DELETE /{databaseId}/series/{seriesId}

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

seriesId

string

Located in: path

Required: Yes

ID of the series to be deleted.

Responses

200

Successful operation.

400

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

404

Series of the given seriesId is not present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been deleted from the database since the series was already not present. If there is no additional info in the JSON response, you probably have an error in your URL.

get

List Series

Gets the list of all the series currently present in the database.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ListSeries())
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(ListSeries())

Copy

Initialization

result = client.send(ListSeries.new())

Copy

Initialization

Series[] result = client.send(new ListSeries());

Copy

Initialization

<?php
$result = $client->send(new ListSeries());
?>

Copy

Initialization

IEnumerable<Series> result = client.Send(ListSeries());

Copy

Initialization

request := client.NewListSeries()

result, err := request.Send() // result is of the type []bindings.Series

Copy

GET /{databaseId}/series/list/

Calls Limit Per Minute

100

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

Responses

200

Successful operation.

[
  "series-1",
  "series-2",
  "series-3"
]

404

Invalid URL.

Series items

Methods for adding items (or even series themselves) to series.

get

List Series Items

Lists all the items present in the given series, sorted according to their time index values.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ListSeriesItems(seriesId))
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(ListSeriesItems(series_id))

Copy

Initialization

result = client.send(ListSeriesItems.new(seriesId))

Copy

Initialization

SeriesItem[] result = client.send(new ListSeriesItems(String seriesId));

Copy

Initialization

<?php
$result = $client->send(new ListSeriesItems($series_id));
?>

Copy

Initialization

IEnumerable<SeriesItem> result = client.Send(ListSeriesItems(string seriesId));

Copy

Initialization

request := client.NewListSeriesItems(seriesId string)

result, err := request.Send() // result is of the type []bindings.SeriesItem

Copy

GET /{databaseId}/series/{seriesId}/items/

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

seriesId

string

Located in: path

Required: Yes

ID of the series whose items are to be listed.

Responses

200

Successful operation.

[
  {
    "itemType": "item",
    "itemId": "item-x",
    "time": 1
  },
  {
    "itemType": "item",
    "itemId": "item-y",
    "time": 2
  },
  {
    "itemType": "item",
    "itemId": "item-z",
    "time": 3
  }
]

400

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

404

Series of the given seriesId is not present in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

post

Insert to Series

Inserts an existing item/series into a series of the given seriesId at a position determined by time.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.InsertToSeries(seriesId, itemType, itemId, time, {
  // optional parameters:
  'cascadeCreate': <boolean>
}));

Copy

Initialization

client.send(InsertToSeries(series_id, item_type, item_id, time,
    # optional parameters:
    cascade_create=<boolean>
  )
)

Copy

Initialization

client.send(InsertToSeries.new(seriesId, itemType, itemId, time, {
    # optional parameters:
    :cascade_create => <boolean>
  })
)

Copy

Initialization

client.send(new InsertToSeries(String seriesId, String itemType, String itemId, double time)
  .setCascadeCreate(boolean cascadeCreate)
);

Copy

Initialization

<?php
$client->send(new InsertToSeries($series_id, $item_type, $item_id, $time, [
    // optional parameters:
    'cascadeCreate' => <boolean>
  ])
);
?>

Copy

Initialization

client.Send(InsertToSeries(string seriesId, string itemType, string itemId, double time,
    // optional parameters:
    cascadeCreate: <bool>
  )
);

Copy

Initialization

request := client.NewInsertToSeries(seriesId string, itemType string, itemId string, time float64)    
    // optional parameters:
    .SetCascadeCreate(cascadeCreate bool)


_, err := request.Send()

Copy

POST /{databaseId}/series/{seriesId}/items/
Body (application/json):
{
  "itemType" => <string>,
  "itemId" => <string>,
  "time" => <number>,
  "cascadeCreate" => <boolean>
}

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

seriesId

string

Located in: path

Required: Yes

ID of the series to be inserted into.

itemType

string

Located in: body

Required: Yes

item iff the regular item from the catalog is to be inserted, series iff series is inserted as the item.

itemId

string

Located in: body

Required: Yes

ID of the item iff itemType is item. ID of the series iff itemType is series.

time

number

Located in: body

Required: Yes

Time index used for sorting items in the series. According to time, items are sorted within series in ascending order. In the example of TV show episodes, the episode number is a natural choice to be passed as time.

cascadeCreate

boolean

Located in: body

Required: No

Indicates that any non-existing entity specified within the request should be created (as if corresponding PUT requests were invoked). This concerns both the seriesId and the itemId. If cascadeCreate is set to true, the behavior also depends on the itemType. Either item or series may be created if not present in the database.

Responses

200

Successful operation.

400

seriesId or itemId does not match ^[a-zA-Z0-9_-:@.]+$, or itemType∉{item,series}, or time is not a real number.

404

Series of the given seriesId is not present in the database. Item of the given itemId is not present in the database if itemType is item. Series of the given itemId is not present in the database if itemType is series. If there is no additional info in the JSON response, you probably have an error in your URL.

409

A series item of the exact same (itemType, itemId, time) is already present in the series of seriesId. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.

delete

Remove from Series

Removes an existing series item from the series.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.RemoveFromSeries(seriesId, itemType, itemId, time));

Copy

Initialization

client.send(RemoveFromSeries(series_id, item_type, item_id, time))

Copy

Initialization

client.send(RemoveFromSeries.new(seriesId, itemType, itemId, time))

Copy

Initialization

client.send(new RemoveFromSeries(String seriesId, String itemType, String itemId, double time));

Copy

Initialization

<?php
$client->send(new RemoveFromSeries($series_id, $item_type, $item_id, $time));
?>

Copy

Initialization

client.Send(RemoveFromSeries(string seriesId, string itemType, string itemId, double time));

Copy

Initialization

request := client.NewRemoveFromSeries(seriesId string, itemType string, itemId string, time float64)

_, err := request.Send()

Copy

DELETE /{databaseId}/series/{seriesId}/items/?itemType=<string>
&itemId=<string>
&time=<number>

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

seriesId

string

Located in: path

Required: Yes

ID of the series from which a series item is to be removed.

itemType

string

Located in: query

Required: Yes

Type of the item to be removed.

itemId

string

Located in: query

Required: Yes

ID of the item iff itemType is item. ID of the series iff itemType is series.

time

number

Located in: query

Required: Yes

Time index of the item to be removed.

Responses

200

Successful operation.

400

The seriesId or itemId does not match ^[a-zA-Z0-9_-:@.]+$, or itemType∉{item, series}, or time is not a real number.

404

Series of the given seriesId is not present in the database. Series item given by triplet (itemType, itemId, time) is not present in series of seriesId. If there is no additional info in the JSON response, you probably have an error in your URL.

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

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.CreatePropertyBasedSegmentation(segmentationId, sourceType, propertyName, {
  // optional parameters:
  'title': <string>,
  'description': <string>
}));

Copy

Initialization

client.send(CreatePropertyBasedSegmentation(segmentation_id, source_type, property_name,
    # optional parameters:
    title=<string>,
    description=<string>
  )
)

Copy

Initialization

client.send(CreatePropertyBasedSegmentation.new(segmentationId, sourceType, propertyName, {
    # optional parameters:
    :title => <string>,
    :description => <string>
  })
)

Copy

Initialization

client.send(new CreatePropertyBasedSegmentation(String segmentationId, String sourceType, String propertyName)
  .setTitle(String title)
  .setDescription(String description)
);

Copy

Initialization

<?php
$client->send(new CreatePropertyBasedSegmentation($segmentation_id, $source_type, $property_name, [
    // optional parameters:
    'title' => <string>,
    'description' => <string>
  ])
);
?>

Copy

Initialization

client.Send(CreatePropertyBasedSegmentation(string segmentationId, string sourceType, string propertyName,
    // optional parameters:
    title: <string>,
    description: <string>
  )
);

Copy

Initialization

request := client.NewCreatePropertyBasedSegmentation(segmentationId string, sourceType string, propertyName string)    
    // optional parameters:
    .SetTitle(title string)
    .SetDescription(description string)


_, err := request.Send()

Copy

PUT /{databaseId}/segmentations/property-based/{segmentationId}
Body (application/json):
{
  "sourceType" => <string>,
  "propertyName" => <string>,
  "title" => <string>,
  "description" => <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

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.UpdatePropertyBasedSegmentation(segmentationId, {
  // optional parameters:
  'propertyName': <string>,
  'title': <string>,
  'description': <string>
}));

Copy

Initialization

client.send(UpdatePropertyBasedSegmentation(segmentation_id,
    # optional parameters:
    property_name=<string>,
    title=<string>,
    description=<string>
  )
)

Copy

Initialization

client.send(UpdatePropertyBasedSegmentation.new(segmentationId, {
    # optional parameters:
    :property_name => <string>,
    :title => <string>,
    :description => <string>
  })
)

Copy

Initialization

client.send(new UpdatePropertyBasedSegmentation(String segmentationId)
  .setPropertyName(String propertyName)
  .setTitle(String title)
  .setDescription(String description)
);

Copy

Initialization

<?php
$client->send(new UpdatePropertyBasedSegmentation($segmentation_id, [
    // optional parameters:
    'propertyName' => <string>,
    'title' => <string>,
    'description' => <string>
  ])
);
?>

Copy

Initialization

client.Send(UpdatePropertyBasedSegmentation(string segmentationId,
    // optional parameters:
    propertyName: <string>,
    title: <string>,
    description: <string>
  )
);

Copy

Initialization

request := client.NewUpdatePropertyBasedSegmentation(segmentationId string)    
    // optional parameters:
    .SetPropertyName(propertyName string)
    .SetTitle(title string)
    .SetDescription(description string)


_, err := request.Send()

Copy

POST /{databaseId}/segmentations/property-based/{segmentationId}
Body (application/json):
{
  "propertyName" => <string>,
  "title" => <string>,
  "description" => <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

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.CreateManualReqlSegmentation(segmentationId, sourceType, {
  // optional parameters:
  'title': <string>,
  'description': <string>
}));

Copy

Initialization

client.send(CreateManualReqlSegmentation(segmentation_id, source_type,
    # optional parameters:
    title=<string>,
    description=<string>
  )
)

Copy

Initialization

client.send(CreateManualReqlSegmentation.new(segmentationId, sourceType, {
    # optional parameters:
    :title => <string>,
    :description => <string>
  })
)

Copy

Initialization

client.send(new CreateManualReqlSegmentation(String segmentationId, String sourceType)
  .setTitle(String title)
  .setDescription(String description)
);

Copy

Initialization

<?php
$client->send(new CreateManualReqlSegmentation($segmentation_id, $source_type, [
    // optional parameters:
    'title' => <string>,
    'description' => <string>
  ])
);
?>

Copy

Initialization

client.Send(CreateManualReqlSegmentation(string segmentationId, string sourceType,
    // optional parameters:
    title: <string>,
    description: <string>
  )
);

Copy

Initialization

request := client.NewCreateManualReqlSegmentation(segmentationId string, sourceType string)    
    // optional parameters:
    .SetTitle(title string)
    .SetDescription(description string)


_, err := request.Send()

Copy

PUT /{databaseId}/segmentations/manual-reql/{segmentationId}
Body (application/json):
{
  "sourceType" => <string>,
  "title" => <string>,
  "description" => <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

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))

Copy

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

response = client.send(batch)

Copy

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

BatchResponse[] responses = client.send(new Batch(requests));

Copy

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

client.send(batch,
  (err, resp) => {
    console.log(err);
    console.log(resp);
  }
);

Copy


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

  $responses = $client->send(new Reqs\Batch($reqs));
?>

Copy



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

BatchResponse batchResponse = await client.SendAsync(new Batch(requests));

Copy


import (
  "github.com/recombee/go-api-client/v4/recombee"
  "github.com/recombee/go-api-client/v4/recombee/requests"
)

reqs := []requests.Request{
  // Assuming methods similar to the Java SDK exist in the Go SDK
  client.NewCreateManualReqlSegmentation("homepage-rows", "items"),
  client.NewAddManualReqlSegment("homepage-rows", "made-in-us", "'country' == \"US\""),
  client.NewAddManualReqlSegment("homepage-rows", "short-laughs", "\"Comedy\" in 'genres' and 'runtime' < 30"),
}

// Send the batch request
batchRes, err := client.NewBatch(reqs).Send()

post

Update Manual ReQL Segmentation

Update an existing Segmentation.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.UpdateManualReqlSegmentation(segmentationId, {
  // optional parameters:
  'title': <string>,
  'description': <string>
}));

Copy

Initialization

client.send(UpdateManualReqlSegmentation(segmentation_id,
    # optional parameters:
    title=<string>,
    description=<string>
  )
)

Copy

Initialization

client.send(UpdateManualReqlSegmentation.new(segmentationId, {
    # optional parameters:
    :title => <string>,
    :description => <string>
  })
)

Copy

Initialization

client.send(new UpdateManualReqlSegmentation(String segmentationId)
  .setTitle(String title)
  .setDescription(String description)
);

Copy

Initialization

<?php
$client->send(new UpdateManualReqlSegmentation($segmentation_id, [
    // optional parameters:
    'title' => <string>,
    'description' => <string>
  ])
);
?>

Copy

Initialization

client.Send(UpdateManualReqlSegmentation(string segmentationId,
    // optional parameters:
    title: <string>,
    description: <string>
  )
);

Copy

Initialization

request := client.NewUpdateManualReqlSegmentation(segmentationId string)    
    // optional parameters:
    .SetTitle(title string)
    .SetDescription(description string)


_, err := request.Send()

Copy

POST /{databaseId}/segmentations/manual-reql/{segmentationId}
Body (application/json):
{
  "title" => <string>,
  "description" => <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

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.AddManualReqlSegment(segmentationId, segmentId, filter, {
  // optional parameters:
  'title': <string>
}));

Copy

Initialization

client.send(AddManualReqlSegment(segmentation_id, segment_id, filter,
    # optional parameters:
    title=<string>
  )
)

Copy

Initialization

client.send(AddManualReqlSegment.new(segmentationId, segmentId, filter, {
    # optional parameters:
    :title => <string>
  })
)

Copy

Initialization

client.send(new AddManualReqlSegment(String segmentationId, String segmentId, String filter)
  .setTitle(String title)
);

Copy

Initialization

<?php
$client->send(new AddManualReqlSegment($segmentation_id, $segment_id, $filter, [
    // optional parameters:
    'title' => <string>
  ])
);
?>

Copy

Initialization

client.Send(AddManualReqlSegment(string segmentationId, string segmentId, string filter,
    // optional parameters:
    title: <string>
  )
);

Copy

Initialization

request := client.NewAddManualReqlSegment(segmentationId string, segmentId string, filter string)    
    // optional parameters:
    .SetTitle(title string)


_, err := request.Send()

Copy

PUT /{databaseId}/segmentations/manual-reql/{segmentationId}/segments/{segmentId}
Body (application/json):
{
  "filter" => <string>,
  "title" => <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

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.UpdateManualReqlSegment(segmentationId, segmentId, filter, {
  // optional parameters:
  'title': <string>
}));

Copy

Initialization

client.send(UpdateManualReqlSegment(segmentation_id, segment_id, filter,
    # optional parameters:
    title=<string>
  )
)

Copy

Initialization

client.send(UpdateManualReqlSegment.new(segmentationId, segmentId, filter, {
    # optional parameters:
    :title => <string>
  })
)

Copy

Initialization

client.send(new UpdateManualReqlSegment(String segmentationId, String segmentId, String filter)
  .setTitle(String title)
);

Copy

Initialization

<?php
$client->send(new UpdateManualReqlSegment($segmentation_id, $segment_id, $filter, [
    // optional parameters:
    'title' => <string>
  ])
);
?>

Copy

Initialization

client.Send(UpdateManualReqlSegment(string segmentationId, string segmentId, string filter,
    // optional parameters:
    title: <string>
  )
);

Copy

Initialization

request := client.NewUpdateManualReqlSegment(segmentationId string, segmentId string, filter string)    
    // optional parameters:
    .SetTitle(title string)


_, err := request.Send()

Copy

POST /{databaseId}/segmentations/manual-reql/{segmentationId}/segments/{segmentId}
Body (application/json):
{
  "filter" => <string>,
  "title" => <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

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

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

Copy

Initialization

client.send(DeleteManualReqlSegment(segmentation_id, segment_id))

Copy

Initialization

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

Copy

Initialization

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

Copy

Initialization

<?php
$client->send(new DeleteManualReqlSegment($segmentation_id, $segment_id));
?>

Copy

Initialization

client.Send(DeleteManualReqlSegment(string segmentationId, string segmentId));

Copy

Initialization

request := client.NewDeleteManualReqlSegment(segmentationId string, segmentId string)

_, err := request.Send()

Copy

DELETE /{databaseId}/segmentations/manual-reql/{segmentationId}/segments/{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

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.CreateAutoReqlSegmentation(segmentationId, sourceType, expression, {
  // optional parameters:
  'title': <string>,
  'description': <string>
}));

Copy

Initialization

client.send(CreateAutoReqlSegmentation(segmentation_id, source_type, expression,
    # optional parameters:
    title=<string>,
    description=<string>
  )
)

Copy

Initialization

client.send(CreateAutoReqlSegmentation.new(segmentationId, sourceType, expression, {
    # optional parameters:
    :title => <string>,
    :description => <string>
  })
)

Copy

Initialization

client.send(new CreateAutoReqlSegmentation(String segmentationId, String sourceType, String expression)
  .setTitle(String title)
  .setDescription(String description)
);

Copy

Initialization

<?php
$client->send(new CreateAutoReqlSegmentation($segmentation_id, $source_type, $expression, [
    // optional parameters:
    'title' => <string>,
    'description' => <string>
  ])
);
?>

Copy

Initialization

client.Send(CreateAutoReqlSegmentation(string segmentationId, string sourceType, string expression,
    // optional parameters:
    title: <string>,
    description: <string>
  )
);

Copy

Initialization

request := client.NewCreateAutoReqlSegmentation(segmentationId string, sourceType string, expression string)    
    // optional parameters:
    .SetTitle(title string)
    .SetDescription(description string)


_, err := request.Send()

Copy

PUT /{databaseId}/segmentations/auto-reql/{segmentationId}
Body (application/json):
{
  "sourceType" => <string>,
  "expression" => <string>,
  "title" => <string>,
  "description" => <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

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)

Copy

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

response = client.send(req)

Copy

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

client.send(req);

Copy

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

const response = client.send(req);

Copy

<?php

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

  $response = $client->send($req);

?>

Copy

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

client.Send(req);

Copy

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

_, err = req.Send()

post

Update Auto ReQL Segmentation

Update an existing Segmentation.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.UpdateAutoReqlSegmentation(segmentationId, {
  // optional parameters:
  'expression': <string>,
  'title': <string>,
  'description': <string>
}));

Copy

Initialization

client.send(UpdateAutoReqlSegmentation(segmentation_id,
    # optional parameters:
    expression=<string>,
    title=<string>,
    description=<string>
  )
)

Copy

Initialization

client.send(UpdateAutoReqlSegmentation.new(segmentationId, {
    # optional parameters:
    :expression => <string>,
    :title => <string>,
    :description => <string>
  })
)

Copy

Initialization

client.send(new UpdateAutoReqlSegmentation(String segmentationId)
  .setExpression(String expression)
  .setTitle(String title)
  .setDescription(String description)
);

Copy

Initialization

<?php
$client->send(new UpdateAutoReqlSegmentation($segmentation_id, [
    // optional parameters:
    'expression' => <string>,
    'title' => <string>,
    'description' => <string>
  ])
);
?>

Copy

Initialization

client.Send(UpdateAutoReqlSegmentation(string segmentationId,
    // optional parameters:
    expression: <string>,
    title: <string>,
    description: <string>
  )
);

Copy

Initialization

request := client.NewUpdateAutoReqlSegmentation(segmentationId string)    
    // optional parameters:
    .SetExpression(expression string)
    .SetTitle(title string)
    .SetDescription(description string)


_, err := request.Send()

Copy

POST /{databaseId}/segmentations/auto-reql/{segmentationId}
Body (application/json):
{
  "expression" => <string>,
  "title" => <string>,
  "description" => <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

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ListSegmentations(sourceType))
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(ListSegmentations(source_type))

Copy

Initialization

result = client.send(ListSegmentations.new(sourceType))

Copy

Initialization

ListSegmentationsResponse result = client.send(new ListSegmentations(String sourceType));

Copy

Initialization

<?php
$result = $client->send(new ListSegmentations($source_type));
?>

Copy

Initialization

ListSegmentationsResponse result = client.Send(ListSegmentations(string sourceType));

Copy

Initialization

request := client.NewListSegmentations(sourceType string)

result, err := request.Send() // result is of the type bindings.ListSegmentationsResponse

Copy

GET /{databaseId}/segmentations/list/?sourceType=<string>

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

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.GetSegmentation(segmentationId))
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(GetSegmentation(segmentation_id))

Copy

Initialization

result = client.send(GetSegmentation.new(segmentationId))

Copy

Initialization

Segmentation result = client.send(new GetSegmentation(String segmentationId));

Copy

Initialization

<?php
$result = $client->send(new GetSegmentation($segmentation_id));
?>

Copy

Initialization

Segmentation result = client.Send(GetSegmentation(string segmentationId));

Copy

Initialization

request := client.NewGetSegmentation(segmentationId string)

result, err := request.Send() // result is of the type bindings.Segmentation

Copy

GET /{databaseId}/segmentations/list/{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

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

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

Copy

Initialization

client.send(DeleteSegmentation(segmentation_id))

Copy

Initialization

client.send(DeleteSegmentation.new(segmentationId))

Copy

Initialization

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

Copy

Initialization

<?php
$client->send(new DeleteSegmentation($segmentation_id));
?>

Copy

Initialization

client.Send(DeleteSegmentation(string segmentationId));

Copy

Initialization

request := client.NewDeleteSegmentation(segmentationId string)

_, err := request.Send()

Copy

DELETE /{databaseId}/segmentations/{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.

Miscellaneous

delete

Reset Database

Completely erases all your data, including items, item properties, series, user database, purchases, ratings, detail views, and bookmarks. Make sure the request is never executed in the production environment! Resetting your database is irreversible.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ResetDatabase());

Copy

Initialization

client.send(ResetDatabase())

Copy

Initialization

client.send(ResetDatabase.new())

Copy

Initialization

client.send(new ResetDatabase());

Copy

Initialization

<?php
$client->send(new ResetDatabase());
?>

Copy

Initialization

client.Send(ResetDatabase());

Copy

Initialization

request := client.NewResetDatabase()

_, err := request.Send()

Copy

DELETE /{databaseId}/

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

Responses

200

Successful operation.

post

Batch

Allowed on Client-Side

Batch processing allows you to submit arbitrary sequence of requests within a single HTTPS request.

Any type of request from the above documentation may be used in the Batch, and the Batch may combine different types of requests arbitrarily as well.

Using Batch requests is beneficial for example, when synchronizing the catalog of items or uploading historical interaction data, as sending the data in Batch is considerably faster than sending the individual requests (thanks to optimizations and reducing network and HTTPS overhead).

Javascript Kotlin Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new recombee.Batch(requests, {
  // optional parameters:
  'distinctRecomms': <boolean>
})).then(function(res) {
  // handle response 
});

Copy

Initialization

val result = client.sendAsync(Batch(requests: List<Request>,
    // optional parameters:
    distinctRecomms: Boolean
  )
)

result.onSuccess { response: List<BatchResponse> ->
    // Handle response
}.onFailure { exception -> // ApiException
    // Handle exception
}

Copy

Initialization

var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.Batch(requests, {
  // optional parameters:
  'distinctRecomms': <boolean>
}))
.then((response) => {
    //handle response
})
.catch((error) => {
    //handle error
});

Copy

Initialization

result = client.send(Batch(requests,
    # optional parameters:
    distinct_recomms=<boolean>
  )
)

Copy

Initialization

result = client.send(Batch.new(requests, {
    # optional parameters:
    :distinct_recomms => <boolean>
  })
)

Copy

Initialization

BatchResponse[] result = client.send(new Batch(Request[] requests)
  .setDistinctRecomms(boolean distinctRecomms)
);

Copy

Initialization

<?php
$result = $client->send(new Batch($requests, [
    // optional parameters:
    'distinctRecomms' => <boolean>
  ])
);
?>

Copy

Initialization

IEnumerable<BatchResponse> result = client.Send(Batch(IEnumerable<Request> requests,
    // optional parameters:
    distinctRecomms: <bool>
  )
);

Copy

Initialization

request := client.NewBatch(reqs requests.Request[])    
    // optional parameters:
    .SetDistinctRecomms(distinctRecomms bool)


result, err := request.Send() // result is of the type []bindings.BatchResponse

Copy

POST /{databaseId}/batch/
Body (application/json):
{
  "requests" => <array>,
  "distinctRecomms" => <boolean>
}

Parameters

databaseId

string

Located in: path

Required: Yes

ID of your database.

requests

array

Located in: body

Required: Yes

JSON array containing the requests.

distinctRecomms

boolean

Located in: body

Required: No

Since version: 1.2.4

Makes all the recommended items for a certain user distinct among multiple recommendation requests in the batch.

Responses

200

Successful operation. There is an array with responses. The order of the responses in the array follows the order of the sent requests.

[
  {
    "code": 200,
    "json": "ok"
  },
  {
    "code": 200,
    "json": "ok"
  },
  {
    "code": 200,
    "json": {
      "recommId": "3f6ad2f2-a3f1-4ba1-a690-f4f01f76d4eb",
      "recomms": [
        {
          "id": "item-146"
        },
        {
          "id": "item-462"
        },
        {
          "id": "item-463"
        }
      ],
      "numberNextRecommsCalls": 0
    }
  }
]

400

Many possibilities, see the error description in the result JSON. Examples: invalid or missing Content-type (not application/json), request body is not a valid JSON, request JSON does not have the prescribed structure.

404

There is at least one request in the batch with an invalid (non-existing) URL. In such a case, the batch as a whole is not executed and you'll get HTTP 404, because the batch is apriori erroneous.

413

Too large batch (containing more than 10,000 requests in case of a server side request).

Examples

Sending multiple requests in a single Batch request

Batch can encapsulate requests of various types.

Javascript Kotlin Python Ruby Java Node.js PHP C#Go REST

Copy

let reqs = [new recombee.AddDetailView(userId, itemId),
            new recombee.RecommendItemsToUser(userId, 5, {scenario: 'just_for_you'}),
            new recombee.RecommendItemsToItem(itemId, userId, 5, {scenario: 'similar_products'})
           ];

client.send(new recombee.Batch(reqs))
.then((responses) => { ... })
.catch((error) => { ... } );

Copy

val requests = listOf(
    AddDetailView(
        userId = "userId",
        itemId = "itemId",
        cascadeCreate = true
    ),

    RecommendItemsToUser(
        userId = "userId",
        count = 5,
        scenario = "just_for_you",
        cascadeCreate = true
    ),

    RecommendItemsToItem(
        itemId = "itemId",
        targetUserId = "userId",
        count = 5,
        scenario = "similar_products",
        cascadeCreate = true
    ),
)

val responses = client.send(Batch(requests))

Copy

requests = [AddDetailView(user_id, item_id, cascade_create=True),
            RecommendItemsToUser(user_id, 5, scenario="just_for_you", cascade_create=True),
            RecommendItemsToItem(item_id, user_id, 5, scenario="similar_products", cascade_create=True),
            SetItemValues(item_id, {"price": 200, "category": "furniture"}, cascade_create=True)
           ]
responses = client.send(Batch(requests))

Copy

requests = [AddDetailView.new(user_id, item_id, {:cascade_create => true}),
            RecommendItemsToUser.new(user_id, 5, {:scenario => 'just_for_you', :cascade_create => true}),
            RecommendItemsToItem.new(item_id, user_id, 5, {:scenario => 'similar_products', :cascade_create => true}),
            SetItemValues(item_id, {"price" => 200, "category" => "furniture"}, {:cascade_create => true})
           ]
responses = client.send(Batch.new(requests))

Copy

Request[] requests = new Request[] {
  new AddDetailView(userId, itemId).setCascadeCreate(true),
  new RecommendItemsToUser(userId, 5).setScenario("just_for_you").setCascadeCreate(true),
  new RecommendItemsToItem(itemId, userId, 5).setScenario("similar_products").setCascadeCreate(true),
  new SetItemValues(itemId, new HashMap<String, Object>(){{put("price", 200); put("category", "furniture");}})
};

BatchResponse[] responses = client.send(new Batch(requests));

Copy

let reqs = [new rqs.AddDetailView(userId, itemId, {cascadeCreate: true}),
            new rqs.RecommendItemsToUser(userId, 5, {scenario: 'just_for_you', cascadeCreate: true}),
            new rqs.RecommendItemsToItem(itemId, userId, 5, {scenario: 'similar_products', cascadeCreate: true}),
            new rqs.SetItemValues(itemId, {price: 200, category: 'funiture'}, {cascadeCreate: true})
           ];

client.send(new rqs.Batch(reqs),
  (err, resp) => {
    console.log(err);
    console.log(resp);
  }
);

Copy

<?php
$reqs = [
            new Reqs\AddDetailView(userId, itemId, ['cascadeCreate' => true]),
            new Reqs\RecommendItemsToUser(userId, 5, ['scenario' => 'just_for_you', 'cascadeCreate' => true]),
            new Reqs\RecommendItemsToItem(userId, itemId, 5, ['scenario' => 'similar_products', 'cascadeCreate' => true]),
            new Reqs\SetItemValues(itemId, ['price' => 200, 'category' => 'furniture'], ['cascadeCreate' => true]),
        ];
$replies = $client->send(new Reqs\Batch($reqs));
?>

Copy

Request[] requests = new Request[] {
    new AddDetailView(userId, itemId, cascadeCreate: true),
    new RecommendItemsToUser(userId, 5, scenario: "just_for_you", cascadeCreate: true),
    new RecommendItemsToItem(itemId, userId, 5, scenario: "similar_products", cascadeCreate: true),
    new SetItemValues(itemId, new Dictionary<string, object>(){{"price", 200}, {"category", "furniture"}})
};

BatchResponse batchResponse = await client.SendAsync(new Batch(requests));

Copy


import (
  "github.com/recombee/go-api-client/v4/recombee"
  "github.com/recombee/go-api-client/v4/recombee/requests"
)

requestsBatch := []requests.Request{
  client.NewAddDetailView(userId, itemId).SetCascadeCreate(true),
  client.NewRecommendItemsToUser(userId, 5).SetScenario("just_for_you").SetCascadeCreate(true),
  client.NewRecommendItemsToItem(itemId, userId, 5).SetScenario("similar_products").SetCascadeCreate(true),
  client.NewSetItemValues(itemId, map[string]interface{}{
    "price":    200,
    "category": "furniture",
  }).SetCascadeCreate(true),
}

// Send batch request
batchRes, err := client.NewBatch(requestsBatch).Send()

Copy


# If you use the REST API directly, than the body of a batch request consists of a JSON object. 
# The individual requests are given as a JSON array associated with key *requests*. 
#
# In the array, each request is encoded as a JSON object containing the following fields:
#
# * method – required string with HTTP method of the request (one of PUT, POST, GET, DELETE, case insensitive),
# * path – required string with path of the request from the root of the database, excluding the query string,
# * params – optional (or required if also required by the request type) object containing values 
#            of the request's parameters (GET or POST, depending on the request type)
#
# The `params` property may be omitted if there are no attributes to be passed for the request;
# if some attributes are optional, you may or may not include them as in regular request,
#
# Example of executing three requests (setting the item values, adding a detail view,
#                                      and getting user based recommendation) in a batch:

  {
    "requests": [
      {
        "method": "POST",
        "path": "/items/item-24",
        "params": {
          "product_description": "4K TV with 3D feature",
          "categories":   ["Electronics", "Televisions"],
          "price_usd": 342,
          "!cascadeCreate": true
        }
      },
      {
        "method": "POST",
        "path": "/detailviews/",
        "params": {
          "userId": "user-123",
          "itemId": "item-x",
          "timestamp": 1404727253,
          "cascadeCreate": true
        }
      },
      {
        "method": "GET",
        "path": "/recomms/users/user-123/items/",
        "params": {
          "count": 3
        }
      }
    ]
  }

Checking the result of the individual requests

You should check that the requests in the Batch succeeded. A request can fail for example due to invalid parameters - the returned error mesage gives you a hint what went wrong.

Javascript Kotlin Python Ruby Java Node.js PHP C#Go

Copy

client.send(new recombee.Batch(reqs))
.then((responses) => {
    for (const response of responses) {

      if (response.code < 200 || response.code > 299) {
        // A request in the Batch did not succeed
        console.log(response);
      }

    }
})
.catch((error) => {
    //the whole Batch request failed
});

Copy

val result = client.sendAsync(Batch(requests))

result.onSuccess {batchResponses: List<BatchResponse> ->
    // Check individual requests
    batchResponses.forEach { response ->
        if (!response.successful) {
            // A request in the Batch did not succeed
            // response.getResponse() will throw corresponding ApiException
        }

    }
}.onFailure { exception -> // ApiException
    // The whole Batch failed
}

Copy

responses = client.send(Batch(requests))

for response in responses:

  if not (200 <= response["code"] < 300):
    # A request in the Batch did not succeed
    print(response)

Copy

responses = client.send(Batch.new(requests))

reponses.each do |reponse| 
  if response['code'] < 200 || response['code'] > 299
    # A request in the Batch did not succeed

    puts reponse
  end
end

Copy

// Send the Batch to the Recombee API
BatchResponse[] responses = client.send(batch);

// Check if the Batch was successful
for (BatchResponse response : responses) {
  if (!response.isSuccessful()) {
    // A request in the Batch did not succeed
    // response.getResponse() will throw corresponding ApiException
  }
}

Copy

client.send(new rqs.Batch(reqs))
.then((responses) => {

  for (const response of responses) {

    if (response.code < 200 || response.code > 299) {
      // A request in the Batch did not succeed
      console.log(response);
    }

  }
})
.catch((error) => {
    //the whole Batch request failed
});

Copy

<?php
  // Send the Batch to the Recombee API
  $responses = $client->send($batch);

  // Check if the Batch was successful
  foreach ($responses as $response) {
    if (200 < $response["code"] || $response["code"] >= 300) {
      // A request in the Batch did not succeed
      print($response);
    }
  }
?>

Copy

var responses = client.Send(batch);
for (int i = 0; i < responses.StatusCodes.Length; i++)
{
  if (((int)responses.StatusCodes[i]) < 200 || ((int)responses.StatusCodes[i]) >= 300)
  {
      // A request in the Batch did not succeed
      // Accessing responses[i] will throw corresponding ApiException
  }
}

Copy

batchRes, err := client.NewBatch(requestsBatch).Send()
if err != nil {
  fmt.Println(err)
  panic(err)
}

for i, resp := range batchRes {
  if resp.StatusCode < 200 || resp.StatusCode >= 300 {
    fmt.Printf("Request #%d failed with status code %d: %s\n", i, resp.StatusCode, resp.Error.ErrorMessage)
  }
}

Using distinctRecomms parameter to deduplicate results in multiple boxes

If you show multiple boxes with recommendations on a single page, you may want to ensure that the same item is not recommended in multiple boxes. You can achieve that by specifying distinctRecomms=true.

Javascript Kotlin Python Ruby Java Node.js PHP C#Go REST

Copy

const batchRequest = rqs.new Batch([
  new RecommendItemsToUser('user-id', 5, {scenario:'new_releases', cascadeCreate: true}),
  new RecommendItemsToUser('user-id', 5, {scenario:'just_for_you', cascadeCreate: true})
], {
  distinctRecomms: true
});

client.send(batchRequest)
.then((responses) => { ... })
.catch((error) => { ... } );

Copy

val requests = listOf(
    RecommendItemsToUser(userId = "userId", count = 5, scenario = "new_releases", cascadeCreate = true),
    RecommendItemsToUser(userId = "userId", count = 5, scenario = "just_for_you", cascadeCreate = true)
)

val result = client.sendAsync(Batch(requests=requests, distinctRecomms = true)

Copy

requests = [RecommendItemsToUser(user_id, 5, scenario="new_releases", cascade_create=True),
            RecommendItemsToUser(user_id, 5, scenario="just_for_you", cascade_create=True),]
responses = client.send(Batch(requests, distinct_recomms=True))

Copy

batch = Batch.new([
  RecommendItemsToUser.new(user_id, 5, scenario: "new_releases", cascade_create: true),
  RecommendItemsToUser.new(user_id, 5, scenario: "just_for_you", cascade_create: true),
], distinct_recomms: true)

responses = client.send(batch)

Copy


Request[] requests = new Request[] {
  new RecommendItemsToUser(userId, 5).setScenario("new_releases").setCascadeCreate(true),
  new RecommendItemsToUser(userId, 5).setScenario("just_for_you").setCascadeCreate(true)
};

Batch batch = new Batch(requests).setDistinctRecomms(true);

BatchResponse[] responses = client.send(batch);

Copy

const batchRequest = rqs.new Batch([
  new RecommendItemsToUser('user-id', 5, {scenario:'new_releases', cascadeCreate: true}),
  new RecommendItemsToUser('user-id', 5, {scenario:'just_for_you', cascadeCreate: true})
], {
  distinctRecomms: true
});

client.send(batchRequest,
  (err, resp) => {
    console.log(err);
    console.log(resp);
  }
);

Copy

<?php

$batchRequest = new Reqs\Batch([
  new Reqs\RecommendItemsToUser('user-id', 5, ['scenario' => 'new_releases', 'cascadeCreate' => true]),
  new Reqs\RecommendItemsToUser('user-id', 5, ['scenario' => 'just_for_you', 'cascadeCreate' => true])
], [
  'distinctRecomms' => true
]);
$replies = $client->send(batchRequest);
?>

Copy

Request[] requests = new Request[] {
     new RecommendItemsToUser(userId, 5, scenario: "new_releases", cascadeCreate: true),
     new RecommendItemsToUser(userId, 5, scenario: "just_for_you", cascadeCreate: true)
 };

 BatchResponse batchResponse = await client.SendAsync(new Batch(requests, distinctRecomms: true));

Copy

batchRes, err := client.NewBatch([]requests.Request{
  client.NewRecommendItemsToUser(userId, 5).SetScenario("new_releases").SetCascadeCreate(true),
  client.NewRecommendItemsToUser(userId, 5).SetScenario("just_for_you").SetCascadeCreate(true),
}).SetDistinctRecomms(true).Send()

Copy


{
  "requests": [
    {
      "method": "GET",
      "path": "/recomms/users/user-123/items/",
      "params": {
        "count": 3,
        "scenario": "recent_relases"
      }
    },
    {
      "method": "GET",
      "path": "/recomms/users/user-123/items/",
      "params": {
        "count": 3,
        "scenario": "just_for_you"
      }
    }
  ],
  "distinctRecomms": true
}

Notes

Executing the requests in a Batch is equivalent as if they were executed one-by-one individually; there are, however, many optimizations to make batch execution as fast as possible.

The status code of the Batch request itself is 200 even if the individual requests result in error – you have to inspect the code values in the resulting array.

If the status code of the whole batch is not 200, then there is an error in the Batch request itself; in such a case, the error message returned should help you to resolve the problem.

The batch size is limited to 10,000 requests when sent from the server side; if you wish to execute even larger number of requests, please split the Batch into multiple parts. Client libraries do the splitting automatically.

In case of the client side integration, the limit is 30 requests and only the requests that can be called from the client side are allowed.

Table of contents

Items
Item Properties
- Item properties definition
- Values of item properties
Users
User Properties
- User properties definition
- Values of user properties
  - Set User Values
  - Get User Values
User-Item Interactions
Recommendations
Search
Series
- Series definition
- Series items
Segmentations Definition
Miscellaneous
- Reset Database
- Batch