API Reference

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

  • Version: 3.2.0

  • Hostname: rapi.recombee.com

  • 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 sign and dot.

Add item

PUT
Add item

See doc for client: Python Ruby Java Node.js PHP .NET

client.send(AddItem(item_id))
client.send(AddItem.new(itemId))
client.send(new AddItem(String itemId));
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.AddItem(itemId), callback);
<?php
$client->send(new AddItem($item_id));
?>
client.Send(AddItem(string itemId));
PUT /{databaseId}/items/{itemId}

Adds new item of given itemId to the items catalog.

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

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

itemId

path

string

Yes

ID of the item to be created.

Responses

Response

Description

201

successful operation

400

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

401

Invalid or missing authentication details.

404

Invalid URL.

405

Invalid HTTP method.

409

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

Delete item

DELETE
Delete item

See doc for client: Python Ruby Java Node.js PHP .NET

client.send(DeleteItem(item_id))
client.send(DeleteItem.new(itemId))
client.send(new DeleteItem(String itemId));
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.DeleteItem(itemId), callback);
<?php
$client->send(new DeleteItem($item_id));
?>
client.Send(DeleteItem(string itemId));
DELETE /{databaseId}/items/{itemId}

Deletes an item of 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 often 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.

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

itemId

path

string

Yes

ID of the item to be deleted.

Responses

Response

Description

200

successful operation

400

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

401

Invalid or missing authentication details.

404

The itemId is not present in the item catalog. In many cases, you may consider this code 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 you URL.

405

Invalid HTTP method.

List items

GET
List items

See doc for client: Python Ruby Java Node.js PHP .NET

result = client.send(ListItems(
    # optional parameters:
    filter=<string>,
    count=<integer>,
    offset=<integer>,
    return_properties=<boolean>,
    included_properties=<array>
  )
)
result = client.send(ListItems.new({
    # optional parameters:
    :filter => <string>,
    :count => <integer>,
    :offset => <integer>,
    :return_properties => <boolean>,
    :included_properties => <array>
  })
)
Item[] result = client.send(new ListItems()
  .setFilter(String filter)
  .setCount(long count)
  .setOffset(long offset)
  .setReturnProperties(boolean returnProperties)
  .setIncludedProperties(String[] includedProperties)
);
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>
}), callback);
<?php
$result = $client->send(new ListItems([
    // optional parameters:
    'filter' => <string>,
    'count' => <integer>,
    'offset' => <integer>,
    'returnProperties' => <boolean>,
    'includedProperties' => <array>
  ])
);
?>
IEnumerable<Item> result = client.Send(ListItems(
    // optional parameters:
    filter: <string>,
    count: <long>,
    offset: <long>,
    returnProperties: <bool>,
    includedProperties: <string[]>
  )
);
GET /{databaseId}/items/list/?filter=<string>&count=<integer>&offset=<integer>&returnProperties=<boolean>&includedProperties=<array>

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

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

filter

query

string

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

query

integer

No

The number of items to be listed.

offset

query

integer

No

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

returnProperties

query

boolean

No

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

query

array

No

1.4.0

Allows to specify, 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

Response

Description

200

successful operation

Example:

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

401

Invalid or missing authentication details.

404

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

405

Invalid HTTP method.

Item Properties

Item properties definition

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

Add item property

PUT
Add item property

See doc for client: Python Ruby Java Node.js PHP .NET

client.send(AddItemProperty(property_name, type))
client.send(AddItemProperty.new(propertyName, type))
client.send(new AddItemProperty(String propertyName, String type));
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.AddItemProperty(propertyName, type), callback);
<?php
$client->send(new AddItemProperty($property_name, $type));
?>
client.Send(AddItemProperty(string propertyName, string type));
PUT /{databaseId}/items/properties/{propertyName}?type=<string>

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

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

propertyName

path

string

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

query

string

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

Response

Description

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.

401

Invalid or missing authentication details.

404

Invalid URL.

405

Invalid HTTP method.

409

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

Delete item property

DELETE
Delete item property

See doc for client: Python Ruby Java Node.js PHP .NET

client.send(DeleteItemProperty(property_name))
client.send(DeleteItemProperty.new(propertyName))
client.send(new DeleteItemProperty(String propertyName));
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.DeleteItemProperty(propertyName), callback);
<?php
$client->send(new DeleteItemProperty($property_name));
?>
client.Send(DeleteItemProperty(string propertyName));
DELETE /{databaseId}/items/properties/{propertyName}

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

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

propertyName

path

string

Yes

Name of the property to be deleted.

Responses

Response

Description

200

successful operation

400

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

401

Invalid or missing authentication details.

404

Property of given name is not present in the database. In many cases, you may consider this code 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 you URL.

405

Invalid HTTP method.

Get item property info

GET
Get item property info

See doc for client: Python Ruby Java Node.js PHP .NET

result = client.send(GetItemPropertyInfo(property_name))
result = client.send(GetItemPropertyInfo.new(propertyName))
PropertyInfo result = client.send(new GetItemPropertyInfo(String propertyName));
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.GetItemPropertyInfo(propertyName), callback);
<?php
$result = $client->send(new GetItemPropertyInfo($property_name));
?>
PropertyInfo result = client.Send(GetItemPropertyInfo(string propertyName));
GET /{databaseId}/items/properties/{propertyName}

Gets information about specified item property.

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

propertyName

path

string

Yes

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

Responses

Response

Description

200

successful operation

Example:

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

400

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

401

Invalid or missing authentication details.

404

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

405

Invalid HTTP method.

List item properties

GET
List item properties

See doc for client: Python Ruby Java Node.js PHP .NET

result = client.send(ListItemProperties())
result = client.send(ListItemProperties.new())
PropertyInfo[] result = client.send(new ListItemProperties());
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ListItemProperties(), callback);
<?php
$result = $client->send(new ListItemProperties());
?>
IEnumerable<PropertyInfo> result = client.Send(ListItemProperties());
GET /{databaseId}/items/properties/list/

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

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

Responses

Response

Description

200

successful operation

Example:

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

401

Invalid or missing authentication details.

404

Invalid URL.

405

Invalid HTTP method.

Values of item properties

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

Set item values

POST
Set item values

See doc for client: Python Ruby Java Node.js PHP .NET

client.send(SetItemValues(item_id, values,
    # optional parameters:
    cascade_create=<boolean>
  )
)
client.send(SetItemValues.new(itemId, values, {
    # optional parameters:
    :cascade_create => <boolean>
  })
)
client.send(new SetItemValues(String itemId, Map<String, Object> values)
  .setCascadeCreate(boolean cascadeCreate)
);
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.SetItemValues(itemId, values, {
  // optional parameters:
  'cascadeCreate': <boolean>
}), callback);
<?php
$client->send(new SetItemValues($item_id, $values, [
    // optional parameters:
    'cascadeCreate' => <boolean>
  ])
);
?>
client.Send(SetItemValues(string itemId, Dictionary<string, object> values,
    // optional parameters:
    cascadeCreate: <bool>
  )
);
POST /{databaseId}/items/{itemId}
Body (application/json):
{

}

Set/update (some) property values of a given item. The properties (columns) must be previously created by Add item property.

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

itemId

path

string

Yes

ID of the item which will be modified.

body

object

Yes

The values for the individual properties.

Example of 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

Response

Description

200

successful operation

400

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

401

Invalid or missing authentication details.

404

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

405

Invalid HTTP method.

Get item values

GET
Get item values

See doc for client: Python Ruby Java Node.js PHP .NET

result = client.send(GetItemValues(item_id))
result = client.send(GetItemValues.new(itemId))
Map<String, Object> result = client.send(new GetItemValues(String itemId));
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.GetItemValues(itemId), callback);
<?php
$result = $client->send(new GetItemValues($item_id));
?>
StringBinding result = client.Send(GetItemValues(string itemId));
GET /{databaseId}/items/{itemId}

Get all the current property values of a given item.

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

itemId

path

string

Yes

ID of the item properties of which are to be obtained.

Responses

Response

Description

200

successful operation

Example:

{
  "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_-:@.]+$

401

Invalid or missing authentication details.

404

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

405

Invalid HTTP method.

Users

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

Add user

PUT
Add user

See doc for client: Python Ruby Java Node.js PHP .NET

client.send(AddUser(user_id))
client.send(AddUser.new(userId))
client.send(new AddUser(String userId));
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.AddUser(userId), callback);
<?php
$client->send(new AddUser($user_id));
?>
client.Send(AddUser(string userId));
PUT /{databaseId}/users/{userId}

Adds a new user to the database.

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

userId

path

string

Yes

ID of the user to be added.

Responses

Response

Description

201

successful operation

400

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

401

Invalid or missing authentication details.

404

Invalid URL.

405

Invalid HTTP method.

409

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

Delete user

DELETE
Delete user

See doc for client: Python Ruby Java Node.js PHP .NET

client.send(DeleteUser(user_id))
client.send(DeleteUser.new(userId))
client.send(new DeleteUser(String userId));
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.DeleteUser(userId), callback);
<?php
$client->send(new DeleteUser($user_id));
?>
client.Send(DeleteUser(string userId));
DELETE /{databaseId}/users/{userId}

Deletes a user of 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.

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

userId

path

string

Yes

ID of the user to be added.

Responses

Response

Description

200

successful operation

400

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

401

Invalid or missing authentication details.

404

User of given userId is not present in the database. In many cases, you may consider this code 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 you URL.

405

Invalid HTTP method.

Merge users

PUT
Merge users

See doc for client: Python Ruby Java Node.js PHP .NET

client.send(MergeUsers(target_user_id, source_user_id,
    # optional parameters:
    cascade_create=<boolean>
  )
)
client.send(MergeUsers.new(targetUserId, sourceUserId, {
    # optional parameters:
    :cascade_create => <boolean>
  })
)
client.send(new MergeUsers(String targetUserId, String sourceUserId)
  .setCascadeCreate(boolean cascadeCreate)
);
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.MergeUsers(targetUserId, sourceUserId, {
  // optional parameters:
  'cascadeCreate': <boolean>
}), callback);
<?php
$client->send(new MergeUsers($target_user_id, $source_user_id, [
    // optional parameters:
    'cascadeCreate' => <boolean>
  ])
);
?>
client.Send(MergeUsers(string targetUserId, string sourceUserId,
    // optional parameters:
    cascadeCreate: <bool>
  )
);
PUT /{databaseId}/users/{targetUserId}/merge/{sourceUserId}?cascadeCreate=<boolean>

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 together 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.

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

targetUserId

path

