com.recombee.api_client.api_requests.RecommendItemsToItem Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of api-client Show documentation
Show all versions of api-client Show documentation
A client library for easy use of the Recombee recommendation API
package com.recombee.api_client.api_requests;
/*
This file is auto-generated, do not edit
*/
import java.util.Date;
import java.util.Map;
import java.util.HashMap;
import com.recombee.api_client.bindings.Logic;
import com.recombee.api_client.util.HTTPMethod;
/**
* Recommends set of items that are somehow related to one given item, *X*. Typical scenario is when user *A* is viewing *X*. Then you may display items to the user that he might be also interested in. Recommend items to item request gives you Top-N such items, optionally taking the target user *A* into account.
* It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.
* The returned items are sorted by relevancy (first item being the most relevant).
*/
public class RecommendItemsToItem extends Request {
/**
* ID of the item for which the recommendations are to be generated.
*/
protected String itemId;
/**
* ID of the user who will see the recommendations.
* Specifying the *targetUserId* is beneficial because:
* * It makes the recommendations personalized
* * Allows the calculation of Actions and Conversions
* in the graphical user interface,
* as Recombee can pair the user who got recommendations
* and who afterwards viewed/purchased an item.
* If you insist on not specifying the user, pass `null`
* (`None`, `nil`, `NULL` etc. depending on language) to *targetUserId*.
* Do not create some special dummy user for getting recommendations,
* as it could mislead the recommendation models,
* and result in wrong recommendations.
* For anonymous/unregistered users it is possible to use for example their session ID.
*/
protected String targetUserId;
/**
* Number of items to be recommended (N for the top-N recommendation).
*/
protected Long count;
/**
* 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.html) in the [Admin UI](https://admin.recombee.com). You can also see performance of each scenario in the Admin UI separately, so you can check how well each application performs.
* The AI which optimizes models in order to get the best results may optimize different scenarios separately, or even use different models in each of the scenarios.
*/
protected String scenario;
/**
* If item of given *itemId* or user of given *targetUserId* doesn't exist in the database, it creates the missing entity/entities and returns some (non-personalized) recommendations. This allows for example rotations in the following recommendations for the user of given *targetUserId*, as the user will be already known to the system.
*/
protected Boolean cascadeCreate;
/**
* With `returnProperties=true`, property values of the recommended items are returned along with their IDs in a JSON dictionary. The acquired property values can be used for easy displaying of the recommended items to the user.
* Example response:
* ```
* {
* "recommId": "0c6189e7-dc1a-429a-b613-192696309361",
* "recomms":
* [
* {
* "id": "tv-178",
* "values": {
* "description": "4K TV with 3D feature",
* "categories": ["Electronics", "Televisions"],
* "price": 342,
* "url": "myshop.com/tv-178"
* }
* },
* {
* "id": "mixer-42",
* "values": {
* "description": "Stainless Steel Mixer",
* "categories": ["Home & Kitchen"],
* "price": 39,
* "url": "myshop.com/mixer-42"
* }
* }
* ]
* }
* ```
*/
protected Boolean returnProperties;
/**
* Allows to specify, which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list.
* Example response for `includedProperties=description,price`:
* ```
* {
* "recommId": "6842c725-a79f-4537-a02c-f34d668a3f80",
* "recomms":
* [
* {
* "id": "tv-178",
* "values": {
* "description": "4K TV with 3D feature",
* "price": 342
* }
* },
* {
* "id": "mixer-42",
* "values": {
* "description": "Stainless Steel Mixer",
* "price": 39
* }
* }
* ]
* }
* ```
*/
protected String[] includedProperties;
/**
* Boolean-returning [ReQL](https://docs.recombee.com/reql.html) expression which allows you to filter recommended items based on the values of their attributes.
* Filters can be also assigned to a [scenario](https://docs.recombee.com/scenarios.html) in the [Admin UI](https://admin.recombee.com).
*/
protected String filter;
/**
* Number-returning [ReQL](https://docs.recombee.com/reql.html) expression which allows you to boost recommendation rate of some items based on the values of their attributes.
* Boosters can be also assigned to a [scenario](https://docs.recombee.com/scenarios.html) in the [Admin UI](https://admin.recombee.com).
*/
protected String booster;
/**
* Logic specifies particular behavior of the recommendation models. You can pick tailored logic for your domain and use case.
* See [this section](https://docs.recombee.com/recommendation_logics.html) for list of available logics and other details.
* The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users.
* Logic can be also set to a [scenario](https://docs.recombee.com/scenarios.html) in the [Admin UI](https://admin.recombee.com).
*/
protected Logic logic;
/**
* **Expert option** If *targetUserId* parameter is present, the recommendations are biased towards the given user. Using *userImpact*, you may control this bias. For an extreme case of `userImpact=0.0`, the interactions made by the user are not taken into account at all (with the exception of history-based blacklisting), for `userImpact=1.0`, you'll get user-based recommendation. The default value is `0`.
*/
protected Double userImpact;
/**
* **Expert option** Real number from [0.0, 1.0] which determines how much mutually dissimilar should the recommended items be. The default value is 0.0, i.e., no diversification. Value 1.0 means maximal diversification.
*/
protected Double diversity;
/**
* **Expert option** If the *targetUserId* is provided: Specifies the threshold of how much relevant must the recommended items be to the user. Possible values one of: "low", "medium", "high". The default value is "low", meaning that the system attempts to recommend number of items equal to *count* at any cost. If there are not enough data (such as interactions or item properties), this may even lead to bestseller-based recommendations to be appended to reach the full *count*. This behavior may be suppressed by using "medium" or "high" values. In such case, the system only recommends items of at least the requested relevancy, and may return less than *count* items when there is not enough data to fulfill it.
*/
protected String minRelevance;
/**
* **Expert option** If the *targetUserId* is provided: If your users browse the system in real-time, it may easily happen that you wish to offer them recommendations multiple times. Here comes the question: how much should the recommendations change? Should they remain the same, or should they rotate? Recombee API allows you to control this per-request in backward fashion. You may penalize an item for being recommended in the near past. For the specific user, `rotationRate=1` means maximal rotation, `rotationRate=0` means absolutely no rotation. You may also use, for example `rotationRate=0.2` for only slight rotation of recommended items.
*/
protected Double rotationRate;
/**
* **Expert option** If the *targetUserId* is provided: Taking *rotationRate* into account, specifies how long time it takes to an item to recover from the penalization. For example, `rotationTime=7200.0` means that items recommended less than 2 hours ago are penalized.
*/
protected Double rotationTime;
/**
* Dictionary of custom options.
*/
protected Map expertSettings;
/**
* If there is a custom AB-testing running, return name of group to which the request belongs.
*/
protected Boolean returnAbGroup;
/**
* Construct the request
* @param itemId ID of the item for which the recommendations are to be generated.
* @param targetUserId ID of the user who will see the recommendations.
* Specifying the *targetUserId* is beneficial because:
* * It makes the recommendations personalized
* * Allows the calculation of Actions and Conversions
* in the graphical user interface,
* as Recombee can pair the user who got recommendations
* and who afterwards viewed/purchased an item.
* If you insist on not specifying the user, pass `null`
* (`None`, `nil`, `NULL` etc. depending on language) to *targetUserId*.
* Do not create some special dummy user for getting recommendations,
* as it could mislead the recommendation models,
* and result in wrong recommendations.
* For anonymous/unregistered users it is possible to use for example their session ID.
* @param count Number of items to be recommended (N for the top-N recommendation).
*/
public RecommendItemsToItem (String itemId,String targetUserId,long count) {
this.itemId = itemId;
this.targetUserId = targetUserId;
this.count = count;
this.timeout = 3000;
}
/**
* @param scenario 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.html) in the [Admin UI](https://admin.recombee.com). You can also see performance of each scenario in the Admin UI separately, so you can check how well each application performs.
* The AI which optimizes models in order to get the best results may optimize different scenarios separately, or even use different models in each of the scenarios.
*/
public RecommendItemsToItem setScenario(String scenario) {
this.scenario = scenario;
return this;
}
/**
* @param cascadeCreate If item of given *itemId* or user of given *targetUserId* doesn't exist in the database, it creates the missing entity/entities and returns some (non-personalized) recommendations. This allows for example rotations in the following recommendations for the user of given *targetUserId*, as the user will be already known to the system.
*/
public RecommendItemsToItem setCascadeCreate(boolean cascadeCreate) {
this.cascadeCreate = cascadeCreate;
return this;
}
/**
* @param returnProperties With `returnProperties=true`, property values of the recommended items are returned along with their IDs in a JSON dictionary. The acquired property values can be used for easy displaying of the recommended items to the user.
* Example response:
* ```
* {
* "recommId": "0c6189e7-dc1a-429a-b613-192696309361",
* "recomms":
* [
* {
* "id": "tv-178",
* "values": {
* "description": "4K TV with 3D feature",
* "categories": ["Electronics", "Televisions"],
* "price": 342,
* "url": "myshop.com/tv-178"
* }
* },
* {
* "id": "mixer-42",
* "values": {
* "description": "Stainless Steel Mixer",
* "categories": ["Home & Kitchen"],
* "price": 39,
* "url": "myshop.com/mixer-42"
* }
* }
* ]
* }
* ```
*/
public RecommendItemsToItem setReturnProperties(boolean returnProperties) {
this.returnProperties = returnProperties;
return this;
}
/**
* @param includedProperties Allows to specify, which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list.
* Example response for `includedProperties=description,price`:
* ```
* {
* "recommId": "6842c725-a79f-4537-a02c-f34d668a3f80",
* "recomms":
* [
* {
* "id": "tv-178",
* "values": {
* "description": "4K TV with 3D feature",
* "price": 342
* }
* },
* {
* "id": "mixer-42",
* "values": {
* "description": "Stainless Steel Mixer",
* "price": 39
* }
* }
* ]
* }
* ```
*/
public RecommendItemsToItem setIncludedProperties(String[] includedProperties) {
this.includedProperties = includedProperties;
return this;
}
/**
* @param filter Boolean-returning [ReQL](https://docs.recombee.com/reql.html) expression which allows you to filter recommended items based on the values of their attributes.
* Filters can be also assigned to a [scenario](https://docs.recombee.com/scenarios.html) in the [Admin UI](https://admin.recombee.com).
*/
public RecommendItemsToItem setFilter(String filter) {
this.filter = filter;
return this;
}
/**
* @param booster Number-returning [ReQL](https://docs.recombee.com/reql.html) expression which allows you to boost recommendation rate of some items based on the values of their attributes.
* Boosters can be also assigned to a [scenario](https://docs.recombee.com/scenarios.html) in the [Admin UI](https://admin.recombee.com).
*/
public RecommendItemsToItem setBooster(String booster) {
this.booster = booster;
return this;
}
/**
* @param logic Logic specifies particular behavior of the recommendation models. You can pick tailored logic for your domain and use case.
* See [this section](https://docs.recombee.com/recommendation_logics.html) for list of available logics and other details.
* The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users.
* Logic can be also set to a [scenario](https://docs.recombee.com/scenarios.html) in the [Admin UI](https://admin.recombee.com).
*/
public RecommendItemsToItem setLogic(Logic logic) {
this.logic = logic;
return this;
}
/**
* @param userImpact **Expert option** If *targetUserId* parameter is present, the recommendations are biased towards the given user. Using *userImpact*, you may control this bias. For an extreme case of `userImpact=0.0`, the interactions made by the user are not taken into account at all (with the exception of history-based blacklisting), for `userImpact=1.0`, you'll get user-based recommendation. The default value is `0`.
*/
public RecommendItemsToItem setUserImpact(double userImpact) {
this.userImpact = userImpact;
return this;
}
/**
* @param diversity **Expert option** Real number from [0.0, 1.0] which determines how much mutually dissimilar should the recommended items be. The default value is 0.0, i.e., no diversification. Value 1.0 means maximal diversification.
*/
public RecommendItemsToItem setDiversity(double diversity) {
this.diversity = diversity;
return this;
}
/**
* @param minRelevance **Expert option** If the *targetUserId* is provided: Specifies the threshold of how much relevant must the recommended items be to the user. Possible values one of: "low", "medium", "high". The default value is "low", meaning that the system attempts to recommend number of items equal to *count* at any cost. If there are not enough data (such as interactions or item properties), this may even lead to bestseller-based recommendations to be appended to reach the full *count*. This behavior may be suppressed by using "medium" or "high" values. In such case, the system only recommends items of at least the requested relevancy, and may return less than *count* items when there is not enough data to fulfill it.
*/
public RecommendItemsToItem setMinRelevance(String minRelevance) {
this.minRelevance = minRelevance;
return this;
}
/**
* @param rotationRate **Expert option** If the *targetUserId* is provided: If your users browse the system in real-time, it may easily happen that you wish to offer them recommendations multiple times. Here comes the question: how much should the recommendations change? Should they remain the same, or should they rotate? Recombee API allows you to control this per-request in backward fashion. You may penalize an item for being recommended in the near past. For the specific user, `rotationRate=1` means maximal rotation, `rotationRate=0` means absolutely no rotation. You may also use, for example `rotationRate=0.2` for only slight rotation of recommended items.
*/
public RecommendItemsToItem setRotationRate(double rotationRate) {
this.rotationRate = rotationRate;
return this;
}
/**
* @param rotationTime **Expert option** If the *targetUserId* is provided: Taking *rotationRate* into account, specifies how long time it takes to an item to recover from the penalization. For example, `rotationTime=7200.0` means that items recommended less than 2 hours ago are penalized.
*/
public RecommendItemsToItem setRotationTime(double rotationTime) {
this.rotationTime = rotationTime;
return this;
}
/**
* @param expertSettings Dictionary of custom options.
*/
public RecommendItemsToItem setExpertSettings(Map expertSettings) {
this.expertSettings = expertSettings;
return this;
}
/**
* @param returnAbGroup If there is a custom AB-testing running, return name of group to which the request belongs.
*/
public RecommendItemsToItem setReturnAbGroup(boolean returnAbGroup) {
this.returnAbGroup = returnAbGroup;
return this;
}
public String getItemId() {
return this.itemId;
}
public String getTargetUserId() {
return this.targetUserId;
}
public long getCount() {
return this.count;
}
public String getScenario() {
return this.scenario;
}
public boolean getCascadeCreate() {
if (this.cascadeCreate==null) return false;
return this.cascadeCreate;
}
public boolean getReturnProperties() {
if (this.returnProperties==null) return false;
return this.returnProperties;
}
public String[] getIncludedProperties() {
return this.includedProperties;
}
public String getFilter() {
return this.filter;
}
public String getBooster() {
return this.booster;
}
public Logic getLogic() {
return this.logic;
}
public double getUserImpact() {
return this.userImpact;
}
public double getDiversity() {
return this.diversity;
}
public String getMinRelevance() {
return this.minRelevance;
}
public double getRotationRate() {
return this.rotationRate;
}
public double getRotationTime() {
return this.rotationTime;
}
public Map getExpertSettings() {
return this.expertSettings;
}
public boolean getReturnAbGroup() {
if (this.returnAbGroup==null) return false;
return this.returnAbGroup;
}
/**
* @return Used HTTP method
*/
@Override
public HTTPMethod getHTTPMethod() {
return HTTPMethod.POST;
}
/**
* @return URI to the endpoint including path parameters
*/
@Override
public String getPath() {
return String.format("/recomms/items/%s/items/", this.itemId);
}
/**
* Get query parameters
* @return Values of query parameters (name of parameter: value of the parameter)
*/
@Override
public Map getQueryParameters() {
HashMap params = new HashMap();
return params;
}
/**
* Get body parameters
* @return Values of body parameters (name of parameter: value of the parameter)
*/
@Override
public Map getBodyParameters() {
HashMap params = new HashMap();
params.put("targetUserId", this.targetUserId);
params.put("count", this.count);
if (this.scenario!=null) {
params.put("scenario", this.scenario);
}
if (this.cascadeCreate!=null) {
params.put("cascadeCreate", this.cascadeCreate);
}
if (this.returnProperties!=null) {
params.put("returnProperties", this.returnProperties);
}
if (this.includedProperties!=null) {
params.put("includedProperties", this.includedProperties);
}
if (this.filter!=null) {
params.put("filter", this.filter);
}
if (this.booster!=null) {
params.put("booster", this.booster);
}
if (this.logic!=null) {
params.put("logic", this.logic);
}
if (this.userImpact!=null) {
params.put("userImpact", this.userImpact);
}
if (this.diversity!=null) {
params.put("diversity", this.diversity);
}
if (this.minRelevance!=null) {
params.put("minRelevance", this.minRelevance);
}
if (this.rotationRate!=null) {
params.put("rotationRate", this.rotationRate);
}
if (this.rotationTime!=null) {
params.put("rotationTime", this.rotationTime);
}
if (this.expertSettings!=null) {
params.put("expertSettings", this.expertSettings);
}
if (this.returnAbGroup!=null) {
params.put("returnAbGroup", this.returnAbGroup);
}
return params;
}
}
© 2015 - 2025 Weber Informatics LLC | Privacy Policy