# Recommendations > Source: https://docs.recombee.com/api/recommendations > For the complete documentation index, see [llms.txt](/llms.txt). # Recommendations Recommendation methods are capable of recommending items (Recommend Items to User, Recommend Items to Item) or users (Recommend Users to Item, Recommend Users to User). See Segmentations section for recommendation endpoints that return Segments (e.g. "recommend categories to a user"). ## Recommending Items Recommendation endpoints that return the Items (content, products, etc.). post ### Recommend Items to User Allowed on Client-Side Based on the user's past interactions (purchases, ratings, etc.) with the items, recommends top-N items that are most likely to be of high value for the given user. The most typical use cases are recommendations on the homepage, in some "Picked just for you" section, or in email. The returned items are sorted by relevance (the first item being the most relevant). Besides the recommended items, also a unique `recommId` is returned in the response. It can be used to: * Let Recombee know that this recommendation was successful (e.g., user clicked one of the recommended items). See [Reported metrics](https://docs.recombee.com/admin_ui#reported-metrics). * Get subsequent recommended items when the user scrolls down (_infinite scroll_) or goes to the next page. See [Recommend Next Items](https://docs.recombee.com/api/recommendations#recommend-next-items). It is also possible to use GET HTTP method - body parameters then become query parameters. ```js const result = await client.send(new recombee.RecommendItemsToUser(userId, count, { // optional parameters: scenario: 'homepage', // string cascadeCreate: true, // boolean returnProperties: true, // boolean includedProperties: ['title', 'price', 'publishedAt'], // array filter: 'price > 50', // string booster: 'if now() - \'publishedAt\' <= 7 * 24 * 3600 then 2 else 1', // string logic: 'recombee:default', // string / Object reqlExpressions: { isInUsersCity: 'context_user["city"] in \'cities\'', }, // Object minRelevance: 'low', // string rotationRate: 0.1, // number rotationTime: 7200.0, // number })); ``` --- Since version 2.0.0 --- #### Parameters databaseId String Located in: **path** Required: **Yes** Since version: **2.0.0** ID of your database. --- userId String Located in: **path** Required: **Yes** Since version: **2.0.0** ID of the user for whom personalized recommendations are to be generated. --- count Integer Located in: **body** Required: **Yes** Since version: **2.0.0** Number of items to be recommended (N for the top-N recommendation). --- scenario String Located in: **body** Required: **No** Since version: **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](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs. The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios. --- cascadeCreate Boolean Located in: **body** Required: **No** Since version: **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 Boolean Located in: **body** Required: **No** Since version: **2.0.0** With `returnProperties=true`, property values of the recommended items are returned along with their IDs in a JSON dictionary. The acquired property values can be used to easily display the recommended items to the user. Example response: ``` { "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837", "recomms": [ { "id": "tv-178", "values": { "description": "4K TV with 3D feature", "categories": ["Electronics", "Televisions"], "price": 342, "url": "myshop.com/tv-178" } }, { "id": "mixer-42", "values": { "description": "Stainless Steel Mixer", "categories": ["Home & Kitchen"], "price": 39, "url": "myshop.com/mixer-42" } } ], "numberNextRecommsCalls": 0 } ``` --- includedProperties Array Located in: **body** Required: **No** Since version: **2.0.0** Allows specifying which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. Example response for `includedProperties=description,price`: ``` { "recommId": "a86ee8d5-cd8e-46d1-886c-8b3771d0520b", "recomms": [ { "id": "tv-178", "values": { "description": "4K TV with 3D feature", "price": 342 } }, { "id": "mixer-42", "values": { "description": "Stainless Steel Mixer", "price": 39 } } ], "numberNextRecommsCalls": 0 } ``` --- filter String Located in: **body** Required: **No** Since version: **2.0.0** Boolean-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to filter recommended items based on the values of their attributes. Filters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). --- booster String Located in: **body** Required: **No** Since version: **2.0.0** Number-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to boost the recommendation rate of some items based on the values of their attributes. Boosters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). --- logic String Object Located in: **body** Required: **No** Since version: **2.4.0** Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. See [this section](https://docs.recombee.com/logics) for a list of available logics and other details. The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users. Logic can also be set to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). --- reqlExpressions Object Located in: **body** Required: **No** Since version: **6.0.0** A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended item. This can be used to compute additional properties of the recommended items that are not stored in the database. The keys are the names of the expressions, and the values are the actual ReQL expressions. Example request: ``` { "reqlExpressions": { "isInUsersCity": "context_user[\"city\"] in 'cities'", "distanceToUser": "earth_distance('location', context_user[\"location\"])" } } ``` Example response: ``` { "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837", "recomms": [ { "id": "restaurant-178", "reqlEvaluations": { "isInUsersCity": true, "distanceToUser": 5200.2 } }, { "id": "bar-42", "reqlEvaluations": { "isInUsersCity": false, "distanceToUser": 2516.0 } } ], "numberNextRecommsCalls": 0 } ``` --- minRelevance String Located in: **body** Required: **No** Since version: **2.0.0** **Expert option:** Specifies the threshold of how 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 a number of items equal to _count_ at any cost. If there is 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 a 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 Number Located in: **body** Required: **No** Since version: **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 a 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`. --- rotationTime Number Located in: **body** Required: **No** Since version: **2.0.0** **Expert option:** Taking _rotationRate_ into account, specifies how long it takes for 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 200 Successful operation. ``` { "recommId": "3f6ad2f2-a3f1-4ba1-a690-f4f01f76d4eb", "recomms": [ { "id": "item-146" }, { "id": "item-462" }, { "id": "item-463" } ], "numberNextRecommsCalls": 0 } ``` --- 400 userId does not match ^\[a-zA-Z0-9\_-:@.\]+$, count is not a positive integer, filter or booster is not valid [ReQL](https://docs.recombee.com/reql) expressions, filter expression does not return boolean, booster does not return double or integer. --- 404 userId not found in the database and cascadeCreate is false. If there is no additional info in the JSON response, you probably have an error in your URL. --- post ### Recommend Items to Item Allowed on Client-Side Recommends a set of items that are somehow related to one given item, _X_. A typical scenario is when the user _A_ is viewing _X_. Then you may display items to the user that he might also be interested in. Recommend items to item request gives you Top-N such items, optionally taking the target user _A_ into account. The returned items are sorted by relevance (the first item being the most relevant). Besides the recommended items, also a unique `recommId` is returned in the response. It can be used to: * Let Recombee know that this recommendation was successful (e.g., user clicked one of the recommended items). See [Reported metrics](https://docs.recombee.com/admin_ui#reported-metrics). * Get subsequent recommended items when the user scrolls down (_infinite scroll_) or goes to the next page. See [Recommend Next Items](https://docs.recombee.com/api/recommendations#recommend-next-items). It is also possible to use GET HTTP method - body parameters then become query parameters. ```js const result = await client.send(new recombee.RecommendItemsToItem(itemId, targetUserId, count, { // optional parameters: scenario: 'homepage', // string cascadeCreate: true, // boolean returnProperties: true, // boolean includedProperties: ['title', 'price', 'publishedAt'], // array filter: 'price > 50', // string booster: 'if now() - \'publishedAt\' <= 7 * 24 * 3600 then 2 else 1', // string logic: 'recombee:default', // string / Object reqlExpressions: { isInUsersCity: 'context_user["city"] in \'cities\'', }, // Object minRelevance: 'low', // string rotationRate: 0.1, // number rotationTime: 7200.0, // number })); ``` --- Since version 2.0.0 --- #### Parameters databaseId String Located in: **path** Required: **Yes** Since version: **2.0.0** ID of your database. --- itemId String Located in: **path** Required: **Yes** Since version: **2.0.0** ID of the item for which the recommendations are to be generated. --- targetUserId String Located in: **body** Required: **Yes** Since version: **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 afterward viewed/purchased an item. If you insist on not specifying the user, pass `null`(`None`, `nil`, `NULL` etc., depending on the 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 Integer Located in: **body** Required: **Yes** Since version: **2.0.0** Number of items to be recommended (N for the top-N recommendation). --- scenario String Located in: **body** Required: **No** Since version: **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](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs. The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios. --- cascadeCreate Boolean Located in: **body** Required: **No** Since version: **2.0.0** If an item of the given _itemId_ or user of the 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 the given _targetUserId_, as the user will be already known to the system. --- returnProperties Boolean Located in: **body** Required: **No** Since version: **2.0.0** With `returnProperties=true`, property values of the recommended items are returned along with their IDs in a JSON dictionary. The acquired property values can be used to easily display the recommended items to the user. Example response: ``` { "recommId": "0c6189e7-dc1a-429a-b613-192696309361", "recomms": [ { "id": "tv-178", "values": { "description": "4K TV with 3D feature", "categories": ["Electronics", "Televisions"], "price": 342, "url": "myshop.com/tv-178" } }, { "id": "mixer-42", "values": { "description": "Stainless Steel Mixer", "categories": ["Home & Kitchen"], "price": 39, "url": "myshop.com/mixer-42" } } ], "numberNextRecommsCalls": 0 } ``` --- includedProperties Array Located in: **body** Required: **No** Since version: **2.0.0** Allows specifying which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. Example response for `includedProperties=description,price`: ``` { "recommId": "6842c725-a79f-4537-a02c-f34d668a3f80", "recomms": [ { "id": "tv-178", "values": { "description": "4K TV with 3D feature", "price": 342 } }, { "id": "mixer-42", "values": { "description": "Stainless Steel Mixer", "price": 39 } } ], "numberNextRecommsCalls": 0 } ``` --- filter String Located in: **body** Required: **No** Since version: **2.0.0** Boolean-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to filter recommended items based on the values of their attributes. Filters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). --- booster String Located in: **body** Required: **No** Since version: **2.0.0** Number-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to boost the recommendation rate of some items based on the values of their attributes. Boosters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). --- logic String Object Located in: **body** Required: **No** Since version: **2.4.0** Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. See [this section](https://docs.recombee.com/logics) for a list of available logics and other details. The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users. Logic can also be set to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). --- reqlExpressions Object Located in: **body** Required: **No** Since version: **6.0.0** A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended item. This can be used to compute additional properties of the recommended items that are not stored in the database. The keys are the names of the expressions, and the values are the actual ReQL expressions. Example request: ``` { "reqlExpressions": { "isInUsersCity": "context_user[\"city\"] in 'cities'", "distanceToUser": "earth_distance('location', context_user[\"location\"])", "isFromSameCompany": "'company' == context_item[\"company\"]" } } ``` Example response: ``` { "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837", "recomms": [ { "id": "restaurant-178", "reqlEvaluations": { "isInUsersCity": true, "distanceToUser": 5200.2, "isFromSameCompany": false } }, { "id": "bar-42", "reqlEvaluations": { "isInUsersCity": false, "distanceToUser": 2516.0, "isFromSameCompany": true } } ], "numberNextRecommsCalls": 0 } ``` --- minRelevance String Located in: **body** Required: **No** Since version: **2.0.0** **Expert option:** If the _targetUserId_ is provided: Specifies the threshold of how 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 a number of items equal to _count_ at any cost. If there is not enough data (such as interactions or item properties), this may even lead to bestseller-based recommendations being 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 Number Located in: **body** Required: **No** Since version: **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 a 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 Number Located in: **body** Required: **No** Since version: **2.0.0** **Expert option:** If the _targetUserId_ is provided: Taking _rotationRate_ into account, specifies how long it takes for an item to recover from the penalization. For example, `rotationTime=7200.0` means that items recommended less than 2 hours ago are penalized. --- #### Responses 200 Successful operation. ``` { "recommId": "768448ea-10b3-4028-bb76-4b2f95121d19", "recomms": [ { "id": "item-146" }, { "id": "item-462" }, { "id": "item-463" } ], "numberNextRecommsCalls": 0 } ``` --- 400 itemId does not match ^\[a-zA-Z0-9\_-:@.\]+$, count is not a positive integer, filter or booster is not valid [ReQL](https://docs.recombee.com/reql) expressions, filter expression does not return boolean, booster does not return double or integer. --- 404 itemId not found in the database and cascadeCreate is false. If there is no additional info in the JSON response, you probably have an error in your URL. --- post ### Recommend Items to Item Segment Allowed on Client-Side Recommends Items that are the most relevant to a particular Segment from a context [Segmentation](https://docs.recombee.com/segmentations). Based on the used Segmentation, this endpoint can be used for example for: * Recommending articles related to a particular topic * Recommending songs belonging to a particular genre * Recommending products produced by a particular brand You need to set the used context Segmentation in the Admin UI in the [Scenario settings](https://docs.recombee.com/scenarios) prior to using this endpoint. The returned items are sorted by relevance (the first item being the most relevant). It is also possible to use GET HTTP method - body parameters then become query parameters. ```js const result = await client.send(new recombee.RecommendItemsToItemSegment(contextSegmentId, targetUserId, count, { // optional parameters: scenario: 'homepage', // string cascadeCreate: true, // boolean returnProperties: true, // boolean includedProperties: ['title', 'price', 'publishedAt'], // array filter: 'price > 50', // string booster: 'if now() - \'publishedAt\' <= 7 * 24 * 3600 then 2 else 1', // string logic: 'recombee:personal-from-segment', // string / Object reqlExpressions: { isInUsersCity: 'context_user["city"] in \'cities\'', }, // Object minRelevance: 'low', // string rotationRate: 0.1, // number rotationTime: 7200.0, // number })); ``` --- Since version 5.0.0 --- #### Parameters databaseId String Located in: **path** Required: **Yes** Since version: **5.0.0** ID of your database. --- contextSegmentId String Located in: **body** Required: **Yes** Since version: **5.0.0** ID of the segment from `contextSegmentationId` for which the recommendations are to be generated. --- targetUserId String Located in: **body** Required: **Yes** Since version: **5.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 afterward viewed/purchased an item. If you insist on not specifying the user, pass `null`(`None`, `nil`, `NULL` etc., depending on the 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 Integer Located in: **body** Required: **Yes** Since version: **5.0.0** Number of items to be recommended (N for the top-N recommendation). --- scenario String Located in: **body** Required: **No** Since version: **5.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](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs. The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios. --- cascadeCreate Boolean Located in: **body** Required: **No** Since version: **5.0.0** If a user of the given _targetUserId_ doesn't exist in the database, it creates this user and returns some (non-personalized) recommendations. This allows, for example, rotations in the following recommendations for the user of the given _targetUserId_, as the user will be already known to the system. --- returnProperties Boolean Located in: **body** Required: **No** Since version: **5.0.0** With `returnProperties=true`, property values of the recommended items are returned along with their IDs in a JSON dictionary. The acquired property values can be used to easily display the recommended items to the user. Example response: ``` { "recommId": "0c6189e7-dc1a-429a-b613-192696309361", "recomms": [ { "id": "tv-178", "values": { "description": "4K TV with 3D feature", "categories": ["Electronics", "Televisions"], "price": 342, "url": "myshop.com/tv-178" } }, { "id": "mixer-42", "values": { "description": "Stainless Steel Mixer", "categories": ["Home & Kitchen"], "price": 39, "url": "myshop.com/mixer-42" } } ], "numberNextRecommsCalls": 0 } ``` --- includedProperties Array Located in: **body** Required: **No** Since version: **5.0.0** Allows specifying which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. Example response for `includedProperties=description,price`: ``` { "recommId": "6842c725-a79f-4537-a02c-f34d668a3f80", "recomms": [ { "id": "tv-178", "values": { "description": "4K TV with 3D feature", "price": 342 } }, { "id": "mixer-42", "values": { "description": "Stainless Steel Mixer", "price": 39 } } ], "numberNextRecommsCalls": 0 } ``` --- filter String Located in: **body** Required: **No** Since version: **5.0.0** Boolean-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to filter recommended items based on the values of their attributes. Filters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). --- booster String Located in: **body** Required: **No** Since version: **5.0.0** Number-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to boost the recommendation rate of some items based on the values of their attributes. Boosters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). --- logic String Object Located in: **body** Required: **No** Since version: **5.0.0** Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. See [this section](https://docs.recombee.com/logics) for a list of available logics and other details. The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users. Logic can also be set to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). --- reqlExpressions Object Located in: **body** Required: **No** Since version: **6.0.0** A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended item. This can be used to compute additional properties of the recommended items that are not stored in the database. The keys are the names of the expressions, and the values are the actual ReQL expressions. Example request: ``` { "reqlExpressions": { "isInUsersCity": "context_user[\"city\"] in 'cities'", "distanceToUser": "earth_distance('location', context_user[\"location\"])" } } ``` Example response: ``` { "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837", "recomms": [ { "id": "restaurant-178", "reqlEvaluations": { "isInUsersCity": true, "distanceToUser": 5200.2 } }, { "id": "bar-42", "reqlEvaluations": { "isInUsersCity": false, "distanceToUser": 2516.0 } } ], "numberNextRecommsCalls": 0 } ``` --- minRelevance String Located in: **body** Required: **No** Since version: **5.0.0** **Expert option:** If the _targetUserId_ is provided: Specifies the threshold of how 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 a number of items equal to _count_ at any cost. If there is not enough data (such as interactions or item properties), this may even lead to bestseller-based recommendations being 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 Number Located in: **body** Required: **No** Since version: **5.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 a 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 Number Located in: **body** Required: **No** Since version: **5.0.0** **Expert option:** If the _targetUserId_ is provided: Taking _rotationRate_ into account, specifies how long it takes for an item to recover from the penalization. For example, `rotationTime=7200.0` means that items recommended less than 2 hours ago are penalized. --- #### Responses 200 successful operation ``` { "recommId": "768448ea-10b3-4028-bb76-4b2f95121d19", "recomms": [ { "id": "item-176" }, { "id": "item-141" }, { "id": "item-967" } ], "numberNextRecommsCalls": 0 } ``` --- 400 count is not a positive integer. --- 404 contextSegmentId not found in the context segmentation --- post ### Recommend Next Items Allowed on Client-Side Returns items that shall be shown to a user as next recommendations when the user e.g. scrolls the page down (_infinite scroll_) or goes to the next page. It accepts `recommId` of a base recommendation request (e.g., request from the first page) and the number of items that shall be returned (`count`). The base request can be one of: * [Recommend Items to Item](https://docs.recombee.com/api/recommendations#recommend-items-to-item) * [Recommend Items to User](https://docs.recombee.com/api/recommendations#recommend-items-to-user) * [Recommend Items to Item Segment](https://docs.recombee.com/api/recommendations#recommend-items-to-item-segment) * [Search Items](https://docs.recombee.com/api/search#search-items) 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. It is also possible to use GET HTTP method - body parameters then become query parameters. ```js const result = await client.send(new recombee.RecommendNextItems(recommId, count)); ``` --- Since version 3.1.0 --- #### Parameters databaseId String Located in: **path** Required: **Yes** Since version: **3.1.0** ID of your database. --- recommId String Located in: **path** Required: **Yes** Since version: **3.1.0** ID of the base recommendation request for which next recommendations should be returned --- count Integer Located in: **body** Required: **Yes** Since version: **3.1.0** Number of items to be recommended --- #### Responses 200 Successful operation. ``` { "recommId": "768448ea-10b3-4028-bb76-4b2f95121d19", "recomms": [ { "id": "item-176" }, { "id": "item-141" }, { "id": "item-967" } ], "numberNextRecommsCalls": 4 } ``` --- 400 Parameter `count` is not given or is not a positive integer. Parameter `recommId` is not an UUID. --- 404 Base request with the given `recommId` does not exist or has expired. --- ## Recommending Item Segments Recommendation endpoints that return the [Item Segments](https://docs.recombee.com/segmentations) (categories, genres, artists, etc.). post ### Recommend Item Segments to User Allowed on Client-Side Recommends the top Segments from a [Segmentation](https://docs.recombee.com/segmentations) for a particular user, based on the user's past interactions. Based on the used Segmentation, this endpoint can be used for example for: * Recommending the top categories for the user * Recommending the top genres for the user * Recommending the top brands for the user * Recommending the top artists for the user You need to set the used Segmentation the Admin UI in the [Scenario settings](https://docs.recombee.com/scenarios) prior to using this endpoint. The returned segments are sorted by relevance (first segment being the most relevant). It is also possible to use GET HTTP method - body parameters then become query parameters. ```js const result = await client.send(new recombee.RecommendItemSegmentsToUser(userId, count, { // optional parameters: scenario: 'homepage', // string cascadeCreate: true, // boolean filter: '\'segmentId\' != "coupons"', // string booster: 'if \'segmentId\' == "Editors Pick" then 2 else 1', // string logic: 'recombee:default', // string / Object reqlExpressions: { countItems: 'size(segment_items("categories", \'segmentId\'))', }, // Object })); ``` --- Since version 4.1.0 --- #### Parameters databaseId String Located in: **path** Required: **Yes** Since version: **4.1.0** ID of your database. --- userId String Located in: **path** Required: **Yes** Since version: **4.1.0** ID of the user for whom personalized recommendations are to be generated. --- count Integer Located in: **body** Required: **Yes** Since version: **4.1.0** Number of item segments to be recommended (N for the top-N recommendation). --- scenario String Located in: **body** Required: **No** Since version: **4.1.0** Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing". You can set various settings to the [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs. The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios. --- cascadeCreate Boolean Located in: **body** Required: **No** Since version: **4.1.0** If the user does not exist in the database, returns a list of non-personalized recommendations and creates the user in the database. This allows, for example, rotations in the following recommendations for that user, as the user will be already known to the system. --- filter String Located in: **body** Required: **No** Since version: **4.1.0** Boolean-returning [ReQL](https://docs.recombee.com/reql) expression which allows you to filter recommended segments based on the `segmentationId`. --- booster String Located in: **body** Required: **No** Since version: **4.1.0** Number-returning [ReQL](https://docs.recombee.com/reql) expression which allows you to boost recommendation rate of some segments based on the `segmentationId`. --- logic String Object Located in: **body** Required: **No** Since version: **4.1.0** Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. See [this section](https://docs.recombee.com/logics) for a list of available logics and other details. The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users. Logic can also be set to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). --- reqlExpressions Object Located in: **body** Required: **No** Since version: **6.1.0** A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended Item Segment. This can be used to compute additional properties of the recommended Item Segments. The keys are the names of the expressions, and the values are the actual ReQL expressions. Example request: ``` { "reqlExpressions": { "countItems": "size(segment_items(\"categories\", 'segmentId'))" } } ``` Example response: ``` { "recommId": "a7ac55a4-8d6e-4f19-addc-abac4164d8a8", "recomms": [ { "id": "category-fantasy-books", "reqlEvaluations": { "countItems": 486 } }, { "id": "category-sci-fi-costumes", "reqlEvaluations": { "countItems": 19 } } ], "numberNextRecommsCalls": 0 } ``` --- #### Responses 200 successful operation ``` { "recommId": "5fbd94fa-2553-422c-bdb5-af82687d8c6a", "recomms": [ { "id": "category-rap" }, { "id": "category-dnb" }, { "id": "category-electronic" } ], "numberNextRecommsCalls": 0 } ``` --- 400 Used Segmentation not configured for the scenario. userId does not match ^\[a-zA-Z0-9\_-:@.\]+$, count is not a positive integer. --- 404 userId not found in the database and cascadeCreate is false --- post ### Recommend Item Segments to Item Allowed on Client-Side Recommends Segments from a [Segmentation](https://docs.recombee.com/segmentations) that are the most relevant to a particular item. Based on the used Segmentation, this endpoint can be used for example for: * Recommending the related categories * Recommending the related genres * Recommending the related brands * Recommending the related artists You need to set the used Segmentation the Admin UI in the [Scenario settings](https://docs.recombee.com/scenarios) prior to using this endpoint. The returned segments are sorted by relevance (first segment being the most relevant). It is also possible to use GET HTTP method - body parameters then become query parameters. ```js const result = await client.send(new recombee.RecommendItemSegmentsToItem(itemId, targetUserId, count, { // optional parameters: scenario: 'homepage', // string cascadeCreate: true, // boolean filter: '\'segmentId\' != "coupons"', // string booster: 'if \'segmentId\' == "Editors Pick" then 2 else 1', // string logic: 'recombee:default', // string / Object reqlExpressions: { countItems: 'size(segment_items("categories", \'segmentId\'))', }, // Object })); ``` --- Since version 4.1.0 --- #### Parameters databaseId String Located in: **path** Required: **Yes** Since version: **4.1.0** ID of your database. --- itemId String Located in: **path** Required: **Yes** Since version: **4.1.0** ID of the item for which the recommendations are to be generated. --- targetUserId String Located in: **body** Required: **Yes** Since version: **4.1.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 afterward viewed/purchased an item. If you insist on not specifying the user, pass `null`(`None`, `nil`, `NULL` etc., depending on the 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 Integer Located in: **body** Required: **Yes** Since version: **4.1.0** Number of item segments to be recommended (N for the top-N recommendation). --- scenario String Located in: **body** Required: **No** Since version: **4.1.0** Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing". You can set various settings to the [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs. The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios. --- cascadeCreate Boolean Located in: **body** Required: **No** Since version: **4.1.0** If the user does not exist in the database, returns a list of non-personalized recommendations and creates the user in the database. This allows, for example, rotations in the following recommendations for that user, as the user will be already known to the system. --- filter String Located in: **body** Required: **No** Since version: **4.1.0** Boolean-returning [ReQL](https://docs.recombee.com/reql) expression which allows you to filter recommended segments based on the `segmentationId`. --- booster String Located in: **body** Required: **No** Since version: **4.1.0** Number-returning [ReQL](https://docs.recombee.com/reql) expression which allows you to boost recommendation rate of some segments based on the `segmentationId`. --- logic String Object Located in: **body** Required: **No** Since version: **4.1.0** Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. See [this section](https://docs.recombee.com/logics) for a list of available logics and other details. The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users. Logic can also be set to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). --- reqlExpressions Object Located in: **body** Required: **No** Since version: **6.1.0** A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended Item Segment. This can be used to compute additional properties of the recommended Item Segments. The keys are the names of the expressions, and the values are the actual ReQL expressions. Example request: ``` { "reqlExpressions": { "countItems": "size(segment_items(\"categories\", 'segmentId'))" } } ``` Example response: ``` { "recommId": "a7ac55a4-8d6e-4f19-addc-abac4164d8a8", "recomms": [ { "id": "category-fantasy-books", "reqlEvaluations": { "countItems": 486 } }, { "id": "category-sci-fi-costumes", "reqlEvaluations": { "countItems": 19 } } ], "numberNextRecommsCalls": 0 } ``` --- #### Responses 200 successful operation ``` { "recommId": "5fbd94fa-2553-422c-bdb5-af82687d8c6a", "recomms": [ { "id": "category-rap" }, { "id": "category-dnb" }, { "id": "category-electronic" } ], "numberNextRecommsCalls": 0 } ``` --- 400 Used Segmentation not configured for the scenario. itemId does not match ^\[a-zA-Z0-9\_-:@.\]+$, count is not a positive integer. --- 404 itemId not found in the database and cascadeCreate is false --- post ### Recommend Item Segments to Item Segment Allowed on Client-Side Recommends Segments from a result [Segmentation](https://docs.recombee.com/segmentations) that are the most relevant to a particular Segment from a context Segmentation. Based on the used Segmentations, this endpoint can be used for example for: * Recommending the related brands to particular brand * Recommending the related brands to particular category * Recommending the related artists to a particular genre (assuming songs are the Items) You need to set the used context and result Segmentation the Admin UI in the [Scenario settings](https://docs.recombee.com/scenarios) prior to using this endpoint. The returned segments are sorted by relevance (first segment being the most relevant). It is also possible to use GET HTTP method - body parameters then become query parameters. ```js const result = await client.send(new recombee.RecommendItemSegmentsToItemSegment(contextSegmentId, targetUserId, count, { // optional parameters: scenario: 'homepage', // string cascadeCreate: true, // boolean filter: '\'segmentId\' != "coupons"', // string booster: 'if \'segmentId\' == "Editors Pick" then 2 else 1', // string logic: 'recombee:default', // string / Object reqlExpressions: { countItems: 'size(segment_items("categories", \'segmentId\'))', }, // Object })); ``` --- Since version 4.1.0 --- #### Parameters databaseId String Located in: **path** Required: **Yes** Since version: **4.1.0** ID of your database. --- contextSegmentId String Located in: **body** Required: **Yes** Since version: **4.1.0** ID of the segment from `contextSegmentationId` for which the recommendations are to be generated. --- targetUserId String Located in: **body** Required: **Yes** Since version: **4.1.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 afterward viewed/purchased an item. If you insist on not specifying the user, pass `null`(`None`, `nil`, `NULL` etc., depending on the 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 Integer Located in: **body** Required: **Yes** Since version: **4.1.0** Number of item segments to be recommended (N for the top-N recommendation). --- scenario String Located in: **body** Required: **No** Since version: **4.1.0** Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing". You can set various settings to the [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs. The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios. --- cascadeCreate Boolean Located in: **body** Required: **No** Since version: **4.1.0** If the user does not exist in the database, returns a list of non-personalized recommendations and creates the user in the database. This allows, for example, rotations in the following recommendations for that user, as the user will be already known to the system. --- filter String Located in: **body** Required: **No** Since version: **4.1.0** Boolean-returning [ReQL](https://docs.recombee.com/reql) expression which allows you to filter recommended segments based on the `segmentationId`. --- booster String Located in: **body** Required: **No** Since version: **4.1.0** Number-returning [ReQL](https://docs.recombee.com/reql) expression which allows you to boost recommendation rate of some segments based on the `segmentationId`. --- logic String Object Located in: **body** Required: **No** Since version: **4.1.0** Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. See [this section](https://docs.recombee.com/logics) for a list of available logics and other details. The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users. Logic can also be set to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). --- reqlExpressions Object Located in: **body** Required: **No** Since version: **6.1.0** A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended Item Segment. This can be used to compute additional properties of the recommended Item Segments. The keys are the names of the expressions, and the values are the actual ReQL expressions. Example request: ``` { "reqlExpressions": { "countItems": "size(segment_items(\"categories\", 'segmentId'))" } } ``` Example response: ``` { "recommId": "a7ac55a4-8d6e-4f19-addc-abac4164d8a8", "recomms": [ { "id": "category-fantasy-books", "reqlEvaluations": { "countItems": 486 } }, { "id": "category-sci-fi-costumes", "reqlEvaluations": { "countItems": 19 } } ], "numberNextRecommsCalls": 0 } ``` --- #### Responses 200 successful operation ``` { "recommId": "5fbd94fa-2553-422c-bdb5-af82687d8c6a", "recomms": [ { "id": "category-rap" }, { "id": "category-dnb" }, { "id": "category-electronic" } ], "numberNextRecommsCalls": 0 } ``` --- 400 count is not a positive integer. --- 404 contextSegmentId not found in the context segmentation --- post ### Recommend Next Item Segments Allowed on Client-Side Returns [Item Segments](https://docs.recombee.com/segmentations) to be shown as the next recommendations when a user scrolls (e.g., within a carousel or feed of Item Segments such as brands, artists, topics, or categories). The request requires the `recommId` of a base recommendation request and the number of Segments to return (`count`). The base request can be one of: * [Recommend Item Segments to Item](https://docs.recombee.com/api/recommendations#recommend-item-segments-to-item) * [Recommend Item Segments to User](https://docs.recombee.com/api/recommendations#recommend-item-segments-to-user) * [Recommend Item Segments to Item Segment](https://docs.recombee.com/api/recommendations#recommend-item-segments-to-item-segment) * [Search Item Segments](https://docs.recombee.com/api/search#search-item-segments) All other parameters are inherited from the base request associated with the provided `recommId`. This endpoint can be called multiple times for a single `recommId`. Each call returns different Item Segments that have not been recommended in previous calls. The number of calls made so far is returned in the `numberNextRecommsCalls` field. Requests can be made up to 30 minutes after the base request or the most recent Recommend Next Item Segments call. For billing purposes, each call to this endpoint is counted as a separate recommendation request. It is also possible to use GET HTTP method - body parameters then become query parameters. ```js const result = await client.send(new recombee.RecommendNextItemSegments(recommId, count)); ``` --- Since version 6.2.0 --- #### Parameters databaseId String Located in: **path** Required: **Yes** Since version: **6.2.0** ID of your database. --- recommId String Located in: **path** Required: **Yes** Since version: **6.2.0** ID of the base recommendation request for which next recommendations should be returned --- count Integer Located in: **body** Required: **Yes** Since version: **6.2.0** Number of item segments to be recommended --- #### Responses 200 Successful operation. ``` { "recommId": "768448ea-10b3-4028-bb76-4b2f95121d19", "recomms": [ { "id": "Comedy" }, { "id": "Drama" }, { "id": "Action" } ], "numberNextRecommsCalls": 4 } ``` --- 400 Parameter `count` is not given or is not a positive integer. Parameter `recommId` is not an UUID. --- 404 Base request with the given `recommId` does not exist or has expired. --- ## Recommending Users Recommendation endpoints that return the Users. post ### Recommend Users to User Gets users similar to the given user, based on the user's past interactions (purchases, ratings, etc.) and values of properties. It is also possible to use GET HTTP method - body parameters then become query parameters. The returned users are sorted by similarity (the first user being the most similar). ```js const result = await client.send(new requests.RecommendUsersToUser(userId, count, { // optional parameters: scenario: 'homepage', // string cascadeCreate: true, // boolean returnProperties: true, // boolean includedProperties: ['username', 'country'], // array filter: '\'country\' == "US"', // string booster: 'if \'country\' == context_user["country"] then 2 else 1', // string logic: 'recombee:default', // string / Object reqlExpressions: { isInUsersCity: 'context_user["city"] in \'cities\'', }, // Object rotationRate: 0.1, // number rotationTime: 7200.0, // number })); ``` --- Since version 2.0.0 --- #### Parameters databaseId String Located in: **path** Required: **Yes** Since version: **2.0.0** ID of your database. --- userId String Located in: **path** Required: **Yes** Since version: **2.0.0** User to whom we find similar users --- count Integer Located in: **body** Required: **Yes** Since version: **2.0.0** Number of users to be recommended (N for the top-N recommendation). --- scenario String Located in: **body** Required: **No** Since version: **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](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs. The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios. --- cascadeCreate Boolean Located in: **body** Required: **No** Since version: **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 Boolean Located in: **body** Required: **No** Since version: **2.0.0** With `returnProperties=true`, property values of the recommended users are returned along with their IDs in a JSON dictionary. The acquired property values can be used to easily display the recommended users. Example response: ``` { "recommId": "9cb9c55d-50ba-4478-84fd-ab456136156e", "recomms": [ { "id": "user-17", "values": { "country": "US", "sex": "F" } }, { "id": "user-2", "values": { "country": "CAN", "sex": "M" } } ], "numberNextRecommsCalls": 0 } ``` --- includedProperties Array Located in: **body** Required: **No** Since version: **2.0.0** Allows specifying which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. Example response for `includedProperties=country`: ``` { "recommId": "b326d82d-5d57-4b45-b362-c9d6f0895855", "recomms": [ { "id": "user-17", "values": { "country": "US" } }, { "id": "user-2", "values": { "country": "CAN" } } ], "numberNextRecommsCalls": 0 } ``` --- filter String Located in: **body** Required: **No** Since version: **2.0.0** Boolean-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to filter recommended users based on the values of their attributes. Filters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). --- booster String Located in: **body** Required: **No** Since version: **2.0.0** Number-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to boost the recommendation rate of some users based on the values of their attributes. Boosters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). --- logic String Object Located in: **body** Required: **No** Since version: **2.4.0** Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. See [this section](https://docs.recombee.com/logics) for a list of available logics and other details. The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users. Logic can also be set to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). --- reqlExpressions Object Located in: **body** Required: **No** Since version: **6.0.0** A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended user. This can be used to compute additional properties of the recommended users that are not stored in the database. The keys are the names of the expressions, and the values are the actual ReQL expressions. Example request: ``` { "reqlExpressions": { "isInUsersCity": "context_user[\"city\"] in 'cities'", "distanceToUser": "earth_distance('location', context_user[\"location\"])" } } ``` Example response: ``` { "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837", "recomms": [ { "id": "restaurant-178", "reqlEvaluations": { "isInUsersCity": true, "distanceToUser": 5200.2 } }, { "id": "bar-42", "reqlEvaluations": { "isInUsersCity": false, "distanceToUser": 2516.0 } } ], "numberNextRecommsCalls": 0 } ``` --- rotationRate Number Located in: **body** Required: **No** Since version: **5.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 a backward fashion. You may penalize a user 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 users. --- rotationTime Number Located in: **body** Required: **No** Since version: **5.0.0** **Expert option:** Taking _rotationRate_ into account, specifies how long it takes for a user to recover from the penalization. For example, `rotationTime=7200.0` means that users recommended less than 2 hours ago are penalized. --- #### Responses 200 Successful operation. ``` { "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 is not valid [ReQL](https://docs.recombee.com/reql) expressions, filter expression does not return boolean, booster does not return double or integer. --- 404 userId not found in the database and cascadeCreate is false. If there is no additional info in the JSON response, you probably have an error in your URL. --- post ### Recommend Users to Item Recommends users that are likely to be interested in the given item. It is also possible to use GET HTTP method - body parameters then become query parameters. The returned users are sorted by predicted interest in the item (the first user being the most interested). ```js const result = await client.send(new requests.RecommendUsersToItem(itemId, count, { // optional parameters: scenario: 'homepage', // string cascadeCreate: true, // boolean returnProperties: true, // boolean includedProperties: ['username', 'country'], // array filter: '\'country\' == "US"', // string booster: 'if \'country\' == context_user["country"] then 2 else 1', // string logic: 'recombee:default', // string / Object reqlExpressions: { isInUsersCity: 'context_user["city"] in \'cities\'', }, // Object })); ``` --- Since version 2.0.0 --- #### Parameters databaseId String Located in: **path** Required: **Yes** Since version: **2.0.0** ID of your database. --- itemId String Located in: **path** Required: **Yes** Since version: **2.0.0** ID of the item for which the recommendations are to be generated. --- count Integer Located in: **body** Required: **Yes** Since version: **2.0.0** Number of users to be recommended (N for the top-N recommendation). --- scenario String Located in: **body** Required: **No** Since version: **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](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs. The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios. --- cascadeCreate Boolean Located in: **body** Required: **No** Since version: **2.0.0** If an item of the given _itemId_ doesn't exist in the database, it creates the missing item. --- returnProperties Boolean Located in: **body** Required: **No** Since version: **2.0.0** With `returnProperties=true`, property values of the recommended users are returned along with their IDs in a JSON dictionary. The acquired property values can be used to easily display the recommended users. Example response: ``` { "recommId": "039b71dc-b9cc-4645-a84f-62b841eecfce", "recomms": [ { "id": "user-17", "values": { "country": "US", "sex": "F" } }, { "id": "user-2", "values": { "country": "CAN", "sex": "M" } } ], "numberNextRecommsCalls": 0 } ``` --- includedProperties Array Located in: **body** Required: **No** Since version: **2.0.0** Allows specifying which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. Example response for `includedProperties=country`: ``` { "recommId": "b2b355dd-972a-4728-9c6b-2dc229db0678", "recomms": [ { "id": "user-17", "values": { "country": "US" } }, { "id": "user-2", "values": { "country": "CAN" } } ], "numberNextRecommsCalls": 0 } ``` --- filter String Located in: **body** Required: **No** Since version: **2.0.0** Boolean-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to filter recommended users based on the values of their attributes. Filters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). --- booster String Located in: **body** Required: **No** Since version: **2.0.0** Number-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to boost the recommendation rate of some users based on the values of their attributes. Boosters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). --- logic String Object Located in: **body** Required: **No** Since version: **2.4.0** Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. See [this section](https://docs.recombee.com/logics) for a list of available logics and other details. The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users. Logic can also be set to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). --- reqlExpressions Object Located in: **body** Required: **No** Since version: **6.0.0** A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended user. This can be used to compute additional properties of the recommended users that are not stored in the database. The keys are the names of the expressions, and the values are the actual ReQL expressions. Example request: ``` { "reqlExpressions": { "isInUsersCity": "context_user[\"city\"] in 'cities'", "distanceToUser": "earth_distance('location', context_user[\"location\"])", "isFromSameCompany": "'company' == context_item[\"company\"]" } } ``` Example response: ``` { "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837", "recomms": [ { "id": "restaurant-178", "reqlEvaluations": { "isInUsersCity": true, "distanceToUser": 5200.2, "isFromSameCompany": false } }, { "id": "bar-42", "reqlEvaluations": { "isInUsersCity": false, "distanceToUser": 2516.0, "isFromSameCompany": true } } ], "numberNextRecommsCalls": 0 } ``` --- #### Responses 200 Successful operation. ``` { "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 is not valid [ReQL](https://docs.recombee.com/reql) expressions, filter expression does not return boolean, booster does not return double or integer. --- 404 itemId not found in the database and cascadeCreate is false. If there is no additional info in the JSON response, you probably have an error in your URL. --- ## Composite Recommendations Composite Recommendations return a source entity (e.g., an Item, or [Item Segment](https://docs.recombee.com/segmentations)) and a list of related recommendations in a single response, enabling multi-layered, highly personalized suggestions, such as _Because You Watched …_ in streaming services or _Top Products from Your Favorite Brand …_ in e-commerce. post ### Composite Recommendation Allowed on Client-Side Composite Recommendation returns both a _source entity_ (e.g., an Item or [Item Segment](https://docs.recombee.com/segmentations)) and a list of related recommendations in a single response. It is ideal for use cases such as personalized homepage sections (_Articles from _), _Because You Watched _, or _Artists Related to Your Favorite Artist _. See detailed **examples and configuration guidance** in the [Composite Scenarios documentation](https://docs.recombee.com/scenarios/composite-recommendations). **Structure** The endpoint operates in two stages: 1. Recommends the _source_ (e.g., an Item Segment or item) to the user. 2. Recommends _results_ (items or Item Segments) related to that _source_. For example, _Articles from _ can be decomposed into: * [Recommend Item Segments To User](https://docs.recombee.com/api/recommendations#recommend-item-segments-to-user) to find the category. * [Recommend Items To Item Segment](https://docs.recombee.com/api/recommendations#recommend-items-to-item-segment) to recommend articles from that category. Since the first step uses [Recommend Item Segments To User](https://docs.recombee.com/api/recommendations#recommend-items-to-user), you must include the `userId` parameter in the _Composite Recommendation_ request. Each _Composite Recommendation_ counts as a single recommendation API request for billing. **Stage-specific Parameters** Additional parameters can be supplied via [sourceSettings](https://docs.recombee.com/api/recommendations#composite-recommendation-param-sourceSettings) and [resultSettings](https://docs.recombee.com/api/recommendations#composite-recommendation-param-resultSettings). In the example above: * `sourceSettings` may include any parameter valid for [Recommend Item Segments To User](https://docs.recombee.com/api/recommendations#recommend-items-to-user) (e.g., `filter`, `booster`). * `resultSettings` may include any parameter valid for [Recommend Items To Item Segment](https://docs.recombee.com/api/recommendations#recommend-items-to-item-segment). See [this example](https://docs.recombee.com/api/recommendations#composite-recommendation-example-setting-parameters-for-individual-stages) for more details. ```js const result = await client.send(new recombee.CompositeRecommendation(scenario, count, { // optional parameters: itemId: 'item-1', // string userId: 'user-1', // string logic: 'recombee:items-from-top-segment-for-you', // string / Object segmentId: 'segment-1', // string searchQuery: 'shoes', // string cascadeCreate: true, // boolean sourceSettings: { returnProperties: true, // boolean includedProperties: ['title', 'price', 'publishedAt'], // array filter: 'price > 50', // string booster: 'if now() - \'publishedAt\' <= 7 * 24 * 3600 then 2 else 1', // string logic: 'recombee:default', // string / Object reqlExpressions: { isInUsersCity: 'context_user["city"] in \'cities\'', }, // Object minRelevance: 'low', // string rotationRate: 0.1, // number rotationTime: 7200.0, // number }, resultSettings: { returnProperties: true, // boolean includedProperties: ['title', 'price', 'publishedAt'], // array filter: 'price > 50', // string booster: 'if now() - \'publishedAt\' <= 7 * 24 * 3600 then 2 else 1', // string logic: 'recombee:default', // string / Object reqlExpressions: { isInUsersCity: 'context_user["city"] in \'cities\'', }, // Object minRelevance: 'low', // string rotationRate: 0.1, // number rotationTime: 7200.0, // number }, })); ``` --- Since version 6.0.0 --- #### Parameters databaseId String Located in: **path** Required: **Yes** Since version: **6.0.0** ID of your database. --- scenario String Located in: **body** Required: **Yes** Since version: **6.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](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs. The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios. --- count Integer Located in: **body** Required: **Yes** Since version: **6.0.0** Number of items to be recommended (N for the top-N recommendation). --- itemId String Located in: **body** Required: **No** Since version: **6.0.0** ID of the item for which the recommendations are to be generated. --- userId String Located in: **body** Required: **No** Since version: **6.0.0** ID of the user for which the recommendations are to be generated. --- logic String Object Located in: **body** Required: **No** Since version: **6.0.0** Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. See [this section](https://docs.recombee.com/logics) for a list of available logics and other details. The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users. Logic can also be set to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). --- segmentId String Located in: **body** Required: **No** Since version: **6.0.0** ID of the segment from `contextSegmentationId` for which the recommendations are to be generated. --- searchQuery String Located in: **body** Required: **No** Since version: **6.2.0** Search query provided by the user. It is used for the full-text search. Only applicable if the _scenario_ corresponds to a search scenario. --- cascadeCreate Boolean Located in: **body** Required: **No** Since version: **6.0.0** If the entity for the source recommendation 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 entity, as the entity will be already known to the system. --- sourceSettings Object Located in: **body** Required: **No** Since version: **6.0.0** Parameters applied for recommending the _Source_ stage. The accepted parameters correspond with the recommendation sub-endpoint used to recommend the _Source_. returnProperties Boolean Located in: **body** Required: **No** Since version: **6.0.0** With `returnProperties=true`, property values of the recommended items are returned along with their IDs in a JSON dictionary. The acquired property values can be used to easily display the recommended items to the user. Example response with `returnProperties` set in the `resultSettings`: ``` { "recommId": "ee94fa8b-efe7-4b35-abc6-2bc3456d66ed", "source": { "id": "category-sport" }, "recomms": [ { "id": "article-1024", "values": { "title": "Champions League: Stunning Comeback Secures Final Spot", "categories": ["Sport", "Football"], "author": "Jane Smith", "url": "newsportal.com/articles/champions-league-comeback" } }, { "id": "article-2031", "values": { "title": "Top 10 Moments from the Summer Olympics", "categories": ["Sport", "Olympics"], "author": "Mark Johnson", "url": "newsportal.com/articles/olympic-top-moments" } }, { "id": "article-3042", "values": { "title": "Rising Stars in Women's Tennis to Watch This Season", "categories": ["Sport", "Tennis"], "author": "Laura Chen", "url": "newsportal.com/articles/womens-tennis-stars" } } ], "numberNextRecommsCalls": 0 } ``` --- includedProperties Array Located in: **body** Required: **No** Since version: **6.0.0** Allows specifying which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. Example response for `returnProperties=true` and `includedProperties=title,url` set in `resultSettings`: ``` { "recommId": "ee94fa8b-efe7-4b35-abc6-2bc3456d66ed", "source": { "id": "category-sport" }, "recomms": [ { "id": "article-1024", "values": { "title": "Champions League: Stunning Comeback Secures Final Spot", "url": "newsportal.com/articles/champions-league-comeback" } }, { "id": "article-2031", "values": { "title": "Top 10 Moments from the Summer Olympics", "url": "newsportal.com/articles/olympic-top-moments" } }, { "id": "article-3042", "values": { "title": "Rising Stars in Women's Tennis to Watch This Season", "url": "newsportal.com/articles/womens-tennis-stars" } } ], "numberNextRecommsCalls": 0 } ``` --- filter String Located in: **body** Required: **No** Since version: **6.0.0** Boolean-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to filter recommended entities based on the values of their attributes. Filters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). --- booster String Located in: **body** Required: **No** Since version: **2.0.0** Number-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to boost the recommendation rate of some entities based on the values of their attributes. Boosters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). --- logic String Object Located in: **body** Required: **No** Since version: **6.0.0** Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. See [this section](https://docs.recombee.com/logics) for a list of available logics and other details. The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users. Logic can also be set to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). --- reqlExpressions Object Located in: **body** Required: **No** Since version: **6.0.0** Only usable if the stage corresponds to the one of these recommendation endpoints: * [Recommend Items To User](https://docs.recombee.com/api/recommendations#recommend-items-to-user) * [Recommend Items To Item](https://docs.recombee.com/api/recommendations#recommend-items-to-item) * [Recommend Items to Item Segment](https://docs.recombee.com/api/recommendations#recommend-items-to-item-segment) * [Recommend Users to Item](https://docs.recombee.com/api/recommendations#recommend-users-to-item) * [Recommend Users To User](https://docs.recombee.com/api/recommendations#recommend-users-to-user) A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended item. This can be used to compute additional properties of the recommended items that are not stored in the database. The keys are the names of the expressions, and the values are the actual ReQL expressions. Example request: ``` { "reqlExpressions": { "isInUsersCity": "context_user[\"city\"] in 'cities'", "distanceToUser": "earth_distance('location', context_user[\"location\"])" } } ``` Example response: ``` { "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837", "source": { "id": "restaurant-123", "reqlEvaluations": { "isInUsersCity": true, "distanceToUser": 3450.5 } }, "recomms": [ { "id": "restaurant-178", "reqlEvaluations": { "isInUsersCity": true, "distanceToUser": 5200.2 } }, { "id": "bar-42", "reqlEvaluations": { "isInUsersCity": false, "distanceToUser": 2516.0 } } ], "numberNextRecommsCalls": 0 } ``` --- minRelevance String Located in: **body** Required: **No** Since version: **6.0.0** **Expert option:** Only usable if the stage corresponds to the one of these recommendation endpoints: * [Recommend Items To User](https://docs.recombee.com/api/recommendations#recommend-items-to-user) * [Recommend Items To Item](https://docs.recombee.com/api/recommendations#recommend-items-to-item) * [Recommend Items to Item Segment](https://docs.recombee.com/api/recommendations#recommend-items-to-item-segment) If the _userId_ is provided: Specifies the threshold of how 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 a number of items equal to _count_ at any cost. If there is not enough data (such as interactions or item properties), this may even lead to bestseller-based recommendations being 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 Number Located in: **body** Required: **No** Since version: **6.0.0** **Expert option:** Only usable if the stage corresponds to the one of these recommendation endpoints: * [Recommend Items To User](https://docs.recombee.com/api/recommendations#recommend-items-to-user) * [Recommend Items To Item](https://docs.recombee.com/api/recommendations#recommend-items-to-item) * [Recommend Items to Item Segment](https://docs.recombee.com/api/recommendations#recommend-items-to-item-segment) * [Recommend Users To User](https://docs.recombee.com/api/recommendations#recommend-users-to-user) If the _userId_ 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 a 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 Number Located in: **body** Required: **No** Since version: **6.0.0** **Expert option:** Only usable if the stage corresponds to the one of these recommendation endpoints: * [Recommend Items To User](https://docs.recombee.com/api/recommendations#recommend-items-to-user) * [Recommend Items To Item](https://docs.recombee.com/api/recommendations#recommend-items-to-item) * [Recommend Items to Item Segment](https://docs.recombee.com/api/recommendations#recommend-items-to-item-segment) * [Recommend Users To User](https://docs.recombee.com/api/recommendations#recommend-users-to-user) If the _userId_ is provided: Taking _rotationRate_ into account, specifies how long it takes for an item to recover from the penalization. For example, `rotationTime=7200.0` means that items recommended less than 2 hours ago are penalized. --- resultSettings Object Located in: **body** Required: **No** Since version: **6.0.0** Parameters applied for recommending the _Result_ stage. The accepted parameters correspond with the recommendation sub-endpoint used to recommend the _Result_. returnProperties Boolean Located in: **body** Required: **No** Since version: **6.0.0** With `returnProperties=true`, property values of the recommended items are returned along with their IDs in a JSON dictionary. The acquired property values can be used to easily display the recommended items to the user. Example response with `returnProperties` set in the `resultSettings`: ``` { "recommId": "ee94fa8b-efe7-4b35-abc6-2bc3456d66ed", "source": { "id": "category-sport" }, "recomms": [ { "id": "article-1024", "values": { "title": "Champions League: Stunning Comeback Secures Final Spot", "categories": ["Sport", "Football"], "author": "Jane Smith", "url": "newsportal.com/articles/champions-league-comeback" } }, { "id": "article-2031", "values": { "title": "Top 10 Moments from the Summer Olympics", "categories": ["Sport", "Olympics"], "author": "Mark Johnson", "url": "newsportal.com/articles/olympic-top-moments" } }, { "id": "article-3042", "values": { "title": "Rising Stars in Women's Tennis to Watch This Season", "categories": ["Sport", "Tennis"], "author": "Laura Chen", "url": "newsportal.com/articles/womens-tennis-stars" } } ], "numberNextRecommsCalls": 0 } ``` --- includedProperties Array Located in: **body** Required: **No** Since version: **6.0.0** Allows specifying which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. Example response for `returnProperties=true` and `includedProperties=title,url` set in `resultSettings`: ``` { "recommId": "ee94fa8b-efe7-4b35-abc6-2bc3456d66ed", "source": { "id": "category-sport" }, "recomms": [ { "id": "article-1024", "values": { "title": "Champions League: Stunning Comeback Secures Final Spot", "url": "newsportal.com/articles/champions-league-comeback" } }, { "id": "article-2031", "values": { "title": "Top 10 Moments from the Summer Olympics", "url": "newsportal.com/articles/olympic-top-moments" } }, { "id": "article-3042", "values": { "title": "Rising Stars in Women's Tennis to Watch This Season", "url": "newsportal.com/articles/womens-tennis-stars" } } ], "numberNextRecommsCalls": 0 } ``` --- filter String Located in: **body** Required: **No** Since version: **6.0.0** Boolean-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to filter recommended entities based on the values of their attributes. Filters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). --- booster String Located in: **body** Required: **No** Since version: **2.0.0** Number-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to boost the recommendation rate of some entities based on the values of their attributes. Boosters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). --- logic String Object Located in: **body** Required: **No** Since version: **6.0.0** Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. See [this section](https://docs.recombee.com/logics) for a list of available logics and other details. The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users. Logic can also be set to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). --- reqlExpressions Object Located in: **body** Required: **No** Since version: **6.0.0** Only usable if the stage corresponds to the one of these recommendation endpoints: * [Recommend Items To User](https://docs.recombee.com/api/recommendations#recommend-items-to-user) * [Recommend Items To Item](https://docs.recombee.com/api/recommendations#recommend-items-to-item) * [Recommend Items to Item Segment](https://docs.recombee.com/api/recommendations#recommend-items-to-item-segment) * [Recommend Users to Item](https://docs.recombee.com/api/recommendations#recommend-users-to-item) * [Recommend Users To User](https://docs.recombee.com/api/recommendations#recommend-users-to-user) A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended item. This can be used to compute additional properties of the recommended items that are not stored in the database. The keys are the names of the expressions, and the values are the actual ReQL expressions. Example request: ``` { "reqlExpressions": { "isInUsersCity": "context_user[\"city\"] in 'cities'", "distanceToUser": "earth_distance('location', context_user[\"location\"])" } } ``` Example response: ``` { "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837", "source": { "id": "restaurant-123", "reqlEvaluations": { "isInUsersCity": true, "distanceToUser": 3450.5 } }, "recomms": [ { "id": "restaurant-178", "reqlEvaluations": { "isInUsersCity": true, "distanceToUser": 5200.2 } }, { "id": "bar-42", "reqlEvaluations": { "isInUsersCity": false, "distanceToUser": 2516.0 } } ], "numberNextRecommsCalls": 0 } ``` --- minRelevance String Located in: **body** Required: **No** Since version: **6.0.0** **Expert option:** Only usable if the stage corresponds to the one of these recommendation endpoints: * [Recommend Items To User](https://docs.recombee.com/api/recommendations#recommend-items-to-user) * [Recommend Items To Item](https://docs.recombee.com/api/recommendations#recommend-items-to-item) * [Recommend Items to Item Segment](https://docs.recombee.com/api/recommendations#recommend-items-to-item-segment) If the _userId_ is provided: Specifies the threshold of how 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 a number of items equal to _count_ at any cost. If there is not enough data (such as interactions or item properties), this may even lead to bestseller-based recommendations being 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 Number Located in: **body** Required: **No** Since version: **6.0.0** **Expert option:** Only usable if the stage corresponds to the one of these recommendation endpoints: * [Recommend Items To User](https://docs.recombee.com/api/recommendations#recommend-items-to-user) * [Recommend Items To Item](https://docs.recombee.com/api/recommendations#recommend-items-to-item) * [Recommend Items to Item Segment](https://docs.recombee.com/api/recommendations#recommend-items-to-item-segment) * [Recommend Users To User](https://docs.recombee.com/api/recommendations#recommend-users-to-user) If the _userId_ 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 a 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 Number Located in: **body** Required: **No** Since version: **6.0.0** **Expert option:** Only usable if the stage corresponds to the one of these recommendation endpoints: * [Recommend Items To User](https://docs.recombee.com/api/recommendations#recommend-items-to-user) * [Recommend Items To Item](https://docs.recombee.com/api/recommendations#recommend-items-to-item) * [Recommend Items to Item Segment](https://docs.recombee.com/api/recommendations#recommend-items-to-item-segment) * [Recommend Users To User](https://docs.recombee.com/api/recommendations#recommend-users-to-user) If the _userId_ is provided: Taking _rotationRate_ into account, specifies how long it takes for an item to recover from the penalization. For example, `rotationTime=7200.0` means that items recommended less than 2 hours ago are penalized. --- #### Responses 200 Successful operation. ``` { "recommId": "ee94fa8b-efe7-4b35-abc6-2bc3456d66ed", "source": { "id": "category-4" }, "recomms": [ { "id": "item-64" }, { "id": "item-42" }, { "id": "item-23" } ], "numberNextRecommsCalls": 0 } ``` --- 400 Count is not a positive integer, provided scenario not found. --- 404 contextSegmentId not found in the context segmentation, userId not found in the database and cascadeCreate is false, itemId not found in the database and cascadeCreate is false. --- #### Examples ##### Example Category Sections With Reordering Suppose you want to recommend three category sections on the homepage, but in a personalized order for each user. For example, in a news domain, one user might see _Politics–Culture–Technology_, while another might get _Sport–Technology–Politics_. You can achieve this by calling three Composite Recommendations within a single [Batch](https://docs.recombee.com/api/miscellaneous#batch) request — retrieving both the personalized categories and the recommended items within each. The Batch ensures that three distinct categories are returned in the results. Example response: ``` [ { "code": 200, "json": { "recommId": "c8f25d2a-5c39-4c45-b42b-6a7d4e6b1c52", "source": { "id": "category-sport" }, "recomms": [ { "id": "article-1024" }, { "id": "article-2031" }, { "id": "article-3042" } ], "numberNextRecommsCalls": 0 } }, { "code": 200, "json": { "recommId": "b31f16e2-f4e9-43e8-b22f-9da78a5e8e33", "source": { "id": "category-technology" }, "recomms": [ { "id": "article-501" }, { "id": "article-507" }, { "id": "article-519" } ], "numberNextRecommsCalls": 0 } }, { "code": 200, "json": { "recommId": "3f6ad2f2-a3f1-4ba1-a690-f4f01f76d4eb", "source": { "id": "category-politics" }, "recomms": [ { "id": "article-146" }, { "id": "article-462" }, { "id": "article-463" } ], "numberNextRecommsCalls": 0 } } ] ``` Requesting recommendations: ```js const batchRequest = new recombee.Batch([ new recombee.CompositeRecommendation('homepage-category-section', 6, { userId: userId }), new recombee.CompositeRecommendation('homepage-category-section', 6, { userId: userId }), new recombee.CompositeRecommendation('homepage-category-section', 6, { userId: userId }) ], { distinctRecomms: true }); const responses = await client.send(batchRequest); ``` --- ##### Example Setting Parameters For Individual Stages This example shows how to use parameters on both stages: * In `sourceSettings`, we enable rotation so the _source_ changes over time for the same user. * In `resultSettings`, we filter out promotions and return basic properties for rendering. Example response (truncated) with `returnProperties=true` on results: ``` { "recommId": "7b8d0f5e-42a4-4a71-b2b7-25f9c0cc0e9a", "source": { "id": "article-389" }, "recomms": [ { "id": "article-1024", "values": { "title": "5 Books That Will Change How You Think", "url": "newsportal.com/a/1024" } }, { "id": "article-2031", "values": { "title": "The Psychology of Habit Formation", "url": "newsportal.com/a/2031" } } ], "numberNextRecommsCalls": 0 } ``` Requesting recommendations: ```js const req = new recombee.CompositeRecommendation( 'because-you-read', 10, { userId: userId, sourceSettings: { rotationRate: 0.5, rotationTime: 7200 }, resultSettings: { filter: "'type' != \"promotion\"", returnProperties: true, includedProperties: ['title', 'url'] } } ); const response = await client.send(req); ```