string

Yes

ID of the targer user.

sourceUserId

path

string

Yes

ID of the source user.

cascadeCreate

query

boolean

No

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

Responses

Response

Description

201

successful operation

400

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

401

Invalid or missing authentication details.

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 you URL.

405

Invalid HTTP method.

List users

GET
List users

See doc for client: Python Ruby Java Node.js PHP .NET

result = client.send(ListUsers(
    # optional parameters:
    filter=<string>,
    count=<integer>,
    offset=<integer>,
    return_properties=<boolean>,
    included_properties=<array>
  )
)
result = client.send(ListUsers.new({
    # optional parameters:
    :filter => <string>,
    :count => <integer>,
    :offset => <integer>,
    :return_properties => <boolean>,
    :included_properties => <array>
  })
)
User[] result = client.send(new ListUsers()
  .setFilter(String filter)
  .setCount(long count)
  .setOffset(long offset)
  .setReturnProperties(boolean returnProperties)
  .setIncludedProperties(String[] includedProperties)
);
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>
}), callback);
<?php
$result = $client->send(new ListUsers([
    // optional parameters:
    'filter' => <string>,
    'count' => <integer>,
    'offset' => <integer>,
    'returnProperties' => <boolean>,
    'includedProperties' => <array>
  ])
);
?>
IEnumerable<User> result = client.Send(ListUsers(
    // optional parameters:
    filter: <string>,
    count: <long>,
    offset: <long>,
    returnProperties: <bool>,
    includedProperties: <string[]>
  )
);
GET /{databaseId}/users/list/?filter=<string>&count=<integer>&offset=<integer>&returnProperties=<boolean>&includedProperties=<array>

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

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

filter

query

string

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

query

integer

No

The number of users to be listed.

offset

query

integer

No

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

returnProperties

query

boolean

No

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

query

array

No

1.4.0

Allows to specify, 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

Response

Description

200

successful operation

Example:

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

401

Invalid or missing authentication details.

404

Invalid URL.

405

Invalid HTTP method.

User Properties

User properties definition

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

Add user property

PUT
Add user property

See doc for client: Python Ruby Java Node.js PHP .NET

client.send(AddUserProperty(property_name, type))
client.send(AddUserProperty.new(propertyName, type))
client.send(new AddUserProperty(String propertyName, String type));
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.AddUserProperty(propertyName, type), callback);
<?php
$client->send(new AddUserProperty($property_name, $type));
?>
client.Send(AddUserProperty(string propertyName, string type));
PUT /{databaseId}/users/properties/{propertyName}?type=<string>

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

Since version 1.3.0

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

1.3.0

ID of your database.

propertyName

path

string

Yes

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

query

string

Yes

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

Response

Description

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.

401

Invalid or missing authentication details.

404

Invalid URL.

405

Invalid HTTP method.

409

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

Delete user property

DELETE
Delete user property

See doc for client: Python Ruby Java Node.js PHP .NET

client.send(DeleteUserProperty(property_name))
client.send(DeleteUserProperty.new(propertyName))
client.send(new DeleteUserProperty(String propertyName));
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.DeleteUserProperty(propertyName), callback);
<?php
$client->send(new DeleteUserProperty($property_name));
?>
client.Send(DeleteUserProperty(string propertyName));
DELETE /{databaseId}/users/properties/{propertyName}

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

Since version 1.3.0

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

1.3.0

ID of your database.

propertyName

path

string

Yes

1.3.0

Name of the property to be deleted.

Responses

Response

Description

200

successful operation

400

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

401

Invalid or missing authentication details.

404

Property of given name is not present in the database. In many cases, you may consider this code 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 you URL.

405

Invalid HTTP method.

Get user property info

GET
Get user property info

See doc for client: Python Ruby Java Node.js PHP .NET

result = client.send(GetUserPropertyInfo(property_name))
result = client.send(GetUserPropertyInfo.new(propertyName))
PropertyInfo result = client.send(new GetUserPropertyInfo(String propertyName));
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.GetUserPropertyInfo(propertyName), callback);
<?php
$result = $client->send(new GetUserPropertyInfo($property_name));
?>
PropertyInfo result = client.Send(GetUserPropertyInfo(string propertyName));
GET /{databaseId}/users/properties/{propertyName}

Gets information about specified user property.

Since version 1.3.0

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

1.3.0

ID of your database.

propertyName

path

string

Yes

1.3.0

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

Responses

Response

Description

200

successful operation

Example:

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

400

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

401

Invalid or missing authentication details.

404

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

405

Invalid HTTP method.

List user properties

GET
List user properties

See doc for client: Python Ruby Java Node.js PHP .NET

result = client.send(ListUserProperties())
result = client.send(ListUserProperties.new())
PropertyInfo[] result = client.send(new ListUserProperties());
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ListUserProperties(), callback);
<?php
$result = $client->send(new ListUserProperties());
?>
IEnumerable<PropertyInfo> result = client.Send(ListUserProperties());
GET /{databaseId}/users/properties/list/

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

Since version 1.3.0

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

1.3.0

ID of your database.

Responses

Response

Description

200

successful operation

Example:

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

401

Invalid or missing authentication details.

404

Invalid URL.

405

Invalid HTTP method.

Values of user properties

The following methods allow assigning property values to user. Set values are examined by content-based algorithms and used in building recommendations especially for users that have only 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.

Set user values

POST
Set user values

See doc for client: Python Ruby Java Node.js PHP .NET

client.send(SetUserValues(user_id, values,
    # optional parameters:
    cascade_create=<boolean>
  )
)
client.send(SetUserValues.new(userId, values, {
    # optional parameters:
    :cascade_create => <boolean>
  })
)
client.send(new SetUserValues(String userId, Map<String, Object> values)
  .setCascadeCreate(boolean cascadeCreate)
);
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.SetUserValues(userId, values, {
  // optional parameters:
  'cascadeCreate': <boolean>
}), callback);
<?php
$client->send(new SetUserValues($user_id, $values, [
    // optional parameters:
    'cascadeCreate' => <boolean>
  ])
);
?>
client.Send(SetUserValues(string userId, Dictionary<string, object> values,
    // optional parameters:
    cascadeCreate: <bool>
  )
);
POST /{databaseId}/users/{userId}
Body (application/json):
{

}

Set/update (some) property values of a given user. The properties (columns) must be previously created by Add user property.

Since version 1.3.0

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

1.3.0

ID of your database.

userId

path

string

Yes

1.3.0

ID of the user which will be modified.

body

object

Yes

1.3.0

The values for the individual properties.

Example of 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

Response

Description

200

successful operation

400

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

401

Invalid or missing authentication details.

404

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

405

Invalid HTTP method.

Get user values

GET
Get user values

See doc for client: Python Ruby Java Node.js PHP .NET

result = client.send(GetUserValues(user_id))
result = client.send(GetUserValues.new(userId))
Map<String, Object> result = client.send(new GetUserValues(String userId));
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.GetUserValues(userId), callback);
<?php
$result = $client->send(new GetUserValues($user_id));
?>
StringBinding result = client.Send(GetUserValues(string userId));
GET /{databaseId}/users/{userId}

Get all the current property values of a given user.

Since version 1.3.0

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

1.3.0

ID of your database.

userId

path

string

Yes

1.3.0

ID of the user properties of which are to be obtained.

Responses

Response

Description

200

successful operation

Example:

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

400

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

401

Invalid or missing authentication details.

404

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

405

Invalid HTTP method.

User-Item Interactions

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

Detail Views

Add detail view

POST
Add detail view

See doc for client: Python Ruby Java Node.js PHP .NET

client.send(new recombee.AddDetailView(userId, itemId, {
  // optional parameters:
  'timestamp': <string / number>,
  'duration': <integer>,
  'cascadeCreate': <boolean>,
  'recommId': <string>
}), callback);
client.send(AddDetailView(user_id, item_id,
    # optional parameters:
    timestamp=<string / number>,
    duration=<integer>,
    cascade_create=<boolean>,
    recomm_id=<string>
  )
)
client.send(AddDetailView.new(userId, itemId, {
    # optional parameters:
    :timestamp => <string / number>,
    :duration => <integer>,
    :cascade_create => <boolean>,
    :recomm_id => <string>
  })
)
client.send(new AddDetailView(String userId, String itemId)
  .setTimestamp(Date timestamp)
  .setDuration(long duration)
  .setCascadeCreate(boolean cascadeCreate)
  .setRecommId(String recommId)
);
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>
}), callback);
<?php
$client->send(new AddDetailView($user_id, $item_id, [
    // optional parameters:
    'timestamp' => <string / number>,
    'duration' => <integer>,
    'cascadeCreate' => <boolean>,
    'recommId' => <string>
  ])
);
?>
client.Send(AddDetailView(string userId, string itemId,
    // optional parameters:
    timestamp: <DateTime>,
    duration: <long>,
    cascadeCreate: <bool>,
    recommId: <string>
  )
);
POST /{databaseId}/detailviews/
Body (application/json):
{
  "userId" => <string>,
  "itemId" => <string>,
  "timestamp" => <string / number>,
  "duration" => <integer>,
  "cascadeCreate" => <boolean>,
  "recommId" => <string>
}

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

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

userId

body

string

Yes

User who viewed the item

itemId

body

string

Yes

Viewed item

timestamp

body

string / number

No

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

duration

body

integer

No

Duration of the view

cascadeCreate

body

boolean

No

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

recommId

body

string

No

2.2.0

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

Responses

Response

Description

201

successful operation

400

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

401

Invalid or missing authentication details.

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 you URL.

405

Invalid HTTP method.

409

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

Delete detail view

DELETE
Delete detail view

See doc for client: Python Ruby Java Node.js PHP .NET

client.send(DeleteDetailView(user_id, item_id,
    # optional parameters:
    timestamp=<number>
  )
)
client.send(DeleteDetailView.new(userId, itemId, {
    # optional parameters:
    :timestamp => <number>
  })
)
client.send(new DeleteDetailView(String userId, String itemId)
  .setTimestamp(Date timestamp)
);
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.DeleteDetailView(userId, itemId, {
  // optional parameters:
  'timestamp': <number>
}), callback);
<?php
$client->send(new DeleteDetailView($user_id, $item_id, [
    // optional parameters:
    'timestamp' => <number>
  ])
);
?>
client.Send(DeleteDetailView(string userId, string itemId,
    // optional parameters:
    timestamp: <DateTime>
  )
);
DELETE /{databaseId}/detailviews/?userId=<string>&itemId=<string>&timestamp=<number>

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

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

userId

