Florian Kleedorfer Stephan Zavrel

In this wiki you will find the documentation of the easiest to use open source recommender. If you have any further questions don't hesitate to contact us at the forums. If you are completely new to easyrec you may want to see how to get started. You might also want to have a glimpse at the frequently asked questions(FAQ).

For instructions on installing easyrec on your server, read the Installation Guide.

We have moved the most important parts of the documentation from the old MeadiWiki to this new place. However, you might still find some more advanced information that might be helpful at the old place http://easyrec.sourceforge.net/wiki/index.php/Main_Page. For the time being sourceforge seems to keep the old systems up and running.

What is easyrec

The easyrec project is an open source recommendation system providing a low barrier entrance to high quality recommendations to any website with personalization needs. The access to easyrec is provided through Web services assuring easy and quick integration. Immediate deployment is possible for web sites (e.g. scripts enclosing API calls, placed in the client's pages, see below). Its focus is simple integration; In most cases, the web-based administration interface should be sufficient for configuring easyrec. It is distributed under the '''GNU General Public License''' by the Studio Smart Agent Technologies and hosted at SourceForge. It is written in Java, uses a MySQL database and comes with an administration tool.

You can find out a bit more about the features here


Have a look at the easyrec Installation Guide to learn how to setup your own easyrec server.

API Documentation

If you want to integrate easyrec into you web platform check out our API documentation.

General Documentation

Basic concepts


An operator is associated with exactly one user account of an easyrec server. Each operator can create and manage a number of tenants to integrate easyrec recommendation services into multiple websites.
For each operator, an API key is generated that must be specified in API calls along with the appropriate tenant Id.


The easyrec server can provide recommendation services for multiple applications. Within easyrec, such applications are referred to as 'tenants', managed by an operator. Each tenant has a unique name which has to be provided in API calls, along with the operator's API key.
You can create a tenant in the web application administration interface. Currently you cannot change the tenant name later so choose it wisely.

Demo tenant

When you register with our demo instance or install the application on your own server you will automatically have a tenant named EASYREC_DEMO. Use this tenant to play around with easyrec - for example you could force the creation of rules by sending the following actions:



As soon as the scheduled rule calculation has run (2AM on the demo instance - or trigger it manually on your own instance) you will have a USER_ALSO_VIEWED rule between ITEM A and ITEM B


Items are easyrec representations of your content. Items get created automatically when you send actions to an easyrec web service. Once an item has been created you cannot delete it. However, you can deactivate it trough the easyrec web administration interface and it will not be in included in any recommendations. Any item is identified by the triple tenantId-itemId-itemType. Items are the basic unit of all recommender operations. Eventhough it might seem counter intuitive at first, in the context of easyrec even users are just items of the special type USER.

Item Types

An item type is a type of a specific item. It is saved together with the other item information when you send the first VIEW action or when you import an item using certain API calls (e.g. importitem, storeitemwithprofile). Item types have to be created explicitly within the easyrec web administration interface. Per default the item type ITEM is created and will be used whenever no other type is explicitly supplied.

Action Types

Each action has an action type. Per default the types VIEW, BUY and RATE are defined. Additional action types can be defined in the type manager within the easyrec web administration interface. Actions types can also specifiy an action value (e.g. a rating value for the type RATE) as well as a weight, so different actions can be weighted differently when analysing actions for recommendation generation. Generators use action types to select a subset of all actions for calculating Rules. For example, the SlopeOne Recommender generator only uses RATE actions, whereas the Association Rule Miner can be configured to use either VIEW or BUY actions.

Assoc Types

Assoc Types define the type of a relation two items have.

Typical examples for such Assoc Types are


Additional assoc types can be created in the type manager within the easyrec web application admin gui. Recommendation algorithms (or rule generators/plugins, as we call them) are associated to assoc types. This means, if you want to use additional generators, you have to create assoc types so that you can associate a plugin configuration to it and query the results using the API (e.g. the relateditems call).


A Rule is a weighted association between two items that has a certain association type. Rule Generators are used to compute these associations. The easyrec administration interface allows configuring how rules are generated for each association type.


A cluster groups a number of items and can be manually created. You can find more information at the Cluster page.

Profile System

easyrec 1.0 includes a JSON based profile system that allows to store additional metadata for items in JSON notation. For more information on how this works read the introduction to the profile system.


Association Rule Miner

Slope One

User Profile Aggregator

Developing easyrec

Coding Guide

Plugin Guide


You can download easyrec for free at https://sourceforge.net/projects/easyrec/ if you find it useful let us know by twittering it.

Demo Server

We're hosting a demo instance, so if you want to play around with easyrec start at http://easyrec.org/ and create an account. Then check the easyrec version deployed on our server and read the documentation for this version to get started.

Older versions

Our old Wiki can be found at: http://easyrec.sourceforge.net/wiki/index.php/Main_Page

Project Members:


Wiki: API
Wiki: ARM
Wiki: Action Types
Wiki: Assoc Types
Wiki: Cluster
Wiki: Coding Guide
Wiki: FAQ
Wiki: Installation Guide
Wiki: Item Types
Wiki: Plugin Guide
Wiki: Slope One
Wiki: UPA
Wiki: get_started

Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:

No, thanks