/docs/manual/source/templates/recommendation/quickstart.html.md.erb

---
title: Quick Start - Recommendation Engine Template
---

## Overview

This Recommendation Engine Template has integrated **Apache Spark MLlib**'s
Collaborative Filtering algorithm by default. You can customize it easily to fit
your specific needs.

We are going to show you how to create your own recommendation engine for
production use based on this template.

## Usage

### Event Data Requirements

By default, the template requires the following events to be collected:

- user 'rate' item events
- user 'buy' item events

NOTE: You can customize to use other event.

### Input Query

- user ID
- num of recomended items

### Output PredictedResult

- a ranked list of recommended itemIDs


## 1. Install and Run PredictionIO

<%= partial 'shared/quickstart/install' %>

## 2. Create a new Engine from an Engine Template

<%= partial 'shared/quickstart/create_engine', locals: { engine_name: 'MyRecommendation', template_name: 'Recommendation Engine Template', template_repo: 'template-scala-parallel-recommendation' } %>

## 3. Generate an App ID and Access Key

<%= partial 'shared/quickstart/create_app' %>

## 4. Collecting Data

Next, let's collect some training data. By default,
the Recommendation Engine Template supports 2 types of events: **rate** and
**buy**. A user can give a rating score to an item or he can buy an item. This template requires user-view-item and user-buy-item events.

INFO: This template can easily be customized to consider more user events such as *like*, *dislike* etc.

<%= partial 'shared/quickstart/collect_data' %>

For example, when a user with ID "u0" rate an item with ID "i0" with rating of 5 on time `2014-11-02T09:39:45.618-08:00` (current time will be used if eventTime is not specified), you can send the following "rate" event. Run the following `curl` command:

<div class="tabs">
  <div data-tab="REST API" data-lang="json">
```
$ curl -i -X POST http://localhost:7070/events.json?accessKey=$ACCESS_KEY \
-H "Content-Type: application/json" \
-d '{
  "event" : "rate",
  "entityType" : "user",
  "entityId" : "u0",
  "targetEntityType" : "item",
  "targetEntityId" : "i0",
  "properties" : {
    "rating" : 5
  }
  "eventTime" : "2014-11-02T09:39:45.618-08:00"
}'
```
  </div>
  <div data-tab="Python SDK" data-lang="python">
```python
import predictionio

client = predictionio.EventClient(
    access_key=<ACCESS KEY>,
    url=<URL OF EVENTSERVER>,
    threads=5,
    qsize=500
)

# A user rates an item
client.create_event(
    event="rate",
    entity_type="user",
    entity_id=<USER ID>,
    target_entity_type="item",
    target_entity_id=<ITEM ID>,
    properties= { "rating" : float(<RATING>) }
)
```
  </div>

  <div data-tab="PHP SDK" data-lang="php">
```php
<?php
require_once("vendor/autoload.php");
use predictionio\EventClient;

$client = new EventClient(<ACCESS KEY>, <URL OF EVENTSERVER>);

// A user rates an item
$client->createEvent(array(
   'event' => 'rate',
   'entityType' => 'user',
   'entityId' => <USER ID>,
   'targetEntityType' => 'item',
   'targetEntityId' => <ITEM ID>,
   'properties' => array('rating'=> <RATING>)
));
?>
```
  </div>
  <div data-tab="Ruby SDK" data-lang="ruby">
```ruby
# Create a client object.
client = PredictionIO::EventClient.new(<ACCESS KEY>, <URL OF EVENTSERVER>)

# A user rates an item.
client.create_event(
  'rate',
  'user',
  <USER ID>, {
    'targetEntityType' => 'item',
    'targetEntityId' => <ITEM ID>,
    'properties' => { 'rating' => <RATING (float)> }
  }
)

```
  </div>
  <div data-tab="Java SDK" data-lang="java">
```java
import org.apache.predictionio.Event;
import org.apache.predictionio.EventClient;

EventClient client = new EventClient(<ACCESS KEY>, <URL OF EVENTSERVER>);

// A user rates an item
Event rateEvent = new Event()
    .event("rate")
    .entityType("user")
    .entityId(<USER_ID>)
    .targetEntityType("item")
    .targetEntityId(<ITEM_ID>)
    .property("rating", new Float(<RATING>));
client.createEvent(rateEvent);

```
  </div>
</div>

When a user with ID "u1" buy an item with ID "i2" on time `2014-11-10T12:34:56.123-08:00` (current time will be used if eventTime is not specified), you can send the following "rate" event. Run the following `curl` command:

<div class="tabs">
  <div data-tab="REST API" data-lang="json">
```
$ curl -i -X POST http://localhost:7070/events.json?accessKey=$ACCESS_KEY \
-H "Content-Type: application/json" \
-d '{
  "event" : "buy",
  "entityType" : "user",
  "entityId" : "u1",
  "targetEntityType" : "item",
  "targetEntityId" : "i2",
  "eventTime" : "2014-11-10T12:34:56.123-08:00"
}'
```
  </div>
  <div data-tab="Python SDK" data-lang="python">