query

string

Yes

ID of the user who made the detail view.

itemId

query

string

Yes

ID of the item of which the details were viewed.

timestamp

query

number

No

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

Responses

Response

Description

200

successful operation

400

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

401

Invalid or missing authentication details.

404

The userId, itemId, or detail view with 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 you URL.

405

Invalid HTTP method.

List item detail views

GET
List item detail views

See doc for client: Python Ruby Java Node.js PHP .NET

result = client.send(ListItemDetailViews(item_id))
result = client.send(ListItemDetailViews.new(itemId))
DetailView[] result = client.send(new ListItemDetailViews(String itemId));
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ListItemDetailViews(itemId), callback);
<?php
$result = $client->send(new ListItemDetailViews($item_id));
?>
IEnumerable<DetailView> result = client.Send(ListItemDetailViews(string itemId));
GET /{databaseId}/items/{itemId}/detailviews/

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

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

itemId

path

string

Yes

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

Responses

Response

Description

200

successful operation

Example:

[
  {
    "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_-:@.]+$.

401

Invalid or missing authentication details.

404

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

405

Invalid HTTP method.

List user detail views

GET
List user detail views

See doc for client: Python Ruby Java Node.js PHP .NET

result = client.send(ListUserDetailViews(user_id))
result = client.send(ListUserDetailViews.new(userId))
DetailView[] result = client.send(new ListUserDetailViews(String userId));
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ListUserDetailViews(userId), callback);
<?php
$result = $client->send(new ListUserDetailViews($user_id));
?>
IEnumerable<DetailView> result = client.Send(ListUserDetailViews(string userId));
GET /{databaseId}/users/{userId}/detailviews/

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

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

userId

path

string

Yes

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

Responses

Response

Description

200

successful operation

Example:

[
  {
    "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_-:@.]+$.

401

Invalid or missing authentication details.

404

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

405

Invalid HTTP method.

Purchases

Add purchase

POST
Add purchase

See doc for client: Python Ruby Java Node.js PHP .NET

client.send(new recombee.AddPurchase(userId, itemId, {
  // optional parameters:
  'timestamp': <string / number>,
  'cascadeCreate': <boolean>,
  'amount': <number>,
  'price': <number>,
  'profit': <number>,
  'recommId': <string>
}), callback);
client.send(AddPurchase(user_id, item_id,
    # optional parameters:
    timestamp=<string / number>,
    cascade_create=<boolean>,
    amount=<number>,
    price=<number>,
    profit=<number>,
    recomm_id=<string>
  )
)
client.send(AddPurchase.new(userId, itemId, {
    # optional parameters:
    :timestamp => <string / number>,
    :cascade_create => <boolean>,
    :amount => <number>,
    :price => <number>,
    :profit => <number>,
    :recomm_id => <string>
  })
)
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)
);
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>
}), callback);
<?php
$client->send(new AddPurchase($user_id, $item_id, [
    // optional parameters:
    'timestamp' => <string / number>,
    'cascadeCreate' => <boolean>,
    'amount' => <number>,
    'price' => <number>,
    'profit' => <number>,
    'recommId' => <string>
  ])
);
?>
client.Send(AddPurchase(string userId, string itemId,
    // optional parameters:
    timestamp: <DateTime>,
    cascadeCreate: <bool>,
    amount: <double>,
    price: <double>,
    profit: <double>,
    recommId: <string>
  )
);
POST /{databaseId}/purchases/
Body (application/json):
{
  "userId" => <string>,
  "itemId" => <string>,
  "timestamp" => <string / number>,
  "cascadeCreate" => <boolean>,
  "amount" => <number>,
  "price" => <number>,
  "profit" => <number>,
  "recommId" => <string>
}

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

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

userId

body

string

Yes

User who purchased the item

itemId

body

string

Yes

Purchased item

timestamp

body

string / number

No

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

cascadeCreate

body

boolean

No

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

amount

body

number

No

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 to 2.

price

body

number

No

1.6.0

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

profit

body

number

No

1.6.0

Your profit from the purchased item. The profit is natural in 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 applicable also in other domains (for example at a news company it may be income from displayed advertisement on article page). If amount is greater than 1, sum of profit of all the items should be given.

recommId

body

string

No

2.2.0

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

Responses

Response

Description

201

successful operation

400

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

401

Invalid or missing authentication details.

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 you URL.

405

Invalid HTTP method.

409

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

Delete purchase

DELETE
Delete purchase

See doc for client: Python Ruby Java Node.js PHP .NET

client.send(DeletePurchase(user_id, item_id,
    # optional parameters:
    timestamp=<number>
  )
)
client.send(DeletePurchase.new(userId, itemId, {
    # optional parameters:
    :timestamp => <number>
  })
)
client.send(new DeletePurchase(String userId, String itemId)
  .setTimestamp(Date timestamp)
);
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.DeletePurchase(userId, itemId, {
  // optional parameters:
  'timestamp': <number>
}), callback);
<?php
$client->send(new DeletePurchase($user_id, $item_id, [
    // optional parameters:
    'timestamp' => <number>
  ])
);
?>
client.Send(DeletePurchase(string userId, string itemId,
    // optional parameters:
    timestamp: <DateTime>
  )
);
DELETE /{databaseId}/purchases/?userId=<string>&itemId=<string>&timestamp=<number>

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

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

userId

query

string

Yes

ID of the user who made the purchase.

itemId

query

string

Yes

ID of the item of which was purchased.

timestamp

query

number

No

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

Responses

Response

Description

200

successful operation

400

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

401

Invalid or missing authentication details.

404

The userId, itemId, or purchase with 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 you URL.

405

Invalid HTTP method.

List item purchases

GET
List item purchases

See doc for client: Python Ruby Java Node.js PHP .NET

result = client.send(ListItemPurchases(item_id))
result = client.send(ListItemPurchases.new(itemId))
Purchase[] result = client.send(new ListItemPurchases(String itemId));
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ListItemPurchases(itemId), callback);
<?php
$result = $client->send(new ListItemPurchases($item_id));
?>
IEnumerable<Purchase> result = client.Send(ListItemPurchases(string itemId));
GET /{databaseId}/items/{itemId}/purchases/

List all the ever-made purchases of a given item.

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

itemId

path

string

Yes

ID of the item of which the pucrhases are to be listed.

Responses

Response

Description

200

successful operation

Example:

[
  {
    "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_-:@.]+$.

401

Invalid or missing authentication details.

404

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

405

Invalid HTTP method.

List user purchases

GET
List user purchases

See doc for client: Python Ruby Java Node.js PHP .NET

result = client.send(ListUserPurchases(user_id))
result = client.send(ListUserPurchases.new(userId))
Purchase[] result = client.send(new ListUserPurchases(String userId));
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ListUserPurchases(userId), callback);
<?php
$result = $client->send(new ListUserPurchases($user_id));
?>
IEnumerable<Purchase> result = client.Send(ListUserPurchases(string userId));
GET /{databaseId}/users/{userId}/purchases/

List all the purchases ever made by a given user.

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

userId

path

string

Yes

ID of the user whose purchases are to be listed.

Responses

Response

Description

200

successful operation

Example:

[
  {
    "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_-:@.]+$.

401

Invalid or missing authentication details.

404

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

405

Invalid HTTP method.

Ratings

Add rating

POST
Add rating

See doc for client: Python Ruby Java Node.js PHP .NET

client.send(new recombee.AddRating(userId, itemId, rating, {
  // optional parameters:
  'timestamp': <string / number>,
  'cascadeCreate': <boolean>,
  'recommId': <string>
}), callback);
client.send(AddRating(user_id, item_id, rating,
    # optional parameters:
    timestamp=<string / number>,
    cascade_create=<boolean>,
    recomm_id=<string>
  )
)
client.send(AddRating.new(userId, itemId, rating, {
    # optional parameters:
    :timestamp => <string / number>,
    :cascade_create => <boolean>,
    :recomm_id => <string>
  })
)
client.send(new AddRating(String userId, String itemId, double rating)
  .setTimestamp(Date timestamp)
  .setCascadeCreate(boolean cascadeCreate)
  .setRecommId(String recommId)
);
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>
}), callback);
<?php
$client->send(new AddRating($user_id, $item_id, $rating, [
    // optional parameters:
    'timestamp' => <string / number>,
    'cascadeCreate' => <boolean>,
    'recommId' => <string>
  ])
);
?>
client.Send(AddRating(string userId, string itemId, double rating,
    // optional parameters:
    timestamp: <DateTime>,
    cascadeCreate: <bool>,
    recommId: <string>
  )
);
POST /{databaseId}/ratings/
Body (application/json):
{
  "userId" => <string>,
  "itemId" => <string>,
  "timestamp" => <string / number>,
  "rating" => <number>,
  "cascadeCreate" => <boolean>,
  "recommId" => <string>
}

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

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

userId

body

string

Yes

User who submitted the rating

itemId

body

string

Yes

Rated item

timestamp

body

string / number

No

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

rating

body

number

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

body

boolean

No

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

recommId

body

string

No

2.2.0

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

Responses

Response

Description

201

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.

401

Invalid or missing authentication details.

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 you URL.

405

Invalid HTTP method.

409

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

Delete rating

DELETE
Delete rating

See doc for client: Python Ruby Java Node.js PHP .NET

client.send(DeleteRating(user_id, item_id,
    # optional parameters:
    timestamp=<number>
  )
)
client.send(DeleteRating.new(userId, itemId, {
    # optional parameters:
    :timestamp => <number>
  })
)
client.send(new DeleteRating(String userId, String itemId)
  .setTimestamp(Date timestamp)
);
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.DeleteRating(userId, itemId, {
  // optional parameters:
  'timestamp': <number>
}), callback);
<?php
$client->send(new DeleteRating($user_id, $item_id, [
    // optional parameters:
    'timestamp' => <number>
  ])
);
?>
client.Send(DeleteRating(string userId, string itemId,
    // optional parameters:
    timestamp: <DateTime>
  )
);
DELETE /{databaseId}/ratings/?userId=<string>&itemId=<string>&timestamp=<number>

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

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

userId

query

string

Yes

ID of the user who rated the item.

itemId

query

string

Yes

ID of the item which was rated.

timestamp

query

number

No

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

Responses

Response

Description

200

successful operation

400

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

401

Invalid or missing authentication details.

404

The userId, itemId or rating with 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 you URL.

405

Invalid HTTP method.

List item ratings

GET
List item ratings

See doc for client: Python Ruby Java Node.js PHP .NET

