additionalData for interactions, returnAbGroup for recommendation endpoints

Author: OndraFiedler

README.md

@@ -13,7 +13,7 @@ The client is available in the [Maven Central Repository](https://mvnrepository.
     <dependency>
         <groupId>com.recombee</groupId>
         <artifactId>api-client</artifactId>
-        <version>2.2.2</version>
+        <version>2.3.0</version>
     </dependency>
 ```
 

pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>com.recombee</groupId>
     <artifactId>api-client</artifactId>
-    <version>2.2.2</version>
+    <version>2.3.0</version>
     <name>Recombee API Client</name>
     <description>A client library for easy use of the Recombee recommendation API</description>
     <url>http://recombee.com</url>

src/main/java/com/recombee/api_client/RecombeeClient.java

@@ -85,7 +85,7 @@ public class RecombeeClient {
 
     final int BATCH_MAX_SIZE = 10000; //Maximal number of requests within one batch request
 
-    final String USER_AGENT = "recombee-java-api-client/2.2.2";
+    final String USER_AGENT = "recombee-java-api-client/2.3.0";
 
     private final OkHttpClient httpClient = new OkHttpClient();
 

src/main/java/com/recombee/api_client/api_requests/AddBookmark.java

@@ -35,6 +35,10 @@ public class AddBookmark extends Request {
      * If this bookmark is based on a recommendation request, `recommId` is the id of the clicked recommendation.
      */
     protected String recommId;
+    /**
+     * A dictionary of additional data for the interaction.
+     */
+    protected Map<String, Object> additionalData;
 
     /**
      * Construct the request
@@ -71,6 +75,14 @@ public AddBookmark setRecommId(String recommId) {
          return this;
     }
 
+    /**
+     * @param additionalData A dictionary of additional data for the interaction.
+     */
+    public AddBookmark setAdditionalData(Map<String, Object> additionalData) {
+         this.additionalData = additionalData;
+         return this;
+    }
+
     public String getUserId() {
          return this.userId;
     }
@@ -92,6 +104,10 @@ public String getRecommId() {
          return this.recommId;
     }
 
+    public Map<String, Object> getAdditionalData() {
+         return this.additionalData;
+    }
+
     /**
      * @return Used HTTP method
      */
@@ -136,6 +152,9 @@ public Map<String, Object> getBodyParameters() {
         if (this.recommId!=null) {
             params.put("recommId", this.recommId);
         }
+        if (this.additionalData!=null) {
+            params.put("additionalData", this.additionalData);
+        }
         return params;
     }
 

src/main/java/com/recombee/api_client/api_requests/AddCartAddition.java

@@ -43,6 +43,10 @@ public class AddCartAddition extends Request {
      * If this cart addition is based on a recommendation request, `recommId` is the id of the clicked recommendation.
      */
     protected String recommId;
+    /**
+     * A dictionary of additional data for the interaction.
+     */
+    protected Map<String, Object> additionalData;
 
     /**
      * Construct the request
@@ -95,6 +99,14 @@ public AddCartAddition setRecommId(String recommId) {
          return this;
     }
 
+    /**
+     * @param additionalData A dictionary of additional data for the interaction.
+     */
+    public AddCartAddition setAdditionalData(Map<String, Object> additionalData) {
+         this.additionalData = additionalData;
+         return this;
+    }
+
     public String getUserId() {
          return this.userId;
     }
@@ -124,6 +136,10 @@ public String getRecommId() {
          return this.recommId;
     }
 
+    public Map<String, Object> getAdditionalData() {
+         return this.additionalData;
+    }
+
     /**
      * @return Used HTTP method
      */
@@ -174,6 +190,9 @@ public Map<String, Object> getBodyParameters() {
         if (this.recommId!=null) {
             params.put("recommId", this.recommId);
         }
+        if (this.additionalData!=null) {
+            params.put("additionalData", this.additionalData);
+        }
         return params;
     }
 

src/main/java/com/recombee/api_client/api_requests/AddDetailView.java

@@ -39,6 +39,10 @@ public class AddDetailView extends Request {
      * If this detail view is based on a recommendation request, `recommId` is the id of the clicked recommendation.
      */
     protected String recommId;
+    /**
+     * A dictionary of additional data for the interaction.
+     */
+    protected Map<String, Object> additionalData;
 
     /**
      * Construct the request
@@ -83,6 +87,14 @@ public AddDetailView setRecommId(String recommId) {
          return this;
     }
 
+    /**
+     * @param additionalData A dictionary of additional data for the interaction.
+     */
+    public AddDetailView setAdditionalData(Map<String, Object> additionalData) {
+         this.additionalData = additionalData;
+         return this;
+    }
+
     public String getUserId() {
          return this.userId;
     }
@@ -108,6 +120,10 @@ public String getRecommId() {
          return this.recommId;
     }
 
+    public Map<String, Object> getAdditionalData() {
+         return this.additionalData;
+    }
+
     /**
      * @return Used HTTP method
      */
@@ -155,6 +171,9 @@ public Map<String, Object> getBodyParameters() {
         if (this.recommId!=null) {
             params.put("recommId", this.recommId);
         }
+        if (this.additionalData!=null) {
+            params.put("additionalData", this.additionalData);
+        }
         return params;
     }
 

src/main/java/com/recombee/api_client/api_requests/AddPurchase.java

@@ -47,6 +47,10 @@ public class AddPurchase extends Request {
      * If this purchase is based on a recommendation request, `recommId` is the id of the clicked recommendation.
      */
     protected String recommId;
+    /**
+     * A dictionary of additional data for the interaction.
+     */
+    protected Map<String, Object> additionalData;
 
     /**
      * Construct the request
@@ -107,6 +111,14 @@ public AddPurchase setRecommId(String recommId) {
          return this;
     }
 
+    /**
+     * @param additionalData A dictionary of additional data for the interaction.
+     */
+    public AddPurchase setAdditionalData(Map<String, Object> additionalData) {
+         this.additionalData = additionalData;
+         return this;
+    }
+
     public String getUserId() {
          return this.userId;
     }
@@ -140,6 +152,10 @@ public String getRecommId() {
          return this.recommId;
     }
 
+    public Map<String, Object> getAdditionalData() {
+         return this.additionalData;
+    }
+
     /**
      * @return Used HTTP method
      */
@@ -193,6 +209,9 @@ public Map<String, Object> getBodyParameters() {
         if (this.recommId!=null) {
             params.put("recommId", this.recommId);
         }
+        if (this.additionalData!=null) {
+            params.put("additionalData", this.additionalData);
+        }
         return params;
     }
 

src/main/java/com/recombee/api_client/api_requests/AddRating.java

@@ -39,6 +39,10 @@ public class AddRating extends Request {
      * If this rating is based on a recommendation request, `recommId` is the id of the clicked recommendation.
      */
     protected String recommId;
+    /**
+     * A dictionary of additional data for the interaction.
+     */
+    protected Map<String, Object> additionalData;
 
     /**
      * Construct the request
@@ -77,6 +81,14 @@ public AddRating setRecommId(String recommId) {
          return this;
     }
 
+    /**
+     * @param additionalData A dictionary of additional data for the interaction.
+     */
+    public AddRating setAdditionalData(Map<String, Object> additionalData) {
+         this.additionalData = additionalData;
+         return this;
+    }
+
     public String getUserId() {
          return this.userId;
     }
@@ -102,6 +114,10 @@ public String getRecommId() {
          return this.recommId;
     }
 
+    public Map<String, Object> getAdditionalData() {
+         return this.additionalData;
+    }
+
     /**
      * @return Used HTTP method
      */
@@ -147,6 +163,9 @@ public Map<String, Object> getBodyParameters() {
         if (this.recommId!=null) {
             params.put("recommId", this.recommId);
         }
+        if (this.additionalData!=null) {
+            params.put("additionalData", this.additionalData);
+        }
         return params;
     }
 

src/main/java/com/recombee/api_client/api_requests/RecommendItemsToItem.java

@@ -13,6 +13,7 @@
 /**
  * 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 {
 
@@ -138,6 +139,10 @@ public class RecommendItemsToItem extends Request {
      * Dictionary of custom options.
      */
     protected Map<String, Object> expertSettings;
+    /**
+     * If there is a custom AB-testing running, return name of group to which the request belongs.
+     */
+    protected Boolean returnAbGroup;
 
     /**
      * Construct the request
@@ -310,6 +315,14 @@ public RecommendItemsToItem setExpertSettings(Map<String, Object> 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;
     }
@@ -372,6 +385,11 @@ public Map<String, Object> getExpertSettings() {
          return this.expertSettings;
     }
 
+    public boolean getReturnAbGroup() {
+         if (this.returnAbGroup==null) return false;
+         return this.returnAbGroup;
+    }
+
     /**
      * @return Used HTTP method
      */
@@ -443,6 +461,9 @@ public Map<String, Object> getBodyParameters() {
         if (this.expertSettings!=null) {
             params.put("expertSettings", this.expertSettings);
         }
+        if (this.returnAbGroup!=null) {
+            params.put("returnAbGroup", this.returnAbGroup);
+        }
         return params;
     }
 

src/main/java/com/recombee/api_client/api_requests/RecommendItemsToUser.java

@@ -13,6 +13,7 @@
 /**
  * Based on user's past interactions (purchases, ratings, etc.) with the items, recommends top-N items that are most likely to be of high value for a given user.
  * It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.
+ * The returned items are sorted by relevancy (first item being the most relevant).
  */
 public class RecommendItemsToUser extends Request {
 
@@ -118,6 +119,10 @@ public class RecommendItemsToUser extends Request {
      * Dictionary of custom options.
      */
     protected Map<String, Object> expertSettings;
+    /**
+     * If there is a custom AB-testing running, return name of group to which the request belongs.
+     */
+    protected Boolean returnAbGroup;
 
     /**
      * Construct the request
@@ -268,6 +273,14 @@ public RecommendItemsToUser setExpertSettings(Map<String, Object> expertSettings
          return this;
     }
 
+    /**
+     * @param returnAbGroup If there is a custom AB-testing running, return name of group to which the request belongs.
+     */
+    public RecommendItemsToUser setReturnAbGroup(boolean returnAbGroup) {
+         this.returnAbGroup = returnAbGroup;
+         return this;
+    }
+
     public String getUserId() {
          return this.userId;
     }
@@ -322,6 +335,11 @@ public Map<String, Object> getExpertSettings() {
          return this.expertSettings;
     }
 
+    public boolean getReturnAbGroup() {
+         if (this.returnAbGroup==null) return false;
+         return this.returnAbGroup;
+    }
+
     /**
      * @return Used HTTP method
      */
@@ -389,6 +407,9 @@ public Map<String, Object> getBodyParameters() {
         if (this.expertSettings!=null) {
             params.put("expertSettings", this.expertSettings);
         }
+        if (this.returnAbGroup!=null) {
+            params.put("returnAbGroup", this.returnAbGroup);
+        }
         return params;
     }