Social Recommendations API
Added by IBM contributorIBM | Edited by Claudia R Elbourn on June 30, 2015
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars

This document describes the Social Recommendations API that is part of the IBM Connections Search.


The following graph depicts an abstraction of how the Social Recommendations API works. For each user there is a "user profile" (inside the dashed ellipse), which contains the people and tags most relevant to the user. The recommended items (on the right) are those which are related to the items in the user profile.

Social Recommendations API



The order of the parameters in the requests do not matter. The parameter names are case-sensitive; they must be entered in the format documented. Any unknown or unsupported parameters submitted as part of a request will be ignored.


The request should be a standard HTTP GET command. The URL is formed by combining the search server's host name, port and path; as well as a collection of name-value pairs (input parameters) separated by & characters. Any parameter value must be URL-escaped.

The diagram below illustrates Example 1 (Found further down):


Example 1

Method URI Description
GET /search/atom/social/recommend Basic
GET /search/{auth}/atom/social/recommend OAuth
Name Type Optional Description
enumerated No The authorization protocol being used by your application to access Connections Cloud.
Authorized values:
  • basic
  • oauth
Name Type Optional Description
string Yes Specifies the language to use to parse the search request. See ISO-639 and ISO-3166 for valid values, e.g. "en_US". This parameter is optional. When specified, the appropriate dictionary for the specified language is used. Note: The dictionary for the language specified must be enabled for this parameter to work.
int Yes Defines an offset from the first result in the set. This parameter is ignored if a page parameter is provided. This starts from 0. The default is 0. If specified value is negative, the value will be defaulted to 0; if the specified value is greater than the number of results, no results will be returned.
int Yes Specifies the page to be returned. The default value is 1, which returns the first page.
int Yes Specifies the number of entries to return per page. The minimum value is zero (negative values default to zero). The default value is 10. The maximum value you can specify is 150.
boolean Yes Specify if evidence information should be added to the results.
NB: Default value is true for Recommendations API but default for Search API is false.
string Yes Allows constraining the search results according to the provided criteria. Refer to Constraints for more information.
Same as for Search API except that only category constraints on the Source facet are supported.
number Yes A float. The higher this is, the more the document scores, of re-occurring document types in the result set, are penalized. (The i+1th occurrence of type T is penalized more that the ith occurrence)
boolean Yes A boolean. True if you want the order of the results to be randomized. Consequently result i+1 may have a higher score than result i.
number Yes A float. Used in the query, penalizes old results on the basis of the delta with the current time. The higher this is, the more the document score of older results are penalized.
Name Type Optional Description
enumerated No The authentication mechanism selected by your application to access the API.
Basic is the Base64 encoding of the IBM Connections Cloud username and password: Base64(username:password). For example, Base64(
Bearer is the oauth 2.0 access token that is generated when the user grants your application access to IBM Connections Cloud services.
See the reference topic "OAuth 2.0 APIs for web server flow" for more information.
Authorized values:
  • bearer
  • basic
Content Type: application/atom+xml
Code Description
Unauthorized. Returned when no authenticated user or no userid, email, or key parameter are provided on the request.
An important part of recommendations is the evidence which describes the reasoning for the different recommended items. The response, in each entry, contains a set of evidence elements which explain why this item was recommended. The response format for the Social Recommendations API is as defined for the Search API except for the addition of these ibmss:entity_evidence elements for each atom:entry element in the feed (unless the evidence parameter is set to false). An example:

Response returned by the server
<atom:title>The Theory of Moral Sentiments</atom:title> <atom:author>
<atom:name>Adam Smith</atom:name>

<atom:link href="" /> 



<atom:summary type="html">Division of moral philosophy. Division of moral systems. Nature and motive of morality.</atom:summary>

<ibmss:entity_evidence type="personUserID" id="Person1">
Person1's name

<ibmss:association_evidence type="author" to="006b7684-803f-4813-94fc-31f16862037c" count="1"/></ibmss:entity_evidence> 

<ibmss:entity_evidence type="personUserID" id="Person2">
Person2's name

<ibmss:association_evidence type="commenter" to="006b7684-803f-4813-94fc-31f16862037c" count="3"/></ibmss:entity_evidence>

<ibmss:entity_evidence type="tag" id="Tag2">
<ibmss:association_evidence type="usedOn" to="006b7684-803f-4813-94fc-31f16862037c" count="12"/></ibmss:entity_evidence>


In the Social Recommendations API response, each of the entity_evidence elements have a type and an id.

The type values for the entity_evidence are the same types defined for the type attribute of the "social" parameter of the Search API.

Each entity_evidence element has a child association_evidence element for each different type of association a person has with the recommendation.

The 'to' attribute of the association_evidence element will match the value of the 'id' element of the recommendation.