result = client.send(ListItemRatings(item_id))
result = client.send(ListItemRatings.new(itemId))
Rating[] result = client.send(new ListItemRatings(String itemId));
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ListItemRatings(itemId), callback);
<?php
$result = $client->send(new ListItemRatings($item_id));
?>
IEnumerable<Rating> result = client.Send(ListItemRatings(string itemId));
GET /{databaseId}/items/{itemId}/ratings/

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

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

itemId

path

string

Yes

ID of the item of which the ratings are to be listed.

Responses

Response

Description

200

successful operation

Example:

[
  {
    "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_-:@.]+$.

401

Invalid or missing authentication details.

404

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

405

Invalid HTTP method.

List user ratings

GET
List user ratings

See doc for client: Python Ruby Java Node.js PHP .NET

result = client.send(ListUserRatings(user_id))
result = client.send(ListUserRatings.new(userId))
Rating[] result = client.send(new ListUserRatings(String userId));
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ListUserRatings(userId), callback);
<?php
$result = $client->send(new ListUserRatings($user_id));
?>
IEnumerable<Rating> result = client.Send(ListUserRatings(string userId));
GET /{databaseId}/users/{userId}/ratings/

List all the ratings ever submitted by a given user.

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

userId

path

string

Yes

ID of the user whose ratings are to be listed.

Responses

Response

Description

200

successful operation

Example:

[
  {
    "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_-:@.]+$.

401

Invalid or missing authentication details.

404

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

405

Invalid HTTP method.

Cart Additions

Add cart addition

POST
Add cart addition

See doc for client: Python Ruby Java Node.js PHP .NET

client.send(new recombee.AddCartAddition(userId, itemId, {
  // optional parameters:
  'timestamp': <string / number>,
  'cascadeCreate': <boolean>,
  'amount': <number>,
  'price': <number>,
  'recommId': <string>
}), callback);
client.send(AddCartAddition(user_id, item_id,
    # optional parameters:
    timestamp=<string / number>,
    cascade_create=<boolean>,
    amount=<number>,
    price=<number>,
    recomm_id=<string>
  )
)
client.send(AddCartAddition.new(userId, itemId, {
    # optional parameters:
    :timestamp => <string / number>,
    :cascade_create => <boolean>,
    :amount => <number>,
    :price => <number>,
    :recomm_id => <string>
  })
)
client.send(new AddCartAddition(String userId, String itemId)
  .setTimestamp(Date timestamp)
  .setCascadeCreate(boolean cascadeCreate)
  .setAmount(double amount)
  .setPrice(double price)
  .setRecommId(String recommId)
);
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>
}), callback);
<?php
$client->send(new AddCartAddition($user_id, $item_id, [
    // optional parameters:
    'timestamp' => <string / number>,
    'cascadeCreate' => <boolean>,
    'amount' => <number>,
    'price' => <number>,
    'recommId' => <string>
  ])
);
?>
client.Send(AddCartAddition(string userId, string itemId,
    // optional parameters:
    timestamp: <DateTime>,
    cascadeCreate: <bool>,
    amount: <double>,
    price: <double>,
    recommId: <string>
  )
);
POST /{databaseId}/cartadditions/
Body (application/json):
{
  "userId" => <string>,
  "itemId" => <string>,
  "timestamp" => <string / number>,
  "cascadeCreate" => <boolean>,
  "amount" => <number>,
  "price" => <number>,
  "recommId" => <string>
}

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

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

userId

body

string

Yes

User who added the item to the cart

itemId

body

string

Yes

Item added to the cart

timestamp

body

string / number

No

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

cascadeCreate

body

boolean

No

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

amount

body

number

No

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 to 2.

price

body

number

No

1.6.0

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

recommId

body

string

No

2.2.0

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

Responses

Response

Description

201

successful operation

400

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

401

Invalid or missing authentication details.

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 you URL.

405

Invalid HTTP method.

409

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

Delete cart addition

DELETE
Delete cart addition

See doc for client: Python Ruby Java Node.js PHP .NET

client.send(DeleteCartAddition(user_id, item_id,
    # optional parameters:
    timestamp=<number>
  )
)
client.send(DeleteCartAddition.new(userId, itemId, {
    # optional parameters:
    :timestamp => <number>
  })
)
client.send(new DeleteCartAddition(String userId, String itemId)
  .setTimestamp(Date timestamp)
);
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.DeleteCartAddition(userId, itemId, {
  // optional parameters:
  'timestamp': <number>
}), callback);
<?php
$client->send(new DeleteCartAddition($user_id, $item_id, [
    // optional parameters:
    'timestamp' => <number>
  ])
);
?>
client.Send(DeleteCartAddition(string userId, string itemId,
    // optional parameters:
    timestamp: <DateTime>
  )
);
DELETE /{databaseId}/cartadditions/?userId=<string>&itemId=<string>&timestamp=<number>

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

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

userId

query

string

Yes

ID of the user who made the cart addition.

itemId

query

string

Yes

ID of the item of which was added to cart.

timestamp

query

number

No

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

Responses

Response

Description

200

successful operation

400

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

401

Invalid or missing authentication details.

404

The userId, itemId, or cart addition with 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 you URL.

405

Invalid HTTP method.

List item cart additions

GET
List item cart additions

See doc for client: Python Ruby Java Node.js PHP .NET

result = client.send(ListItemCartAdditions(item_id))
result = client.send(ListItemCartAdditions.new(itemId))
CartAddition[] result = client.send(new ListItemCartAdditions(String itemId));
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ListItemCartAdditions(itemId), callback);
<?php
$result = $client->send(new ListItemCartAdditions($item_id));
?>
IEnumerable<CartAddition> result = client.Send(ListItemCartAdditions(string itemId));
GET /{databaseId}/items/{itemId}/cartadditions/

List all the ever-made cart addition of a given item.

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

itemId

path

string

Yes

ID of the item of which the cart addition are to be listed.

Responses

Response

Description

200

successful operation

Example:

[
  {
    "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_-:@.]+$.

401

Invalid or missing authentication details.

404

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

405

Invalid HTTP method.

List user cart additions

GET
List user cart additions

See doc for client: Python Ruby Java Node.js PHP .NET

result = client.send(ListUserCartAdditions(user_id))
result = client.send(ListUserCartAdditions.new(userId))
CartAddition[] result = client.send(new ListUserCartAdditions(String userId));
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ListUserCartAdditions(userId), callback);
<?php
$result = $client->send(new ListUserCartAdditions($user_id));
?>
IEnumerable<CartAddition> result = client.Send(ListUserCartAdditions(string userId));
GET /{databaseId}/users/{userId}/cartadditions/

List all the cart additions ever made by a given user.

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

userId

path

string

Yes

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

Responses

Response

Description

200

successful operation

Example:

[
  {
    "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_-:@.]+$.

401

Invalid or missing authentication details.

404

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

405

Invalid HTTP method.

Bookmarks

Add bookmark

POST
Add bookmark

See doc for client: Python Ruby Java Node.js PHP .NET

client.send(new recombee.AddBookmark(userId, itemId, {
  // optional parameters:
  'timestamp': <string / number>,
  'cascadeCreate': <boolean>,
  'recommId': <string>
}), callback);
client.send(AddBookmark(user_id, item_id,
    # optional parameters:
    timestamp=<string / number>,
    cascade_create=<boolean>,
    recomm_id=<string>
  )
)
client.send(AddBookmark.new(userId, itemId, {
    # optional parameters:
    :timestamp => <string / number>,
    :cascade_create => <boolean>,
    :recomm_id => <string>
  })
)
client.send(new AddBookmark(String userId, String itemId)
  .setTimestamp(Date timestamp)
  .setCascadeCreate(boolean cascadeCreate)
  .setRecommId(String recommId)
);
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>
}), callback);
<?php
$client->send(new AddBookmark($user_id, $item_id, [
    // optional parameters:
    'timestamp' => <string / number>,
    'cascadeCreate' => <boolean>,
    'recommId' => <string>
  ])
);
?>
client.Send(AddBookmark(string userId, string itemId,
    // optional parameters:
    timestamp: <DateTime>,
    cascadeCreate: <bool>,
    recommId: <string>
  )
);
POST /{databaseId}/bookmarks/
Body (application/json):
{
  "userId" => <string>,
  "itemId" => <string>,
  "timestamp" => <string / number>,
  "cascadeCreate" => <boolean>,
  "recommId" => <string>
}

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

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

userId

body

string

Yes

User who bookmarked the item

itemId

body

string

Yes

Bookmarked item

timestamp

body

string / number

No

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

cascadeCreate

body

boolean

No

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

recommId

body

string

No

2.2.0

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

Responses

Response

Description

201

successful operation

400

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

401

Invalid or missing authentication details.

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 you URL.

405

Invalid HTTP method.

409

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

Delete bookmark

DELETE
Delete bookmark

See doc for client: Python Ruby Java Node.js PHP .NET

client.send(DeleteBookmark(user_id, item_id,
    # optional parameters:
    timestamp=<number>
  )
)
client.send(DeleteBookmark.new(userId, itemId, {
    # optional parameters:
    :timestamp => <number>
  })
)
client.send(new DeleteBookmark(String userId, String itemId)
  .setTimestamp(Date timestamp)
);
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.DeleteBookmark(userId, itemId, {
  // optional parameters:
  'timestamp': <number>
}), callback);
<?php
$client->send(new DeleteBookmark($user_id, $item_id, [
    // optional parameters:
    'timestamp' => <number>
  ])
);
?>
client.Send(DeleteBookmark(string userId, string itemId,
    // optional parameters:
    timestamp: <DateTime>
  )
);
DELETE /{databaseId}/bookmarks/?userId=<string>&itemId=<string>&timestamp=<number>

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

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

userId

query

string

Yes

ID of the user who made the bookmark.

itemId

query

string

Yes

ID of the item of which was bookmarked.

timestamp

query

number

No

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

Responses

Response

Description

200

successful operation

400

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

401

Invalid or missing authentication details.

404

The userId, itemId, or bookmark with 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 you URL.

405

Invalid HTTP method.

List item bookmarks

GET
List item bookmarks

See doc for client: Python Ruby Java Node.js PHP .NET

result = client.send(ListItemBookmarks(item_id))
result = client.send(ListItemBookmarks.new(itemId))
Bookmark[] result = client.send(new ListItemBookmarks(String itemId));
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ListItemBookmarks(itemId), callback);
<?php
$result = $client->send(new ListItemBookmarks($item_id));
?>
IEnumerable<Bookmark> result = client.Send(ListItemBookmarks(string itemId));
GET /{databaseId}/items/{itemId}/bookmarks/

