API

• General information
• Sending Actions
• Getting Recommendations
• Community Rankings
• Clusters
• Profile API
• Import and other functions
• AngularJS service
  • Enabling CORS
• Legacy Javascript API

General information

This page documents easyrec 1.0 and the API version 1.1. For documentation of older versions please refer to the old Wiki at http://easyrec.sourceforge.net/wiki/index.php/REST_API_v0.98

The easyrec API is able to receive actions from or send recommendations to your web application in REST style. All user actions sent to easyrec are analyzed by the ruleminer, which runs once a day by default. If significant similarities in user behaviour can be found, recommendations are generated and are accessable instantly using the recommendation web services. The evaluation service of easyrec supports the actions view, buy and rate together with the corresponding recommendation functions otherusersalsoviewed, otherusersalsobought and itemsratedgoodbyotherusers. You can use the API Test Tool for playing around with the API functions.

Note that it is not necessary to upload your item information - all information about your items is collected from the view/buy/rate actions.

The recommendations are calculated with an algorithm for market basket analysis. In order to support quick evaluation, the significance levels are set very low: as soon as two different users perform the same action on the same two items recommendations are generated API

The easyrec API allows you to call methods that respond in XML or JSON. Individual methods are detailed in this document. You can call a method by using an HTTP GET to retrieve XML

http://serverURL:port/easyrec-web/api/1.1/{method}

along with method specific arguments. Using

http://serverURL:port/easyrec-web/api/1.1/json/{method}

will return the result in JSON style. Click here for a demonstration on how to use easyrec together with JSON queries.

Every method requires your API Key (e.g. 8ab9dc3ffcdac576d0f298043a60517a) and a tenantId (e.g. EASYREC_DEMO) as input parameters.

Where applicable, the maximum number of results returned is 15

Use UTF-8 encoding when sending arguments to API methods.

Sending Actions

[ActionAPI]

Getting Recommendations

[RecommendationAPI]

Community Rankings

[RankingsAPI]

Clusters

[ClusterAPI]

Profile API

[ProfileAPI]

Import and other functions

[ImportAPI]

AngularJS service

As of easyrec 1.0 we provide an AngularJS service for javascript based integration of easyrec. The former Javascript API based on JSON with padding is considered legagcy now and does not support all API calls provided by easyrec. It'll still work but if you want to use easyrec to its full capability yo will have to switch to the AngularJS service or implement your own Javascript client.

To use the AngularJS service add the following script tag to your application's index.html:

<script src="http://demo.easyrec.org/api-js/angularjs/easyrec.js"></script>

In case you don't use the easyrec demo service but your own hosted setup change the URL accordingly!
When bootstrapping your AngularJS application, add the easyrecServices as a module dependency, e.g.

var myApplication = angular.module('myapplication', ['myApplicationControllers', 'easyrecServices', 'ngRoute']);

Then, in the config block of your application configure theeasyrecProvider with the appropriate baseURL, tenant and API key:

myApplication.config(['$routeProvider', '$locationProvider','easyrecProvider',
    function($routeProvider, $locationProvider, easyrecProvider) {
        ...
        easyrecProvider.setBaseUrl('http://demo.easyrec.org/easyrec-web');
        easyrecProvider.setApiKey('8ab9dc3ffcdac576d0f298043a60517a');
        easyrecProvider.setTenant('EASYREC_DEMO');  

        ...
    }]).run([...

You can inject the easyrec service as module dependency in your controllers whenever you want to call the easyrec API.
The best way to see all the available functions of the easyrec AngularJS service is to take a look at the source of the API Tester and Profile API Tester page in the easyrec Admin GUI. An example for a view call can be found below:

easyrec.view($scope.sessionid, 
        $scope.itemid,
        $scope.itemtype,
        $scope.itemdescription,
        $scope.itemurl,
        $scope.itemimageurl,
        $scope.userid,
        $scope.actioninfo,
        $scope.actiontime,
        $scope.token).then(
    function(data, status) {
        $scope.status = status;
        $scope.data = data;
        }, function(data, status) {
        $scope.status = status;
        $scope.data = data || "Request failed"; 
});

You can take a look at the complete API Tester source and the easyrec AngularJS service source to get a better understanding of all the function calls available and how they work.

Enabling CORS

For the AngularJS service to work you need to enable CORS on your server if you host easyrec in your own environment. Other we will get errors because of the violation of the Cross Origin Request policies in the browser. The page enable-cors.org has a good overview about the most commonly used Web Server implementations and how to enable CORS.

Legacy Javascript API

You can still use our old javascript API as decribed at http://easyrec.sourceforge.net/wiki/index.php?title=JavaScript_API_v0.98. However, this API is considered legagcy. It will not be developed further and misses a lot of new API functions including the profile system.