Skip to end of metadata
Go to start of metadata
All request URLs in the document are relative to the application root. E.g. if the web application is deployed at and this document says to request /recommend/behavioural, the full URL would be

Behavioural recommendations are based on user's profile. They combine knowledge on what the user is interested in with a set of configuration parameters that define weight for each factor.

Let us consider a simple example.

Let us have 2 categories of articles:

  • Articles with IDs of doc-garden-1, doc-garden-2, etc. are related to gardens, garden tools, flowers and so on.
  • Articles with IDs of doc-travel-1, doc-travel-2 etc. are related to geographic places. They mostly contain names of such places, transportation terms etc.

In our example articles of the second category are more visited - they have 4 times more reads on average than the garden articles.
Let us have an user with ID of test-user-1. They have read 2 articles only: doc-garden-1 and doc-garden-3.

We can get recommended content for this user by calling:

This is the result:

Although the user is interested mostly in gardens, the travel articles are on the top of the list. Higher relevance score is calculated for them. This is due to the fact that they are more popular - that is, they have been visited more often.

The popularity weight may be lowered by POST-ing the request and adding JSON-encoded weight parameter like this:

Content-type of the request should be application/json. See Advanced recommendation parameters for more information

This would change weight of popularity to 0.2 (down from the default 0.9) and the result would be:

Note how relevance scores have changed when popularity is not that important for relevance score.

We can also combine user's profile with what content they are currently looking at. Scenarios like this could be:

  • User is reading a news article and we want to recommend them more articles to read.
  • User may be reviewing a CV and we may want to recommend suitable job descriptions

The way to add this contextual information is via the contentid parameter:

Now, as both user's profile and related content is about gardens, we get:


/recommend/behavioural has the following query parameters:

  • userid (required) - the user to return recommendations for
  • contentid (optional) - existing article identifier. If passed, recommendations will be computed with respect to this article and the user history
  • count (optional, default = 10) - maximum number of articles to return
  • sort (optional, default = rel) - sorting method, valid arguments are "pop"(popularity), "rel"(relevancy) and "date"
  • recency (optional, default = <empty>) - limit the age of articles returned by the recommendation. Supported values for recency are "amonthago", "aweekago", and integers representing the maximum number of days to go back. For example recency=5 will only return articles newer than five days ago. If omitted, no age filter is applied
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.