List all the ever-made bookmarks of a given item.

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

itemId

path

string

Yes

ID of the item of which the bookmarks are to be listed.

Responses

Response

Description

200

successful operation

Example:

[
  {
    "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_-:@.]+$.

401

Invalid or missing authentication details.

404

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

405

Invalid HTTP method.

List user bookmarks

GET
List user bookmarks

See doc for client: Python Ruby Java Node.js PHP .NET

result = client.send(ListUserBookmarks(user_id))
result = client.send(ListUserBookmarks.new(userId))
Bookmark[] result = client.send(new ListUserBookmarks(String userId));
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ListUserBookmarks(userId), callback);
<?php
$result = $client->send(new ListUserBookmarks($user_id));
?>
IEnumerable<Bookmark> result = client.Send(ListUserBookmarks(string userId));
GET /{databaseId}/users/{userId}/bookmarks/

List all the bookmarks ever made by a given user.

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

userId

path

string

Yes

ID of the user whose bookmarks are to be listed.

Responses

Response

Description

200

successful operation

Example:

[
  {
    "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_-:@.]+$.

401

Invalid or missing authentication details.

404

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

405

Invalid HTTP method.

View Portions

Set view portion

POST
Set view portion

See doc for client: Python Ruby Java Node.js PHP .NET

client.send(new recombee.SetViewPortion(userId, itemId, portion, {
  // optional parameters:
  'sessionId': <string>,
  'timestamp': <string / number>,
  'cascadeCreate': <boolean>,
  'recommId': <string>
}), callback);
client.send(SetViewPortion(user_id, item_id, portion,
    # optional parameters:
    session_id=<string>,
    timestamp=<string / number>,
    cascade_create=<boolean>,
    recomm_id=<string>
  )
)
client.send(SetViewPortion.new(userId, itemId, portion, {
    # optional parameters:
    :session_id => <string>,
    :timestamp => <string / number>,
    :cascade_create => <boolean>,
    :recomm_id => <string>
  })
)
client.send(new SetViewPortion(String userId, String itemId, double portion)
  .setSessionId(String sessionId)
  .setTimestamp(Date timestamp)
  .setCascadeCreate(boolean cascadeCreate)
  .setRecommId(String recommId)
);
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>
}), callback);
<?php
$client->send(new SetViewPortion($user_id, $item_id, $portion, [
    // optional parameters:
    'sessionId' => <string>,
    'timestamp' => <string / number>,
    'cascadeCreate' => <boolean>,
    'recommId' => <string>
  ])
);
?>
client.Send(SetViewPortion(string userId, string itemId, double portion,
    // optional parameters:
    sessionId: <string>,
    timestamp: <DateTime>,
    cascadeCreate: <bool>,
    recommId: <string>
  )
);
POST /{databaseId}/viewportions/
Body (application/json):
{
  "userId" => <string>,
  "itemId" => <string>,
  "portion" => <number>,
  "sessionId" => <string>,
  "timestamp" => <string / number>,
  "cascadeCreate" => <boolean>,
  "recommId" => <string>
}

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

Since version 2.1.0

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

2.1.0

ID of your database.

userId

body

string

Yes

2.1.0

User who viewed a portion of the item

itemId

body

string

Yes

2.1.0

Viewed item

portion

body

number

Yes

2.1.0

Viewed portion of the item (number between 0.0 (viewed nothing) and 1.0 (viewed full item) ). It should be the really viewed part of the item, no matter seeking, so 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

body

string

No

2.1.0

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

timestamp

body

string / number

No

2.1.0

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

cascadeCreate

body

boolean

No

2.1.0

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

recommId

body

string

No

2.2.0

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

Responses

Response

Description

201

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].

401

Invalid or missing authentication details.

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 you URL.

405

Invalid HTTP method.

Delete view portion

DELETE
Delete view portion

See doc for client: Python Ruby Java Node.js PHP .NET

client.send(DeleteViewPortion(user_id, item_id,
    # optional parameters:
    session_id=<string>
  )
)
client.send(DeleteViewPortion.new(userId, itemId, {
    # optional parameters:
    :session_id => <string>
  })
)
client.send(new DeleteViewPortion(String userId, String itemId)
  .setSessionId(String sessionId)
);
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.DeleteViewPortion(userId, itemId, {
  // optional parameters:
  'sessionId': <string>
}), callback);
<?php
$client->send(new DeleteViewPortion($user_id, $item_id, [
    // optional parameters:
    'sessionId' => <string>
  ])
);
?>
client.Send(DeleteViewPortion(string userId, string itemId,
    // optional parameters:
    sessionId: <string>
  )
);
DELETE /{databaseId}/viewportions/?userId=<string>&itemId=<string>&sessionId=<string>

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

Since version 2.1.0

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

2.1.0

ID of your database.

userId

query

string

Yes

2.1.0

ID of the user who rated the item.

itemId

query

string

Yes

2.1.0

ID of the item which was rated.

sessionId

query

string

No

2.1.0

Identifier of a session.

Responses

Response

Description

200

successful operation

400

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

401

Invalid or missing authentication details.

404

The userId, itemId or view portion with 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 you URL.

405

Invalid HTTP method.

List item view portions

GET
List item view portions

See doc for client: Python Ruby Java Node.js PHP .NET

result = client.send(ListItemViewPortions(item_id))
result = client.send(ListItemViewPortions.new(itemId))
ViewPortion[] result = client.send(new ListItemViewPortions(String itemId));
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ListItemViewPortions(itemId), callback);
<?php
$result = $client->send(new ListItemViewPortions($item_id));
?>
IEnumerable<ViewPortion> result = client.Send(ListItemViewPortions(string itemId));
GET /{databaseId}/items/{itemId}/viewportions/

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

Since version 2.1.0

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

2.1.0

ID of your database.

itemId

path

string

Yes

2.1.0

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

Responses

Response

Description

200

successful operation

Example:

[
  {
    "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_-:@.]+$.

401

Invalid or missing authentication details.

404

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

405

Invalid HTTP method.

List user view portions

GET
List user view portions

See doc for client: Python Ruby Java Node.js PHP .NET

result = client.send(ListUserViewPortions(user_id))
result = client.send(ListUserViewPortions.new(userId))
ViewPortion[] result = client.send(new ListUserViewPortions(String userId));
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ListUserViewPortions(userId), callback);
<?php
$result = $client->send(new ListUserViewPortions($user_id));
?>
IEnumerable<ViewPortion> result = client.Send(ListUserViewPortions(string userId));
GET /{databaseId}/users/{userId}/viewportions/

List all the view portions ever submitted by a given user.

Since version 2.1.0

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

2.1.0

ID of your database.

userId

path

string

Yes

2.1.0

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

Responses

Response

Description

200

successful operation

Example:

[
  {
    "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_-:@.]+$.

401

Invalid or missing authentication details.

404

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

405

Invalid HTTP method.

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).

Recommend items to user

GET
Recommend items to user

See doc for client: Python Ruby Java Node.js PHP .NET

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>
}), callback);
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>
  )
)
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>
  })
)
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)
);
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>
}), callback);
<?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>
  ])
);
?>
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>
  )
);
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>

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

The most typical use cases are recommendations at homepage, in some “Picked just for you” section or in email.

The returned items are sorted by relevance (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 case of very long ReQL filter) - query parameters then become body parameters.

Since version 2.0.0

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

2.0.0

ID of your database.

userId

path

string

Yes

2.0.0

ID of the user for whom personalized recommendations are to be generated.

count

query

integer

Yes

2.0.0

Number of items to be recommended (N for the top-N recommendation).

scenario

query

string

No

2.0.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 performance of each scenario in the Admin UI separately, so you can check how well each application performs.

The AI which optimizes models in order to get the best results may optimize different scenarios separately, or even use different models in each of the scenarios.

cascadeCreate

query

boolean

No

2.0.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.

returnProperties

query

boolean

No

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 for easy displaying of 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

query

array

No

2.0.0

Allows to specify, 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

query

string

No

2.0.0

Boolean-returning ReQL expression which allows you to filter recommended items based on the values of their attributes.

Filters can be also assigned to a scenario in the Admin UI.

booster

query

string

No

2.0.0

Number-returning ReQL expression which allows you to boost recommendation rate of some items based on the values of their attributes.

Boosters can be also assigned to a scenario in the Admin UI.

logic

query

string / object

No

2.4.0

Logic specifies particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. See this section for 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 be also set to a scenario in the Admin UI.

minRelevance

query

string

No

2.0.0

Expert option Specifies the threshold of how much relevant must the recommended items be to the user. Possible values one of: “low”, “medium”, “high”. The default value is “low”, meaning that the system attempts to recommend number of items equal to count at any cost. If there are not enough data (such as interactions or item properties), this may even lead to bestseller-based recommendations to be appended to reach the full count. This behavior may be suppressed by using “medium” or “high” values. In such case, the system only recommends items of at least the requested relevance, and may return less than count items when there is not enough data to fulfill it.

rotationRate

query

number

No

2.0.0

Expert option If your users browse the system in real-time, it may easily happen that you wish to offer them recommendations multiple times. Here comes the question: how much should the recommendations change? Should they remain the same, or should they rotate? Recombee API allows you to control this per-request in backward fashion. You may penalize an item for being recommended in the near past. For the specific user, rotationRate=1 means maximal rotation, rotationRate=0 means absolutely no rotation. You may also use, for example rotationRate=0.2 for only slight rotation of recommended items. Default: 0.1.

rotationTime

query

number

No

2.0.0

Expert option Taking rotationRate into account, specifies how long time it takes to an item to recover from the penalization. For example, rotationTime=7200.0 means that items recommended less than 2 hours ago are penalized. Default: 7200.0.

Responses

Response

Description

200

successful operation

Example:

{
  "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 are not valid ReQL expressions, filter expression does not return boolean, booster does not return double or integer.

401

Invalid or missing authentication details.

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.

405

Invalid HTTP method.

Recommend items to item

GET
Recommend items to item

See doc for client: Python Ruby Java Node.js PHP .NET

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>,
  'userImpact': <number>,
  'minRelevance': <string>,
  'rotationRate': <number>,
  'rotationTime': <number>
}), callback);
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>,
    user_impact=<number>,
    min_relevance=<string>,
    rotation_rate=<number>,
    rotation_time=<number>
  )
)
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>,
    :user_impact => <number>,
    :min_relevance => <string>,
    :rotation_rate => <number>,
    :rotation_time => <number>
  })
)
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)
  .setUserImpact(double userImpact)
  .setMinRelevance(String minRelevance)
  .setRotationRate(double rotationRate)
  .setRotationTime(double rotationTime)
);
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>,
  'userImpact': <number>,
  'minRelevance': <string>,
  'rotationRate': <number>,
  'rotationTime': <number>
}), callback);
<?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)>,
    'userImpact' => <number>,
    'minRelevance' => <string>,
    'rotationRate' => <number>,
    'rotationTime' => <number>
  ])
);
?>
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>,
    userImpact: <double>,
    minRelevance: <string>,
    rotationRate: <double>,
    rotationTime: <double>
  )
);
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>&userImpact=<number>&minRelevance=<string>&rotationRate=<number>&rotationTime=<number>