```python
# A user buys an item
client.create_event(
    event="buy",
    entity_type="user",
    entity_id=<USER ID>,
    target_entity_type="item",
    target_entity_id=<ITEM ID>
)
```
  </div>

  <div data-tab="PHP SDK" data-lang="php">
```php
<?php
// A user buys an item
$client->createEvent(array(
   'event' => 'buy',
   'entityType' => 'user',
   'entityId' => <USER ID>,
   'targetEntityType' => 'item',
   'targetEntityId' => <ITEM ID>
));
?>
```
  </div>
  <div data-tab="Ruby SDK" data-lang="ruby">
```ruby
# A user buys an item.
client.create_event(
  'buy',
  'user',
  <USER ID>, {
    'targetEntityType' => 'item',
    'targetEntityId' => <ITEM ID>
  }
)
```
  </div>
  <div data-tab="Java SDK" data-lang="java">
```java
// A user buys an item
Event buyEvent = new Event()
    .event("buy")
    .entityType("user")
    .entityId(<USER_ID>)
    .targetEntityType("item")
    .targetEntityId(<ITEM_ID>);
client.createEvent(buyEvent);
```
  </div>
</div>

<%= partial 'shared/quickstart/query_eventserver' %>

### Import More Sample Data

<%= partial 'shared/quickstart/import_sample_data' %>

A Python import script `import_eventserver.py` is provided in the template to import the data to
Event Server using Python SDK. Please upgrade to the latest Python SDK.

<%= partial 'shared/quickstart/install_python_sdk' %>

Replace the value of access_key parameter by your
**Access Key** and run:

WARNING: These commands must be executed in the Engine directory, for example: `MyRecomendation`.

```
$ cd MyRecommendation
$ curl https://raw.githubusercontent.com/apache/spark/master/data/mllib/sample_movielens_data.txt --create-dirs -o data/sample_movielens_data.txt
$ python data/import_eventserver.py --access_key $ACCESS_KEY
```

You should see the following output:

```
Importing data...
1501 events are imported.
```

Now the movie ratings data is stored as events inside the Event Store.

<%= partial 'shared/quickstart/query_eventserver_short' %>

INFO: By default, the template train the model with "rate" events (explicit rating). You can customize the engine to [read other custom events](/templates/recommendation/reading-custom-events/) and [handle events of implicit preference (such as, view, buy)](/templates/recommendation/training-with-implicit-preference/)

## 5. Deploy the Engine as a Service

<%= partial 'shared/quickstart/deploy_enginejson', locals: { engine_name: 'MyRecommendation' } %>

<%= partial 'shared/quickstart/deploy', locals: { engine_name: 'MyRecommendation' } %>

## 6. Use the Engine

Now, You can try to retrieve predicted results. To recommend 4 movies to user
whose id is 1, you send this JSON `{ "user": "1", "num": 4 }` to the deployed
engine and it will return a JSON of the recommended movies. Simply send a query
by making a HTTP request or through the `EngineClient` of an SDK.

With the deployed engine running, open another temrinal and run the following `curl` command or use SDK to send the query:

<div class="tabs">
  <div data-tab="REST API" data-lang="json">
```
$ curl -H "Content-Type: application/json" \
-d '{ "user": "1", "num": 4 }' http://localhost:8000/queries.json

```
  </div>

  <div data-tab="Python SDK" data-lang="python">
```python
import predictionio
engine_client = predictionio.EngineClient(url="http://localhost:8000")
print engine_client.send_query({"user": "1", "num": 4})
```
  </div>
  <div data-tab="PHP SDK" data-lang="php">
```php
<?php
require_once("vendor/autoload.php");
use predictionio\EngineClient;

$client = new EngineClient('http://localhost:8000');

$response = $client->sendQuery(array('user'=> 1, 'num'=> 4));
print_r($response);

?>
```
  </div>
  <div data-tab="Ruby SDK" data-lang="ruby">
```ruby
# Create client object.
client = PredictionIO::EngineClient.new(<ENGINE DEPLOY URL>)

# Query PredictionIO.
response = client.send_query('user' => <USER ID>, 'num' => <NUMBER (integer)>)

puts response
```
  </div>
  <div data-tab="Java SDK" data-lang="java">
```java
import com.google.common.collect.ImmutableMap;
import com.google.gson.JsonObject;

import org.apache.predictionio.EngineClient;

// create client object
EngineClient engineClient = new EngineClient(<ENGINE DEPLOY URL>);

// query
JsonObject response = engineClient.sendQuery(ImmutableMap.<String, Object>of(
        "user", "1",
        "num",  4
    ));
```
  </div>
</div>

The following is sample JSON response:

```
{
  "itemScores":[
    {"item":"22","score":4.072304374729956},
    {"item":"62","score":4.058482414005789},
    {"item":"75","score":4.046063009943821},
    {"item":"68","score":3.8153661512945325}
  ]
}
```

Congratulations, *MyRecommendation* is now running!

<%= partial 'shared/quickstart/production' %>

#### [Next: DASE Components Explained](/templates/recommendation/dase/)