User-Item Interactions

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

Detail Views

post

Add Detail View

Allowed on Client-Side

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

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

Copy

Initialization

client.send(new recombee.AddDetailView(userId, itemId, {
  // optional parameters:
  timestamp: '2022-05-13T18:25:43Z',                 // string / number
  duration: 35,                                      // integer
  cascadeCreate: true,                               // boolean
  recommId: 'ce52ada4-e4d9-4885-943c-407db2dee837',  // string
  additionalData: {},                                // Object
  autoPresented: false,                              // boolean
}));

Parameters

databaseId

String

Located in: path

Required: Yes

ID of your database.

userId

String

Located in: body

Required: Yes

User who viewed the item

itemId

String

Located in: body

Required: Yes

Viewed item

timestamp

String

Number

Located in: body

Required: No

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

duration

Integer

Located in: body

Required: No

Duration of the view

cascadeCreate

Boolean

Located in: body

Required: No

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

recommId

String

Located in: body

Required: No

Since version: 2.2.0

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

additionalData

Object

Located in: body

Required: No

Since version: 2.3.0

Additional data associated with the interaction. The expected structure is defined for specific use cases and will be provided by the Recombee Support team when applicable.

autoPresented

Boolean

Located in: body

Required: No

Since version: 6.0.0

Indicates whether the item was automatically presented to the user (e.g., in a swiping feed) or explicitly requested by the user (e.g., by clicking on a link). Defaults to false.

Responses

200

Successful operation.

400

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

404

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

409

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

delete

Delete Detail View

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

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new requests.DeleteDetailView(userId, itemId, {
  // optional parameters:
  timestamp: 1652466343,  // number
}));

Calls Limit Per Minute

1000

Parameters

databaseId

String

Located in: path

Required: Yes

ID of your database.

userId

String

Located in: query

Required: Yes

ID of the user who made the detail view.

itemId

String

Located in: query

Required: Yes

ID of the item whose details were viewed.

timestamp

Number

Located in: query

Required: No

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

Responses

200

Successful operation.

400

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

404

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

get

List Item Detail Views

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

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

const result = await client.send(new requests.ListItemDetailViews(itemId));

Calls Limit Per Minute

Parameters

databaseId

String

Located in: path

Required: Yes

ID of your database.

itemId

String

Located in: path

Required: Yes

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

Responses

200

Successful operation.

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

400

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

404

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

get

List User Detail Views

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

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

const result = await client.send(new requests.ListUserDetailViews(userId));

Calls Limit Per Minute

Parameters

databaseId

String

Located in: path

Required: Yes

ID of your database.

userId

String

Located in: path

Required: Yes

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

Responses

200

Successful operation.

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

400

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

404

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

Purchases

post

Add Purchase

Allowed on Client-Side

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

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

Copy

Initialization

client.send(new recombee.AddPurchase(userId, itemId, {
  // optional parameters:
  timestamp: '2022-05-13T18:25:43Z',                 // string / number
  cascadeCreate: true,                               // boolean
  amount: 1,                                         // number
  price: 25.0,                                       // number
  profit: 5.0,                                       // number
  recommId: 'ce52ada4-e4d9-4885-943c-407db2dee837',  // string
  additionalData: {},                                // Object
}));

Parameters

databaseId

String

Located in: path

Required: Yes

ID of your database.

userId

String

Located in: body

Required: Yes

User who purchased the item

itemId

String

Located in: body

Required: Yes

Purchased item

timestamp

String

Number

Located in: body

Required: No

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

cascadeCreate

Boolean

Located in: body

Required: No

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

amount

Number

Located in: body

Required: No

Since version: 1.6.0

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

price

Number

Located in: body

Required: No

Since version: 1.6.0

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

profit

Number

Located in: body

Required: No

Since version: 1.6.0

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

recommId

String

Located in: body

Required: No

Since version: 2.2.0

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

additionalData

Object

Located in: body

Required: No

Since version: 2.3.0

Additional data associated with the interaction. The expected structure is defined for specific use cases and will be provided by the Recombee Support team when applicable.