Recommends set of items that are somehow related to one given item, X. Typical scenario is when user A is viewing X. Then you may display items to the user that he might be also 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 (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 case of very long ReQL filter) - query parameters then become body parameters.

Since version 2.0.0

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

2.0.0

ID of your database.

itemId

path

string

Yes

2.0.0

ID of the item for which the recommendations are to be generated.

targetUserId

query

string

Yes

2.0.0

ID of the user who will see the recommendations.

Specifying the targetUserId is beneficial because:

  • It makes the recommendations personalized

  • Allows the calculation of Actions and Conversions in the graphical user interface, as Recombee can pair the user who got recommendations and who afterwards viewed/purchased an item.

If you insist on not specifying the user, pass null (None, nil, NULL etc. depending on language) to targetUserId. Do not create some special dummy user for getting recommendations, as it could mislead the recommendation models, and result in wrong recommendations.

For anonymous/unregistered users it is possible to use for example their session ID.

count

query

integer

Yes

2.0.0

Number of items to be recommended (N for the top-N recommendation).

scenario

query

string

No

2.0.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 performance of each scenario in the Admin UI separately, so you can check how well each application performs.

The AI which optimizes models in order to get the best results may optimize different scenarios separately, or even use different models in each of the scenarios.

cascadeCreate

query

boolean

No

2.0.0

If item of given itemId or user of given targetUserId doesn’t exist in the database, it creates the missing entity/entities and returns some (non-personalized) recommendations. This allows for example rotations in the following recommendations for the user of given targetUserId, as the user will be already known to the system.

returnProperties

query

boolean

No

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 for easy displaying of the recommended items to the user.

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

query

array

No

2.0.0

Allows to specify, 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
}

filter

query

string

No

2.0.0

Boolean-returning ReQL expression which allows you to filter recommended items based on the values of their attributes.

Filters can be also assigned to a scenario in the Admin UI.

booster

query

string

No

2.0.0

Number-returning ReQL expression which allows you to boost recommendation rate of some items based on the values of their attributes.

Boosters can be also assigned to a scenario in the Admin UI.

logic

query

string / object

No

2.4.0

Logic specifies particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. See this section for 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 be also set to a scenario in the Admin UI.

userImpact

query

number

No

2.0.0

Expert option If targetUserId parameter is present, the recommendations are biased towards the given user. Using userImpact, you may control this bias. For an extreme case of userImpact=0.0, the interactions made by the user are not taken into account at all (with the exception of history-based blacklisting), for userImpact=1.0, you’ll get user-based recommendation. The default value is 0.

minRelevance

query

string

No

2.0.0

Expert option If the targetUserId is provided: Specifies the threshold of how much relevant must the recommended items be to the user. Possible values one of: “low”, “medium”, “high”. The default value is “low”, meaning that the system attempts to recommend number of items equal to count at any cost. If there are not enough data (such as interactions or item properties), this may even lead to bestseller-based recommendations to be appended to reach the full count. This behavior may be suppressed by using “medium” or “high” values. In such case, the system only recommends items of at least the requested relevance, and may return less than count items when there is not enough data to fulfill it.

rotationRate

query

number

No

2.0.0

Expert option If the targetUserId is provided: If your users browse the system in real-time, it may easily happen that you wish to offer them recommendations multiple times. Here comes the question: how much should the recommendations change? Should they remain the same, or should they rotate? Recombee API allows you to control this per-request in backward fashion. You may penalize an item for being recommended in the near past. For the specific user, rotationRate=1 means maximal rotation, rotationRate=0 means absolutely no rotation. You may also use, for example rotationRate=0.2 for only slight rotation of recommended items.

rotationTime

query

number

No

2.0.0

Expert option If the targetUserId is provided: Taking rotationRate into account, specifies how long time it takes to an item to recover from the penalization. For example, rotationTime=7200.0 means that items recommended less than 2 hours ago are penalized.

Responses

Response

Description

200

successful operation

Example:

{
  "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 are not valid ReQL expressions, filter expression does not return boolean, booster does not return double or integer.

401

Invalid or missing authentication details.

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 you URL.

405

Invalid HTTP method.

Recommend next items

GET
Recommend next items

See doc for client: Python Ruby Java Node.js PHP .NET

client.send(new recombee.RecommendNextItems(recommId, count), callback);
result = client.send(RecommendNextItems(recomm_id, count))
result = client.send(RecommendNextItems.new(recommId, count))
RecommendationResponse result = client.send(new RecommendNextItems(String recommId, long count));
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.RecommendNextItems(recommId, count), callback);
<?php
$result = $client->send(new RecommendNextItems($recomm_id, $count));
?>
RecommendationResponse result = client.Send(RecommendNextItems(string recommId, long count));
GET /{databaseId}/recomms/next/items/{recommId}?count=<integer>

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 a next page.

It accepts recommId of a base recommendation request (e.g. request from the first page) and 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.

Since version 3.1.0

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

3.1.0

ID of your database.

recommId

path

string

Yes

3.1.0

ID of the base recommendation request for which next recommendations should be returned

count

query

integer

Yes

3.1.0

Number of items to be recommended

Responses

Response

Description

200

successful operation

Example:

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

400

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

401

Invalid or missing authentication details.

404

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

405

Invalid HTTP method.

Recommend users to user

GET
Recommend users to user

See doc for client: Python Ruby Java Node.js PHP .NET

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>
  )
)
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>
  })
)
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)
);
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>
}), callback);
<?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)>
  ])
);
?>
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>
  )
);
GET /{databaseId}/recomms/users/{userId}/users/?count=<integer>&scenario=<string>&cascadeCreate=<boolean>&returnProperties=<boolean>&includedProperties=<array>&filter=<string>&booster=<string>&logic=<string / Object>

Get similar users as some 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 case of very long ReQL filter) - query parameters then become body parameters.

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

Since version 2.0.0

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

2.0.0

ID of your database.

userId

path

string

Yes

2.0.0

User to whom we find similar users

count

query

integer

Yes

2.0.0

Number of users to be recommended (N for the top-N recommendation).

scenario

query

string

No

2.0.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 performance of each scenario in the Admin UI separately, so you can check how well each application performs.

The AI which optimizes models in order to get the best results may optimize different scenarios separately, or even use different models in each of the scenarios.

cascadeCreate

query

boolean

No

2.0.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.

returnProperties

query

boolean

No

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 for easy displaying 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

query

array

No

2.0.0

Allows to specify, 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
}

filter

query

string

No

2.0.0

Boolean-returning ReQL expression which allows you to filter recommended items based on the values of their attributes.

Filters can be also assigned to a scenario in the Admin UI.

booster

query

string

No

2.0.0

Number-returning ReQL expression which allows you to boost recommendation rate of some items based on the values of their attributes.

Boosters can be also assigned to a scenario in the Admin UI.

logic

query

string / object

No

2.4.0

Logic specifies particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. See this section for 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 be also set to a scenario in the Admin UI.

Responses

Response

Description

200

successful operation

Example:

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

400

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

401

Invalid or missing authentication details.

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.

405

Invalid HTTP method.

Recommend users to item

GET
Recommend users to item

See doc for client: Python Ruby Java Node.js PHP .NET

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>
  )
)
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>
  })
)
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)
);
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>
}), callback);
<?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)>
  ])
);
?>
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>
  )
);
GET /{databaseId}/recomms/items/{itemId}/users/?count=<integer>&scenario=<string>&cascadeCreate=<boolean>&returnProperties=<boolean>&includedProperties=<array>&filter=<string>&booster=<string>&logic=<string / Object>

Recommend users that are likely to be interested in a given item.

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

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

Since version 2.0.0

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

2.0.0

ID of your database.

itemId

path

string

Yes

2.0.0

ID of the item for which the recommendations are to be generated.

count

query

integer

Yes

2.0.0

Number of items to be recommended (N for the top-N recommendation).

scenario

query

string

No

2.0.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 performance of each scenario in the Admin UI separately, so you can check how well each application performs.

The AI which optimizes models in order to get the best results may optimize different scenarios separately, or even use different models in each of the scenarios.

cascadeCreate

query

boolean

No

2.0.0

If item of given itemId doesn’t exist in the database, it creates the missing item.

returnProperties

query

boolean

No

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 for easy displaying the recommended users.

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

query

array

No

2.0.0

Allows to specify, 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
}

filter

query

string

No

2.0.0

Boolean-returning ReQL expression which allows you to filter recommended items based on the values of their attributes.

Filters can be also assigned to a scenario in the Admin UI.

booster

query

string

No

2.0.0

Number-returning ReQL expression which allows you to boost recommendation rate of some items based on the values of their attributes.

Boosters can be also assigned to a scenario in the Admin UI.

logic

query

string / object

No

2.4.0

Logic specifies particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. See this section for 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 be also set to a scenario in the Admin UI.

Responses

Response

Description

200

successful operation

Example:

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

400

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

401

Invalid or missing authentication details.

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 you URL.

405

Invalid HTTP method.

User based recommendation [deprecated]

GET
User based recommendation [deprecated]

See doc for client: Python Ruby Java Node.js PHP .NET

