Interface

The Recommendation Engine (abbreviated as Gravity Reco) offers the possibility to generate recommendations for off-line usage, such as a newsletter sent out periodically. The image below offers a quick glance at how the system works:

• The FTP Server is operated by gravity and our clients get access by ordering our batch processing API. This is the place where the customer will upload his recommendation requests and from where he may download the results for those.
• For communicating with the Reco servers tab-delimited and XML files are used. These will be transferred over the network by using the FTP or SFTP protocol.

The following sections contain information on the exact usage details, like the work flow of transferring the files and file formats to use.

Batch recommender workflow

📘

NOTE:

Depending on the size of the customers item and user database the second phase may turn out to be quite lengthy (one to three hours). Take this into consideration when you are planning just how often do you want to request batch recommendations.

📘

NOTE:

To avoid long and single burst data transfer we recommend splitting the recommendation requests into 5,000-10,000 request chunks. The above process is valid for one single chunk. The customer needs to go through the work flow for each and every batch. To differentiate between two recommendation requests (batches) we use a date based naming convention. The batch interface of the Reco communicates with the FTP server through the existence and name of the files on the FTP server. The process is guided by the presence and the name of a special file, also refereed to as the marker file.

Recommendation request file

The recommendation engine accepts batch recommendation requests in tab-delimited format. For the description of this format, see the Tab-delimited item example page.

In addition:

• In this case each line contains a recommendation request.
• The userId and scenarioId columns are mandatory. The others are optional.

For example, to get NEWSLETTER scenario recommendations for users 1 and 2, a valid request file specifies in its first row the name of the columns and then follows it up with enumerating the values corresponding to those:

If the recommendation request has another parameters, you can add them as columns. Column name considers the key (name of the attribute), column values are the attribute values. Example:

NOTE: These additional parameters only have an influence on the recommendation result if the usage of the parameter is built in the scenario logic.

If the result should contain additional item properties beside the item ID-s (like in the example below) please add the name of those properties in additional columns:

Recommendation answer file

The answer file for a recommendation request is an XML file (ItemRecommendations 1 0.xsd).

The file contains recommendations for every requested user. For example, in case of the upper request file a valid answer may be:

<recommendations xmlns="http://schemas.gravityrd.com/receng/itemRecommendations_1_0.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"                
xsi:schemaLocation="http://schemas.gravityrd.com/receng/itemRecommendations_1_0.xsd itemRecommendations_1_0.xsd">
    <!-- One recommendation item for each recommendation -->
    <recommendation recommendationId="j4edn6m1-59pj6p0lreu-S.NEWSLETTER.C.c91_a92-1eomy5w">
        <!-- The original recommendation request can be included -->
        <request>
            <userId></userId>
            <cookieId></cookieId>
            <scenarioId></scenarioId>
            <numberLimit>1</numberLimit>
            <properties>
                <property name="filter.category" value="100"/>
            </properties>        
        </request>
        <items>
            <!-- The list of recommended items -->
            <item itemId="1" predictionValue="0.4" modifiedPredictionValue="1.2">
                <itemProperties>
                    <property name="title" value="Example Item Title 1"/>
                    <property name="product" value="Product"/>
                    <property name="imgUrl" value="http://webshop.example.com/img1.jpg"/>
                    <property name="price" value="10.0"/>
                    <property name="category" value="100"/>
                </itemProperties>
            </item>
            <item itemId="2" predictionValue="0.5">
                <itemProperties>
                    <property name="title" value="Example Item Title 2"/>
                    <property name="product" value="Product"/>
                    <property name="imgUrl" value="http://webshop.example.com/img2.jpg"/>
                    <property name="price" value="20.0"/>
                    <property name="category" value="100"/>
                </itemProperties>
            </item>
        </items>     
    </recommendation>
</recommendations>

FTP interface set up and configuration

This is done solely on request by the Gravity R&D staff. May the customer wish to use this feature he will need to contact the Gravity R&D personal [email protected].