Responses

200

Successful operation.

400

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

404

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

409

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

delete

Delete Purchase

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

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new requests.DeletePurchase(userId, itemId, {
  // optional parameters:
  timestamp: 1652466343,  // number
}));

Calls Limit Per Minute

1000

Parameters

databaseId

String

Located in: path

Required: Yes

ID of your database.

userId

String

Located in: query

Required: Yes

ID of the user who made the purchase.

itemId

String

Located in: query

Required: Yes

ID of the item which was purchased.

timestamp

Number

Located in: query

Required: No

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

Responses

200

Successful operation.

400

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

404

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

get

List Item Purchases

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

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

const result = await client.send(new requests.ListItemPurchases(itemId));

Calls Limit Per Minute

Parameters

databaseId

String

Located in: path

Required: Yes

ID of your database.

itemId

String

Located in: path

Required: Yes

ID of the item whose purchases are to be listed.

Responses

200

Successful operation.

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

400

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

404

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

get

List User Purchases

Lists all the purchases ever made by the given user.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

const result = await client.send(new requests.ListUserPurchases(userId));

Calls Limit Per Minute

Parameters

databaseId

String

Located in: path

Required: Yes

ID of your database.

userId

String

Located in: path

Required: Yes

ID of the user whose purchases are to be listed.

Responses

200

Successful operation.

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

400

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

404

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

Ratings

post

Add Rating

Allowed on Client-Side

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

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

Copy

Initialization

client.send(new recombee.AddRating(userId, itemId, rating, {
  // optional parameters:
  timestamp: '2022-05-13T18:25:43Z',                 // string / number
  cascadeCreate: true,                               // boolean
  recommId: 'ce52ada4-e4d9-4885-943c-407db2dee837',  // string
  additionalData: {},                                // Object
}));

Parameters

databaseId

String

Located in: path

Required: Yes

ID of your database.

userId

String

Located in: body

Required: Yes

User who submitted the rating

itemId

String

Located in: body

Required: Yes

Rated item

timestamp

String

Number

Located in: body

Required: No

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

rating

Number

Located in: body

Required: Yes

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

cascadeCreate

Boolean

Located in: body

Required: No

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

recommId

String

Located in: body

Required: No

Since version: 2.2.0

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

additionalData

Object

Located in: body

Required: No

Since version: 2.3.0

Additional data associated with the interaction. The expected structure is defined for specific use cases and will be provided by the Recombee Support team when applicable.

Responses

200

Successful operation.

400

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

404

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

409

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

delete

Delete Rating

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

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new requests.DeleteRating(userId, itemId, {
  // optional parameters:
  timestamp: 1652466343,  // number
}));

Calls Limit Per Minute

1000

Parameters

databaseId

String

Located in: path

Required: Yes

ID of your database.

userId

String

Located in: query

Required: Yes

ID of the user who rated the item.

itemId

String

Located in: query

Required: Yes

ID of the item which was rated.

timestamp

Number

Located in: query

Required: No

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

Responses

200

Successful operation.

400

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

404

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

get

List Item Ratings

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

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

const result = await client.send(new requests.ListItemRatings(itemId));

Calls Limit Per Minute

Parameters

databaseId

String

Located in: path

Required: Yes

ID of your database.

itemId

String

Located in: path

Required: Yes

ID of the item whose ratings are to be listed.

Responses

200

Successful operation.

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

400

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

404

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

get

List User Ratings

Lists all the ratings ever submitted by the given user.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

const result = await client.send(new requests.ListUserRatings(userId));

Calls Limit Per Minute

Parameters

databaseId

String

Located in: path

Required: Yes

ID of your database.

userId

String

Located in: path

Required: Yes

ID of the user whose ratings are to be listed.

Responses

200

Successful operation.

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

400

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

404

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

Cart Additions

post

Add Cart Addition

Allowed on Client-Side

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

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

Copy

Initialization