result = client.send(UserBasedRecommendation(user_id, count,
    # optional parameters:
    filter=<string>,
    booster=<string>,
    cascade_create=<boolean>,
    scenario=<string>,
    return_properties=<boolean>,
    included_properties=<array>,
    min_relevance=<string>,
    rotation_rate=<number>,
    rotation_time=<number>
  )
)
result = client.send(UserBasedRecommendation.new(userId, count, {
    # optional parameters:
    :filter => <string>,
    :booster => <string>,
    :cascade_create => <boolean>,
    :scenario => <string>,
    :return_properties => <boolean>,
    :included_properties => <array>,
    :min_relevance => <string>,
    :rotation_rate => <number>,
    :rotation_time => <number>
  })
)
Recommendation[] result = client.send(new UserBasedRecommendation(String userId, long count)
  .setFilter(String filter)
  .setBooster(String booster)
  .setCascadeCreate(boolean cascadeCreate)
  .setScenario(String scenario)
  .setReturnProperties(boolean returnProperties)
  .setIncludedProperties(String[] includedProperties)
  .setMinRelevance(String minRelevance)
  .setRotationRate(double rotationRate)
  .setRotationTime(double rotationTime)
);
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.UserBasedRecommendation(userId, count, {
  // optional parameters:
  'filter': <string>,
  'booster': <string>,
  'cascadeCreate': <boolean>,
  'scenario': <string>,
  'returnProperties': <boolean>,
  'includedProperties': <array>,
  'minRelevance': <string>,
  'rotationRate': <number>,
  'rotationTime': <number>
}), callback);
<?php
$result = $client->send(new UserBasedRecommendation($user_id, $count, [
    // optional parameters:
    'filter' => <string>,
    'booster' => <string>,
    'cascadeCreate' => <boolean>,
    'scenario' => <string>,
    'returnProperties' => <boolean>,
    'includedProperties' => <array>,
    'minRelevance' => <string>,
    'rotationRate' => <number>,
    'rotationTime' => <number>
  ])
);
?>
IEnumerable<Recommendation> result = client.Send(UserBasedRecommendation(string userId, long count,
    // optional parameters:
    filter: <string>,
    booster: <string>,
    cascadeCreate: <bool>,
    scenario: <string>,
    returnProperties: <bool>,
    includedProperties: <string[]>,
    minRelevance: <string>,
    rotationRate: <double>,
    rotationTime: <double>
  )
);
GET /{databaseId}/users/{userId}/recomms/?count=<integer>&filter=<string>&booster=<string>&cascadeCreate=<boolean>&scenario=<string>&returnProperties=<boolean>&includedProperties=<array>&minRelevance=<string>&rotationRate=<number>&rotationTime=<number>

Warning

Deprecated since version 2.0.0. Use Recommend items to user instead.

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

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

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

userId

path

string

Yes

ID of the user for whom the personalized recommendations are to be generated.

count

query

integer

Yes

Number of items to be recommended (N for the top-N recommendation).

filter

query

string

No

Boolean-returning ReQL expression which allows you to filter recommended items based on the values of their attributes.

booster

query

string

No

Number-returning ReQL expression which allows you to boost recommendation rate of some items based on the values of their attributes.

cascadeCreate

query

boolean

No

1.2.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.

scenario

query

string

No

1.2.0

Scenario defines a particular application of recommendations. It can be for example “homepage”, “cart” or “emailing”. You can see each scenario in the UI separately, so you can check how well each application performs. The AI which optimizes models in order to get the best results may optimize different scenarios separately, or even use different models in each of the scenarios.

returnProperties

query

boolean

No

1.2.2

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 for easy displaying of the recommended items to the user.

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

query

array

No

1.2.2

Allows to specify, 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
  }
]

minRelevance

query

string

No

Expert option Specifies the threshold of how much relevant must the recommended items be to the user. Possible values one of: “low”, “medium”, “high”. The default value is “low”, meaning that the system attempts to recommend number of items equal to count at any cost. If there are not enough data (such as interactions or item properties), this may even lead to bestseller-based recommendations to be appended to reach the full count. This behavior may be suppressed by using “medium” or “high” values. In such case, the system only recommends items of at least the requested qualit, and may return less than count items when there is not enough data to fulfill it.

rotationRate

query

number

No

Expert option If your users browse the system in real-time, it may easily happen that you wish to offer them recommendations multiple times. Here comes the question: how much should the recommendations change? Should they remain the same, or should they rotate? Recombee API allows you to control this per-request in backward fashion. You may penalize an item for being recommended in the near past. For the specific user, rotationRate=1 means maximal rotation, rotationRate=0 means absolutely no rotation. You may also use, for example rotationRate=0.2 for only slight rotation of recommended items. Default: 0.1.

rotationTime

query

number

No

Expert option Taking rotationRate into account, specifies how long time it takes to an item to recover from the penalization. For example, rotationTime=7200.0 means that items recommended less than 2 hours ago are penalized. Default: 7200.0.

Responses

Response

Description

200

successful operation

Example:

[
  "item-146",
  "item-462",
  "item-463",
  "item-79"
]

400

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

401

Invalid or missing authentication details.

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.

405

Invalid HTTP method.

Item based recommendation [deprecated]

GET
Item based recommendation [deprecated]

See doc for client: Python Ruby Java Node.js PHP .NET

result = client.send(ItemBasedRecommendation(item_id, count,
    # optional parameters:
    target_user_id=<string>,
    user_impact=<number>,
    filter=<string>,
    booster=<string>,
    cascade_create=<boolean>,
    scenario=<string>,
    return_properties=<boolean>,
    included_properties=<array>,
    min_relevance=<string>,
    rotation_rate=<number>,
    rotation_time=<number>
  )
)
result = client.send(ItemBasedRecommendation.new(itemId, count, {
    # optional parameters:
    :target_user_id => <string>,
    :user_impact => <number>,
    :filter => <string>,
    :booster => <string>,
    :cascade_create => <boolean>,
    :scenario => <string>,
    :return_properties => <boolean>,
    :included_properties => <array>,
    :min_relevance => <string>,
    :rotation_rate => <number>,
    :rotation_time => <number>
  })
)
Recommendation[] result = client.send(new ItemBasedRecommendation(String itemId, long count)
  .setTargetUserId(String targetUserId)
  .setUserImpact(double userImpact)
  .setFilter(String filter)
  .setBooster(String booster)
  .setCascadeCreate(boolean cascadeCreate)
  .setScenario(String scenario)
  .setReturnProperties(boolean returnProperties)
  .setIncludedProperties(String[] includedProperties)
  .setMinRelevance(String minRelevance)
  .setRotationRate(double rotationRate)
  .setRotationTime(double rotationTime)
);
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ItemBasedRecommendation(itemId, count, {
  // optional parameters:
  'targetUserId': <string>,
  'userImpact': <number>,
  'filter': <string>,
  'booster': <string>,
  'cascadeCreate': <boolean>,
  'scenario': <string>,
  'returnProperties': <boolean>,
  'includedProperties': <array>,
  'minRelevance': <string>,
  'rotationRate': <number>,
  'rotationTime': <number>
}), callback);
<?php
$result = $client->send(new ItemBasedRecommendation($item_id, $count, [
    // optional parameters:
    'targetUserId' => <string>,
    'userImpact' => <number>,
    'filter' => <string>,
    'booster' => <string>,
    'cascadeCreate' => <boolean>,
    'scenario' => <string>,
    'returnProperties' => <boolean>,
    'includedProperties' => <array>,
    'minRelevance' => <string>,
    'rotationRate' => <number>,
    'rotationTime' => <number>
  ])
);
?>
IEnumerable<Recommendation> result = client.Send(ItemBasedRecommendation(string itemId, long count,
    // optional parameters:
    targetUserId: <string>,
    userImpact: <double>,
    filter: <string>,
    booster: <string>,
    cascadeCreate: <bool>,
    scenario: <string>,
    returnProperties: <bool>,
    includedProperties: <string[]>,
    minRelevance: <string>,
    rotationRate: <double>,
    rotationTime: <double>
  )
);
GET /{databaseId}/items/{itemId}/recomms/?count=<integer>&targetUserId=<string>&userImpact=<number>&filter=<string>&booster=<string>&cascadeCreate=<boolean>&scenario=<string>&returnProperties=<boolean>&includedProperties=<array>&minRelevance=<string>&rotationRate=<number>&rotationTime=<number>

Warning

Deprecated since version 2.0.0. Use Recommend items to item instead.

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

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

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

itemId

path

string

Yes

ID of the item for which the recommendations are to be generated.

count

query

integer

Yes

Number of items to be recommended (N for the top-N recommendation).

targetUserId

query

string

No

ID of the user who will see the recommendations.

Specifying the targetUserId is beneficial because:

  • It makes the recommendations personalized

  • Allows the calculation of Actions and Conversions in the graphical user interface, as Recombee can pair the user who got recommendations and who afterwards viewed/purchased an item.

For the above reasons, we encourage you to set the targetUserId even for anonymous/unregistered users (i.e. use their session ID).

userImpact

query

number

No

If targetUserId parameter is present, the recommendations are biased towards the user given. Using userImpact, you may control this bias. For an extreme case of userImpact=0.0, the interactions made by the user are not taken into account at all (with the exception of history-based blacklisting), for userImpact=1.0, you’ll get user-based recommendation. The default value is 0.

filter

query

string

No

Boolean-returning ReQL expression which allows you to filter recommended items based on the values of their attributes.

booster

query

string

No

Number-returning ReQL expression which allows you to boost recommendation rate of some items based on the values of their attributes.

cascadeCreate

query

boolean

No

1.2.0

If item of given itemId or user of given targetUserId doesn’t exist in the database, it creates the missing enity/entities and returns some (non-personalized) recommendations. This allows for example rotations in the following recommendations for the user of given targetUserId, as the user will be already known to the system.

scenario

query

string

No

1.2.0

Scenario defines a particular application of recommendations. It can be for example “homepage”, “cart” or “emailing”. You can see each scenario in the UI separately, so you can check how well each application performs. The AI which optimizes models in order to get the best results may optimize different scenarios separately, or even use different models in each of the scenarios.

returnProperties

query

boolean

No

1.2.2

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 for easy displaying of the recommended items to the user.

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

query

array

No

1.2.2

Allows to specify, 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
  }
]

minRelevance

query

string

No

Expert option If the targetUserId is provided: Specifies the threshold of how much relevant must the recommended items be to the user. Possible values one of: “low”, “medium”, “high”. The default value is “low”, meaning that the system attempts to recommend number of items equal to count at any cost. If there are not enough data (such as interactions or item properties), this may even lead to bestseller-based recommendations to be appended to reach the full count. This behavior may be suppressed by using “medium” or “high” values. In such case, the system only recommends items of at least the requested qualit, and may return less than count items when there is not enough data to fulfill it.

rotationRate

query

number

No

Expert option If the targetUserId is provided: If your users browse the system in real-time, it may easily happen that you wish to offer them recommendations multiple times. Here comes the question: how much should the recommendations change? Should they remain the same, or should they rotate? Recombee API allows you to control this per-request in backward fashion. You may penalize an item for being recommended in the near past. For the specific user, rotationRate=1 means maximal rotation, rotationRate=0 means absolutely no rotation. You may also use, for example rotationRate=0.2 for only slight rotation of recommended items. Default: 0.01.

