Skip to content

Commit 3f80bd1

Browse files
OndraFiedlerOndraFiedler
committed
Java client for Recombee API
0 parents  commit 3f80bd1

File tree

173 files changed

+10809
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

173 files changed

+10809
-0
lines changed

‎LICENSE.txt‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
The MIT License (MIT)
2+
3+
Copyright (c) 2015 Recombee s.r.o.
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in
13+
all copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21+
THE SOFTWARE.

‎README.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
# Recombee API Client
2+
3+
A Java client for easy use of the [Recombee](https://www.recombee.com/) recommendation API.
4+
5+
If you don't have an account at Recombee yet, you can create a free account [here](https://www.recombee.com/).
6+
7+
Documentation of the API can be found at [docs.recombee.com](https://docs.recombee.com/).
8+
9+
## Installation
10+
11+
The client shall be available in the Maven Central Repository within days.
12+
Until then, you can use [jitpack](https://jitpack.io/#Recombee/java-api-client) for an easy install.
13+
14+
## Examples
15+
16+
### Basic example
17+
18+
Examples are located in [src/examples](https://github.com/Recombee/java-api-client/tree/master/src/examples/java/com/recombee/api_client/examples/).
19+
20+
```java
21+
package com.recombee.api_client.examples;
22+
23+
import com.recombee.api_client.RecombeeClient;
24+
import com.recombee.api_client.api_requests.*;
25+
import com.recombee.api_client.bindings.Recommendation;
26+
import com.recombee.api_client.exceptions.ApiException;
27+
28+
import java.util.ArrayList;
29+
import java.util.Random;
30+
31+
public class BasicExample {
32+
public static void main(String[] args) {
33+
34+
RecombeeClient client = new RecombeeClient("client-test", "jGGQ6ZKa8rQ1zTAyxTc0EMn55YPF7FJLUtaMLhbsGxmvwxgTwXYqmUk5xVZFw98L");
35+
try {
36+
final int NUM = 100;
37+
//Create some users and send them to Recombee, use Batch for faster processing
38+
ArrayList<Request> addUserRequests = new ArrayList<Request>();
39+
for (int i = 0; i < NUM; i++) addUserRequests.add(new AddUser(String.format("user-%s", i)));
40+
41+
System.out.println("Send users");
42+
client.send(new Batch(addUserRequests));
43+
44+
//Now create some items
45+
ArrayList<Request> addItemRequests = new ArrayList<Request>();
46+
for (int i = 0; i < NUM; i++) addItemRequests.add(new AddItem(String.format("item-%s", i)));
47+
48+
System.out.println("Send items");
49+
client.send(new Batch(addItemRequests));
50+
51+
// Generate some random purchases of items by users
52+
final double PROBABILITY_PURCHASED = 0.01;
53+
Random r = new Random();
54+
ArrayList<Request> addPurchaseRequests = new ArrayList<Request>();
55+
for (int i = 0; i < NUM; i++)
56+
for (int j = 0; j < NUM; j++)
57+
if (r.nextDouble() < PROBABILITY_PURCHASED)
58+
addPurchaseRequests.add(new AddPurchase(String.format("user-%s", i),String.format("item-%s", j)));
59+
60+
System.out.println("Send purchases");
61+
client.send(new Batch(addPurchaseRequests));
62+
63+
// Get 5 recommendations for user 'user-25'
64+
Recommendation[] recommended = client.send(new UserBasedRecommendation("user-25", 5));
65+
System.out.println("Recommended items:");
66+
for(Recommendation rec: recommended) System.out.println(rec.getId());
67+
68+
} catch (ApiException e) {
69+
e.printStackTrace();
70+
//use fallback
71+
}
72+
}
73+
}
74+
75+
```
76+
77+
### Using property values
78+
```java
79+
package com.recombee.api_client.examples;
80+
81+
import com.recombee.api_client.RecombeeClient;
82+
import com.recombee.api_client.api_requests.*;
83+
import com.recombee.api_client.bindings.Recommendation;
84+
import com.recombee.api_client.exceptions.ApiException;
85+
86+
import java.util.ArrayList;
87+
import java.util.HashMap;
88+
import java.util.Random;
89+
90+
public class ItemPropertiesExample {
91+
public static void main(String[] args) {
92+
93+
RecombeeClient client = new RecombeeClient("client-test", "jGGQ6ZKa8rQ1zTAyxTc0EMn55YPF7FJLUtaMLhbsGxmvwxgTwXYqmUk5xVZFw98L");
94+
95+
try {
96+
client.send(new ResetDatabase()); //Clear everything from the database
97+
98+
/*
99+
We will use computers as items in this example
100+
Computers have three properties
101+
- price (floating point number)
102+
- number of processor cores (integer number)
103+
- description (string)
104+
*/
105+
106+
client.send(new AddItemProperty("price", "double"));
107+
client.send(new AddItemProperty("num-cores", "int"));
108+
client.send(new AddItemProperty("description", "string"));
109+
110+
// Prepare requests for setting a catalog of computers
111+
final ArrayList<Request> requests = new ArrayList<Request>();
112+
final int NUM = 100;
113+
final Random rand = new Random();
114+
115+
for(int i=0; i<NUM; i++)
116+
{
117+
final SetItemValues req = new SetItemValues(
118+
String.format("computer-%s",i), //itemId
119+
//values:
120+
new HashMap<String, Object>() {{
121+
put("price", 600.0 + 400*rand.nextDouble());
122+
put("num-cores", 1 + rand.nextInt(7));
123+
put("description", "Great computer");
124+
put("!cascadeCreate", true); // Use !cascadeCreate for creating item
125+
// with given itemId, if it doesn't exist
126+
}}
127+
);
128+
requests.add(req);
129+
}
130+
client.send(new Batch(requests)); // Send catalog to the recommender system
131+
132+
// Generate some random purchases of items by users
133+
final double PROBABILITY_PURCHASED = 0.02;
134+
ArrayList<Request> addPurchaseRequests = new ArrayList<Request>();
135+
for (int i = 0; i < NUM; i++)
136+
for (int j = 0; j < NUM; j++)
137+
if (rand.nextDouble() < PROBABILITY_PURCHASED) {
138+
AddPurchase req = new AddPurchase(String.format("user-%s", i),String.format("computer-%s", j))
139+
.setCascadeCreate(true); //use cascadeCreate to create the users
140+
addPurchaseRequests.add(req);
141+
}
142+
client.send(new Batch(addPurchaseRequests)); // Send purchases to the recommender system
143+
144+
145+
// Get 5 recommendations for user-42, who is currently viewing computer-6
146+
Recommendation[] recommended = client.send(new ItemBasedRecommendation("computer-6", 5)
147+
.setTargetUserId("user-42"));
148+
System.out.println("Recommended items:");
149+
for(Recommendation rec: recommended) System.out.println(rec.getId());
150+
151+
152+
// Get 5 recommendations for user-42, but recommend only computers that have at least 3 cores
153+
recommended = client.send(new ItemBasedRecommendation("computer-6", 5).setTargetUserId("user-42")
154+
.setFilter(" 'num-cores'>=3 "));
155+
System.out.println("Recommended items with at least 3 processor cores:");
156+
for(Recommendation rec: recommended) System.out.println(rec.getId());
157+
158+
// Get 5 recommendations for user-42, but recommend only items that are more expensive then currently viewed item (up-sell)
159+
recommended = client.send(new ItemBasedRecommendation("computer-6", 5).setTargetUserId("user-42")
160+
.setFilter(" 'price' > context_item[\"price\"] "));
161+
162+
System.out.println("Recommended up-sell items:");
163+
for(Recommendation rec: recommended) System.out.println(rec.getId());
164+
165+
} catch (ApiException e) {
166+
e.printStackTrace();
167+
//Use fallback
168+
}
169+
}
170+
}
171+
172+
```
173+
174+
## Exception handling
175+
176+
Various errors can occur while processing request, for example because of adding an already existing item or submitting interaction of nonexistent user without *setCascadeCreate(true)*. These errors lead to throwing the *ResponseException* by the *send* method of the client. Another reason for throwing an exception is a timeout. *ApiException* is the base class of both *ResponseException* and *ApiTimeoutException*.
177+
178+
We are doing our best to provide the fastest and most reliable service, but production-level applications must implement a fallback solution since errors can always happen. The fallback might be, for example, showing the most popular items from the current category, or not displaying recommendations at all.

‎pom.xml‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<project xmlns="http://maven.apache.org/POM/4.0.0"
3+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
5+
<modelVersion>4.0.0</modelVersion>
6+
7+
<groupId>com.recombee</groupId>
8+
<artifactId>api-client</artifactId>
9+
<version>1.2.3</version>
10+
11+
<name>Recombee API Client</name>
12+
<description>A client library for easy use of the Recombee recommendation API</description>
13+
<url>http://recombee.com</url>
14+
15+
<licenses>
16+
<license>
17+
<name>MIT License</name>
18+
<url>http://www.opensource.org/licenses/mit-license.php</url>
19+
<distribution>repo</distribution>
20+
</license>
21+
</licenses>
22+
23+
<scm>
24+
<url>https://github.com/Recombee/java-api-client</url>
25+
<connection>scm:git:[email protected]:Recombee/java-api-client.git</connection>
26+
<developerConnection>scm:git:[email protected]:Recombee/java-api-client.git</developerConnection>
27+
</scm>
28+
29+
<developers>
30+
<developer>
31+
<id>ondra_fiedler</id>
32+
<name>Ondrej Fiedler</name>
33+
<email>[email protected]</email>
34+
<url>https://github.com/OndraFiedler</url>
35+
<organization>Recombee</organization>
36+
<organizationUrl>http://recombee.com</organizationUrl>
37+
</developer>
38+
</developers>
39+
40+
<dependencies>
41+
<dependency>
42+
<groupId>com.mashape.unirest</groupId>
43+
<artifactId>unirest-java</artifactId>
44+
<version>1.4.9</version>
45+
</dependency>
46+
<dependency>
47+
<groupId>com.fasterxml.jackson.core</groupId>
48+
<artifactId>jackson-core</artifactId>
49+
<version>2.8.1</version>
50+
</dependency>
51+
<dependency>
52+
<groupId>com.fasterxml.jackson.core</groupId>
53+
<artifactId>jackson-databind</artifactId>
54+
<version>2.8.1</version>
55+
</dependency>
56+
<dependency>
57+
<groupId>junit</groupId>
58+
<artifactId>junit</artifactId>
59+
<version>4.12</version>
60+
</dependency>
61+
<dependency>
62+
<groupId>commons-lang</groupId>
63+
<artifactId>commons-lang</artifactId>
64+
<version>2.6</version>
65+
</dependency>
66+
</dependencies>
67+
</project>

‎src/examples/java/com/recombee/api_client/examples/BasicExample.java‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
package com.recombee.api_client.examples;
2+
3+
import com.recombee.api_client.RecombeeClient;
4+
import com.recombee.api_client.api_requests.*;
5+
import com.recombee.api_client.bindings.Recommendation;
6+
import com.recombee.api_client.exceptions.ApiException;
7+
8+
import java.util.ArrayList;
9+
import java.util.Random;
10+
11+
public class BasicExample {
12+
public static void main(String[] args) {
13+
14+
RecombeeClient client = new RecombeeClient("client-test", "jGGQ6ZKa8rQ1zTAyxTc0EMn55YPF7FJLUtaMLhbsGxmvwxgTwXYqmUk5xVZFw98L");
15+
try {
16+
final int NUM = 100;
17+
//Create some users and send them to Recombee, use Batch for faster processing
18+
ArrayList<Request> addUserRequests = new ArrayList<Request>();
19+
for (int i = 0; i < NUM; i++) addUserRequests.add(new AddUser(String.format("user-%s", i)));
20+
21+
System.out.println("Send users");
22+
client.send(new Batch(addUserRequests));
23+
24+
//Now create some items
25+
ArrayList<Request> addItemRequests = new ArrayList<Request>();
26+
for (int i = 0; i < NUM; i++) addItemRequests.add(new AddItem(String.format("item-%s", i)));
27+
28+
System.out.println("Send items");
29+
client.send(new Batch(addItemRequests));
30+
31+
// Generate some random purchases of items by users
32+
final double PROBABILITY_PURCHASED = 0.01;
33+
Random r = new Random();
34+
ArrayList<Request> addPurchaseRequests = new ArrayList<Request>();
35+
for (int i = 0; i < NUM; i++)
36+
for (int j = 0; j < NUM; j++)
37+
if (r.nextDouble() < PROBABILITY_PURCHASED)
38+
addPurchaseRequests.add(new AddPurchase(String.format("user-%s", i),String.format("item-%s", j)));
39+
40+
System.out.println("Send purchases");
41+
client.send(new Batch(addPurchaseRequests));
42+
43+
// Get 5 recommendations for user 'user-25'
44+
Recommendation[] recommended = client.send(new UserBasedRecommendation("user-25", 5));
45+
System.out.println("Recommended items:");
46+
for(Recommendation rec: recommended) System.out.println(rec.getId());
47+
48+
} catch (ApiException e) {
49+
e.printStackTrace();
50+
//use fallback
51+
}
52+
}
53+
}

0 commit comments

Comments
 (0)