client.send(new recombee.AddCartAddition(userId, itemId, {
  // optional parameters:
  timestamp: '2022-05-13T18:25:43Z',                 // string / number
  cascadeCreate: true,                               // boolean
  amount: 1,                                         // number
  price: 25.0,                                       // number
  recommId: 'ce52ada4-e4d9-4885-943c-407db2dee837',  // string
  additionalData: {},                                // Object
}));

Parameters

databaseId

String

Located in: path

Required: Yes

ID of your database.

userId

String

Located in: body

Required: Yes

User who added the item to the cart

itemId

String

Located in: body

Required: Yes

Item added to the cart

timestamp

String

Number

Located in: body

Required: No

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

cascadeCreate

Boolean

Located in: body

Required: No

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

amount

Number

Located in: body

Required: No

Since version: 1.6.0

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

price

Number

Located in: body

Required: No

Since version: 1.6.0

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

recommId

String

Located in: body

Required: No

Since version: 2.2.0

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

additionalData

Object

Located in: body

Required: No

Since version: 2.3.0

Additional data associated with the interaction. The expected structure is defined for specific use cases and will be provided by the Recombee Support team when applicable.

Responses

200

Successful operation.

400

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

404

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

409

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

delete

Delete Cart Addition

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

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new requests.DeleteCartAddition(userId, itemId, {
  // optional parameters:
  timestamp: 1652466343,  // number
}));

Calls Limit Per Minute

1000

Parameters

databaseId

String

Located in: path

Required: Yes

ID of your database.

userId

String

Located in: query

Required: Yes

ID of the user who made the cart addition.

itemId

String

Located in: query

Required: Yes

ID of the item which was added to the cart.

timestamp

Number

Located in: query

Required: No

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

Responses

200

Successful operation.

400

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

404

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

get

List Item Cart Additions

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

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

const result = await client.send(new requests.ListItemCartAdditions(itemId));

Calls Limit Per Minute

Parameters

databaseId

String

Located in: path

Required: Yes

ID of your database.

itemId

String

Located in: path

Required: Yes

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

Responses

200

Successful operation.

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

400

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

404

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

get

List User Cart Additions

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

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

const result = await client.send(new requests.ListUserCartAdditions(userId));

Calls Limit Per Minute

Parameters

databaseId

String

Located in: path

Required: Yes

ID of your database.

userId

String

Located in: path

Required: Yes

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

Responses

200

Successful operation.

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

400

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

404

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

Bookmarks

post

Add Bookmark

Allowed on Client-Side

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

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

Copy

Initialization

client.send(new recombee.AddBookmark(userId, itemId, {
  // optional parameters:
  timestamp: '2022-05-13T18:25:43Z',                 // string / number
  cascadeCreate: true,                               // boolean
  recommId: 'ce52ada4-e4d9-4885-943c-407db2dee837',  // string
  additionalData: {},                                // Object
}));

Parameters

databaseId

String

Located in: path

Required: Yes

ID of your database.

userId

String

Located in: body

Required: Yes

User who bookmarked the item

itemId

String

Located in: body

Required: Yes

Bookmarked item

timestamp

String

Number

Located in: body

Required: No

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

cascadeCreate

Boolean

Located in: body

Required: No

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

recommId

String

Located in: body

Required: No

Since version: 2.2.0

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

additionalData

Object

Located in: body

Required: No

Since version: 2.3.0

Additional data associated with the interaction. The expected structure is defined for specific use cases and will be provided by the Recombee Support team when applicable.

Responses

200

Successful operation.

400

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

404

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

409

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

delete

Delete Bookmark

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

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new requests.DeleteBookmark(userId, itemId, {
  // optional parameters:
  timestamp: 1652466343,  // number
}));

Calls Limit Per Minute

1000

Parameters

databaseId

String

Located in: path

Required: Yes

ID of your database.

userId

String

Located in: query

Required: Yes

ID of the user who made the bookmark.

itemId

String

Located in: query

Required: Yes

ID of the item which was bookmarked.

timestamp

Number

Located in: query

Required: No

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

Responses

200

Successful operation.

400

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

404

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

get

List Item Bookmarks

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

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

const result = await client.send(new requests.ListItemBookmarks(itemId));