rotationTime

query

number

No

Expert option If the targetUserId is provided: Taking rotationRate into account, specifies how long time it takes to an item to recover from the penalization. For example, rotationTime=7200.0 means that items recommended less than 2 hours ago are penalized. Default: 7200.0.

Responses

Response

Description

200

successful operation

Example:

[
  "item-865",
  "item-460",
  "item-121",
  "item-1555"
]

400

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

401

Invalid or missing authentication details.

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 you URL.

405

Invalid HTTP method.

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 also series may be added into another series, resulting in “meta-series”. This may be useful for modeling ordered seasons of a TV show, episodes of which are themselves ordered.

Series definition

Methods for managing series - creating, listing, and deleting them.

Add series

PUT
Add series

See doc for client: Python Ruby Java Node.js PHP .NET

client.send(AddSeries(series_id))
client.send(AddSeries.new(seriesId))
client.send(new AddSeries(String seriesId));
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.AddSeries(seriesId), callback);
<?php
$client->send(new AddSeries($series_id));
?>
client.Send(AddSeries(string seriesId));
PUT /{databaseId}/series/{seriesId}

Creates new series in the database.

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

seriesId

path

string

Yes

ID of the series to be created.

Responses

Response

Description

201

successful operation

400

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

401

Invalid or missing authentication details.

404

Invalid URL.

405

Invalid HTTP method.

409

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

Delete series

DELETE
Delete series

See doc for client: Python Ruby Java Node.js PHP .NET

client.send(DeleteSeries(series_id))
client.send(DeleteSeries.new(seriesId))
client.send(new DeleteSeries(String seriesId));
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.DeleteSeries(seriesId), callback);
<?php
$client->send(new DeleteSeries($series_id));
?>
client.Send(DeleteSeries(string seriesId));
DELETE /{databaseId}/series/{seriesId}

Deletes the series of given seriesId from the database.

Deleting a series will only delete assignment of items to it, not the items themselves!

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

seriesId

path

string

Yes

ID of the series to be deleted.

Responses

Response

Description

200

successful operation

400

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

401

Invalid or missing authentication details.

404

Series of given seriesId not present in the database. In many cases, you may consider this code 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 you URL.

405

Invalid HTTP method.

List series

GET
List series

See doc for client: Python Ruby Java Node.js PHP .NET

result = client.send(ListSeries())
result = client.send(ListSeries.new())
Series[] result = client.send(new ListSeries());
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ListSeries(), callback);
<?php
$result = $client->send(new ListSeries());
?>
IEnumerable<Series> result = client.Send(ListSeries());
GET /{databaseId}/series/list/

Gets the list of all the series currently present in the database.

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

Responses

Response

Description

200

successful operation

Example:

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

401

Invalid or missing authentication details.

404

Invalid URL.

405

Invalid HTTP method.

Series items

Methods for adding items (or even series themselves) to series.

List series items

GET
List series items

See doc for client: Python Ruby Java Node.js PHP .NET

result = client.send(ListSeriesItems(series_id))
result = client.send(ListSeriesItems.new(seriesId))
SeriesItem[] result = client.send(new ListSeriesItems(String seriesId));
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.ListSeriesItems(seriesId), callback);
<?php
$result = $client->send(new ListSeriesItems($series_id));
?>
IEnumerable<SeriesItem> result = client.Send(ListSeriesItems(string seriesId));
GET /{databaseId}/series/{seriesId}/items/

List all the items present in the given series, sorted according to their time index values.

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

seriesId

path

string

Yes

ID of the series items of which are to be listed.

Responses

Response

Description

200

successful operation

Example:

[
  {
    "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_-:@.]+$.

401

Invalid or missing authentication details.

404

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

405

Invalid HTTP method.

Insert to series

POST
Insert to series

See doc for client: Python Ruby Java Node.js PHP .NET

client.send(InsertToSeries(series_id, item_type, item_id, time,
    # optional parameters:
    cascade_create=<boolean>
  )
)
client.send(InsertToSeries.new(seriesId, itemType, itemId, time, {
    # optional parameters:
    :cascade_create => <boolean>
  })
)
client.send(new InsertToSeries(String seriesId, String itemType, String itemId, double time)
  .setCascadeCreate(boolean cascadeCreate)
);
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.InsertToSeries(seriesId, itemType, itemId, time, {
  // optional parameters:
  'cascadeCreate': <boolean>
}), callback);
<?php
$client->send(new InsertToSeries($series_id, $item_type, $item_id, $time, [
    // optional parameters:
    'cascadeCreate' => <boolean>
  ])
);
?>
client.Send(InsertToSeries(string seriesId, string itemType, string itemId, double time,
    // optional parameters:
    cascadeCreate: <bool>
  )
);
POST /{databaseId}/series/{seriesId}/items/
Body (application/json):
{
  "itemType" => <string>,
  "itemId" => <string>,
  "time" => <number>,
  "cascadeCreate" => <boolean>
}

Inserts an existing item/series into series of given seriesId at position determined by time.

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

seriesId

path

string

Yes

ID of the series to be inserted into.

itemType

body

string

Yes

item iff the regular item from the catalog is to be inserted, series iff series is inserted as the item.

itemId

body

string

Yes

ID of the item iff itemType is item. ID of the series iff itemType is series.

time

body

number

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

body

boolean

No

Indicates that any non-existing entity specified within the request should be created (as is corresponding PUT requests were invoked). This concerns both the seriesId and the itemId. If cascadeCreate is set true, the behavior also depends on the itemType. Either item or series may be created if not present in the database.

Responses

Response

Description

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.

401

Invalid or missing authentication details.

404

Series of given seriesId not present in the database. Item of given itemId is not present in the database if itemType is item. Series of 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 you URL.

405

Invalid HTTP method.

409

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 success – it only tells you that nothing has been written to the database.

Remove from series

DELETE
Remove from series

See doc for client: Python Ruby Java Node.js PHP .NET

client.send(RemoveFromSeries(series_id, item_type, item_id, time))
client.send(RemoveFromSeries.new(seriesId, itemType, itemId, time))
client.send(new RemoveFromSeries(String seriesId, String itemType, String itemId, double time));
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.RemoveFromSeries(seriesId, itemType, itemId, time), callback);
<?php
$client->send(new RemoveFromSeries($series_id, $item_type, $item_id, $time));
?>
client.Send(RemoveFromSeries(string seriesId, string itemType, string itemId, double time));
DELETE /{databaseId}/series/{seriesId}/items/?itemType=<string>&itemId=<string>&time=<number>

Removes an existing series item from the series.

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

seriesId

path

string

Yes

ID of the series from which a series item is to be removed.

itemType

query

string

Yes

Type of the item to be removed.

itemId

query

string

Yes

ID of the item iff itemType is item. ID of the series iff itemType is series.

time

query

number

Yes

Time index of the item to be removed.

Responses

Response

Description

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.

401

Invalid or missing authentication details.

404

Series of given seriesId not present in the database. Series item given by triplet (itemType, itemId, time) not present in series of seriesId. If there is no additional info in the JSON response, you probably have an error in you URL.

405

Invalid HTTP method.

Miscellaneous

Reset database

DELETE
Reset database

See doc for client: Python Ruby Java Node.js PHP .NET

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

client.send(new rqs.ResetDatabase(), callback);
<?php
$client->send(new ResetDatabase());
?>
client.Send(ResetDatabase());
DELETE /{databaseId}/

Completely erases all your data, including items, item properties, series, user database, purchases, ratings, detail views, and bookmarks. Make sure the request to be never executed in production environment! Resetting your database is irreversible.

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

Responses

Response

Description

200

successful operation

401

Invalid or missing authentication details.

404

Invalid URL.

405

Invalid HTTP method.

Batch

POST
Batch

See doc for client: Python Ruby Java Node.js PHP .NET

result = client.send(Batch(requests,
    # optional parameters:
    distinct_recomms=<boolean>
  )
)
result = client.send(Batch.new(requests, {
    # optional parameters:
    :distinct_recomms => <boolean>
  })
)
BatchResponse[] result = client.send(new Batch(Request[] requests)
  .setDistinctRecomms(boolean distinctRecomms)
);
var recombee = require('recombee-api-client');
var rqs = recombee.requests;

client.send(new rqs.Batch(requests, {
  // optional parameters:
  'distinctRecomms': <boolean>
}), callback);
<?php
$result = $client->send(new Batch($requests, [
    // optional parameters:
    'distinctRecomms' => <boolean>
  ])
);
?>
IEnumerable<BatchResponse> result = client.Send(Batch(IEnumerable<Request> requests,
    // optional parameters:
    distinctRecomms: <bool>
  )
);
POST /{databaseId}/batch/
Body (application/json):
{
  "requests" => <array>,
  "distinctRecomms" => <boolean>
}

In many cases, it may be desirable to execute multiple requests at once. For example, when synchronizing the catalog of items in a periodical manner, you would have to execute a sequence of thousands of separate POST requests, which is very ineffective and may take a very long time to complete. Most notably, network latencies can make execution of such sequence very slow and even if executed in multiple parallel threads, there will still be unreasonable overhead caused by the HTTP(s). To avoid the mentioned problems, batch processing may be used, encapsulating a sequence of requests into a single HTTPS request.

Batch processing allows you to submit arbitrary sequence of requests - 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.

The Batch request classes in the SDKs accept an array of the Requests in their constructors (see page dedicated to the particular SDK for details).

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)

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": 5
      }
    }
  ]
}

Note that:

  • 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,

  • 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,

  • currently, batch size is limited to 10,000 requests; if you wish to execute even larger number of requests, please split the batch into multiple parts. Client libraries do the splitting automatically.

Parameters

Parameter

Located in

Type

Required

Since version

databaseId

path

string

Yes

ID of your database.

requests

body

array

Yes

JSON array containing the requests.

distinctRecomms

body

boolean

No

1.2.4

Makes all the recommended items for a certain user distinct among multiple recommendation requests in the batch.

Responses

Response

Description

200

successful operation

Example:

[
  {
    "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"
        },
        {
          "id": "item-135"
        },
        {
          "id": "item-482"
        }
      ],
      "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.

401

Invalid or missing authentication details.

404

There is at least one request in the batch with invalid (non-existing) URL. Is such a case, the batch as a whole is not executed and you’ll get HTTP 404, because the batch is apriori erroneous.

405

Invalid HTTP method.

413

Too large batch (containing more than 10,000 requests).