Calls Limit Per Minute

Parameters

databaseId

String

Located in: path

Required: Yes

ID of your database.

itemId

String

Located in: path

Required: Yes

ID of the item whose bookmarks are to be listed.

Responses

200

Successful operation.

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

400

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

404

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

get

List User Bookmarks

Lists all the bookmarks ever made by the given user.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

const result = await client.send(new requests.ListUserBookmarks(userId));

Calls Limit Per Minute

Parameters

databaseId

String

Located in: path

Required: Yes

ID of your database.

userId

String

Located in: path

Required: Yes

ID of the user whose bookmarks are to be listed.

Responses

200

Successful operation.

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

400

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

404

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

View Portions

post

Set View Portion

Allowed on Client-Side

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

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

Copy

Initialization

client.send(new recombee.SetViewPortion(userId, itemId, portion, {
  // optional parameters:
  sessionId: 'ABAD1D',                               // string
  timestamp: '2022-05-13T18:25:43Z',                 // string / number
  cascadeCreate: true,                               // boolean
  recommId: 'ce52ada4-e4d9-4885-943c-407db2dee837',  // string
  additionalData: {},                                // Object
  autoPresented: false,                              // boolean
  timeSpent: 42,                                     // number
}));

Since version

2.1.0

Parameters

databaseId

String

Located in: path

Required: Yes

Since version: 2.1.0

ID of your database.

userId

String

Located in: body

Required: Yes

Since version: 2.1.0

User who viewed a portion of the item

itemId

String

Located in: body

Required: Yes

Since version: 2.1.0

Viewed item

portion

Number

Located in: body

Required: Yes

Since version: 2.1.0

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

sessionId

String

Located in: body

Required: No

Since version: 2.1.0

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

timestamp

String

Number

Located in: body

Required: No

Since version: 2.1.0

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

cascadeCreate

Boolean

Located in: body

Required: No

Since version: 2.1.0

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

recommId

String

Located in: body

Required: No

Since version: 2.2.0

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

additionalData

Object

Located in: body

Required: No

Since version: 2.3.0

Additional data associated with the interaction. The expected structure is defined for specific use cases and will be provided by the Recombee Support team when applicable.

autoPresented

Boolean

Located in: body

Required: No

Since version: 6.0.0

Indicates whether the item was automatically presented to the user (e.g., in a swiping feed) or explicitly requested by the user (e.g., by clicking on a link). Defaults to false.

timeSpent

Number

Located in: body

Required: No

Since version: 6.0.0

The duration (in seconds) that the user viewed the item. In update requests, this value may only increase and is required only if it has changed.

Responses

200

Successful operation.

400

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

404

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

409

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

delete

Delete View Portion

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

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

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

Since version

2.1.0

Calls Limit Per Minute

1000

Parameters

databaseId

String

Located in: path

Required: Yes

Since version: 2.1.0

ID of your database.

userId

String

Located in: query

Required: Yes

Since version: 2.1.0

ID of the user who rated the item.

itemId

String

Located in: query

Required: Yes

Since version: 2.1.0

ID of the item which was rated.

sessionId

String

Located in: query

Required: No

Since version: 2.1.0

Identifier of a session.

Responses

200

Successful operation.

400

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

404

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

get

List Item View Portions

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

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

const result = await client.send(new requests.ListItemViewPortions(itemId));

Since version

2.1.0

Calls Limit Per Minute

Parameters

databaseId

String

Located in: path

Required: Yes

Since version: 2.1.0

ID of your database.

itemId

String

Located in: path

Required: Yes

Since version: 2.1.0

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

Responses

200

Successful operation.

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

400

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

404

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

get

List User View Portions

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

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

const result = await client.send(new requests.ListUserViewPortions(userId));

Since version

2.1.0

Calls Limit Per Minute

Parameters

databaseId

String

Located in: path

Required: Yes

Since version: 2.1.0

ID of your database.

userId

String

Located in: path

Required: Yes

Since version: 2.1.0

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

Responses

200

Successful operation.

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

400

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

404

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

docs.recombee.com