Recommendations

Page is marked as "withdrawn" on Drupal site.

Summary

Providing content recommendations is a good way to drive up content consumption, as the content provided is curated based on the user's consumption habits so should be more relevant to their tastes. Whilst providing some form of similar-content recommendations is fairly trivial, providing great recommendations based on user habits is a complex task that requires a fully-featured recommendation engine.

The OpenTV Platform supports both the use of static content-to-content recommendations defined by the operator or a created by a recommendation engine, and dynamic recommendations derived in real time from a recommendation engine.

The OpenTV Platform includes a Content Discovery facade module, the Content Discovery Gateway (CDG). Its purpose is to abstract the complexity of content discovery functionality from the client to provide a consistent API. For recommendations, this means abstracting the Recommendation Engine interface to provide the same API regardless of the engine used. To ease client integration, the API shares most of its syntax with the Metadata server. Also, the data model used in responses is the same as found in the Metadata Server. The key feature here, however, is that the order in which the items are returned is with the most recommended first.

Think Analytics integration​: As of version 2.7, the CDG is integrated with the ThinkAnalytics recommendation engine. Other recommendation engines could be added as required.

Data models

This section covers data models used in responses and in dynamic recommendation requests.

Data models used in responses

The data models used in responses are the same as found in the Metadata Server, as it is used to populate the metadata for each recommended item.

VOD E-T-P-V data model

BTV programme data model

Data models used in dynamic requests

The data models used in dynamic recommendation requests are JSON objects as detailed below:

RecommendationRequest data model

Filter data model

ExcludeRecommendationRequest data model

Use cases

Retrieving static recommendations

Static content-to-content recommendations should be used when the operator is defining the recommendations manually within the CMS, or when simple content-to-content recommendations are sufficient. If generated by a recommendation engine, they will be updated with every metadata import and pushed to the MDS (via the CMS).

Retrieving static VOD content-to-content recommendations

Static VOD recommendations are provided as a Vod Item id directly inside the VodItems themselves. Therefore, to create the recommendation list for an asset, query the editorial API again using the provided IDs.

In the request example shown below, you ask for editorial items in the node with the id "KIDS".

http://server:port/metadata/delivery/[provider]/vod/editorials?filter={"voditem.nodeRefs":"KIDS", "locale":"en_gb", "isVisible":true, "isValid":true, "isPurchasable":true, "voditems.deviceType":"STB", "editorial.region":"Wales"}&sort=[["voditem.DisplayPriority",1]]&fields=["editorial.Title", "editorial.Rating", "editorial.Description", "product.price", "voditem.RecommendedVodItemIds"]&offset=0&limit=10

This request gives you two editorials. Each one has two products with a vod item each.  The Vod item contains the recommended item ids, which each include a display priority.

For example:

Example VOD browse response with recommendations

If you consider the first movie, "WallaceGromit: The Curse of the Were-Rabbit", each product includes the same vod item. You can then use these ids to get the recommended content based on these ids. You must remove the display priority value before sending the request. Therefore, the list of the recommended content ids relating to this movie are, ["MS-0002-22_STARWARS2_VOD", "LYS000004814", "LYS000004822"], in that order.

You can then make a second request to the editorial API to retrieve the recommended content details:

http://server:port/metadata/delivery/[provider]/vod/editorials?filter={"voditem.id": {"$in": ["MS-0002-22_STARWARS2_VOD", "LYS000004814", "LYS000004822"]}, "locale":"en_gb", "isVisible":true, "isValid":true, "isPurchasable":true, "voditems.deviceType":"STB", "editorial.region":"Wales"}&sort=[["voditem.DisplayPriority",1]]&fields=["editorial.Title", "editorial.Rating", "editorial.Description", "product.price", "voditem.RecommendedVodItemIds"]&offset=0&limit=10

Retrieving static BTV content-to-content recommendations

Static BTV recommendations are provided as programme ids directly inside the programmes themselves.

In the request example below, you ask for programmes for the service with id, "MainClr37" for the 24 hours of November 29th, 2014.  For the purpose of this example, the limit is set to 1.

http://server:port/metadata/delivery/[provider]/btv/programmes?filter={"serviceRef": "MainClr37", "period.end": {"$gt":1417219200}, "period.start": {"$lt":1417305600}}&fields=["period", "RecommendedProgrammeIds", "title", "Rating", "eventId", "isCatchup"]&limit=1

In this example, you get ten recommended programme ids in the response.  As with the VOD editorial APIs, the order of recommendation is included as part of the string, which must be stripped out before using again.

Example BTV programmes API response with recommendations

Example BTV programme request to get recommended content details

Retrieving dynamic recommendations

Dynamic recommendations are recommendations derived in real-time by a recommendation engine based on content-to-content links, and the consumption of the content by the users. Most recommendation engines provide several different types of recommendations based on factors such as related content, specific user activity, and the use of content by all users.

Dynamic recommendations are requested from CDG by submitting a HTTP GET request to an appropriate URL using the appropriate parameters.

Refer to the CDG API reference, open the document corresponding to the Content Discovery API and go to the '/contentdiscovery/v1/recommendations' section.

CDG handles recommendation requests as follows:

1. Sends a request to the configured recommendation engine (for example, Think Analytics), which returns a list of content IDs for recommended content.
2. Queries MDS using these IDs to fetch the full metadata for the recommendations (a list of Programmes for BTV or a list of Editorials for VOD).
3. Returns the MDS data to the client that made the recommendation request.

The example below shows the format of all BTV recommendation request results:

Example BTV Recommendation result

The example below shows the format of all VOD recommendation request results:

Example VOD Recommendations result

Retrieving dynamic related content recommendations by account

To retrieve related content recommendations for an account the client must submit a recommendationRequest JSON parameter with recommendationType set to "related" and also specify a suitable contentId.

When querying at account level the account number is submitted as part of the URL.

In the example below, a user belonging to account "AC1234" is requesting related VOD recommendations for the account based on VOD item "LYS000006703":

GET http://server:port/contentdiscovery/v1/recommendations/account/AC1234?recommendationRequest={"dataType":"vod","recommendationType":"related","contentId":"LYS000006703","deviceType":"MediaPlayer"}

Retrieving dynamic related content recommendations by account and user

To retrieve related content recommendations for an account user the client must submit a recommendationRequest JSON parameter with recommendationType set to "related", and also specify a suitable contentId.

When querying at user level, both the account number and user ID are submitted as part of the URL.

In the example below, user "US2468" belonging to account "AC1234" is requesting related VOD recommendations for themselves based on VOD item "LYS000006703":

GET http://server:port/contentdiscovery/v1/recommendations/account/AC1234/user/US2468?recommendationRequest={"dataType":"vod","recommendationType":"related","contentId":"LYS000006703","deviceType":"MediaPlayer"}

Retrieving dynamic social recommendations by account

To retrieve social activity-based recommendations for an account, the client must submit a recommendationRequest JSON parameter with recommendationType set to "social" and also specify a suitable contentId.

When querying at account level the account number is submitted as part of the URL.

In the example below, a user belonging to account "AC1234" is requesting VOD social recommendations for the account based on VOD item "LYS000001468":

GET http://server:port/contentdiscovery/v1/recommendations/account/AC1234?recommendationRequest={"dataType":"vod","recommendationType":"related","contentId":"LYS000001468","deviceType":"MediaPlayer"}

Retrieving dynamic preference recommendations for BTV by account and user

Over time the recommendation engine will learn the users viewing preferences. To retrieve personal preference-based recommendations for a user the client must submit a recommendationRequest JSON parameter with recommendationType set to "preference" and omit the contentId.

When querying at user level both the account number and user ID are submitted as part of the URL.

In the example below, user "US2468" belonging to account "AC1234" is requesting BTV preference recommendations for themselves to view using a media player:

GET http://server:port/contentdiscovery/v1/recommendations/account/AC1234/user/US2468?recommendationRequest={"dataType":"btv","recommendationType":"preference","deviceType":"MediaPlayer"}

Retrieving dynamic context recommendations for VOD by account

To retrieve context-based recommendations for an account, the client must submit a recommendationRequest JSON parameter with recommendationType set to "context "; contentId is optional.

When querying at account level the account number is submitted as part of the URL.

In the example below, a user belonging to account "AC1234" is requesting VOD recommendations for the account based on the context defined by VOD item "LYS000001468":

GET http://server:port/contentdiscovery/v1/recommendations/account/AC1234?recommendationRequest={"dataType":"vod","recommendationType":"preference","deviceType":"MediaPlayer","contentId":"LYS000001468"}

In the example below, a user belonging to account "AC1234" is requesting VOD recommendations for the account based on the context defined by providing a Filter with a genre of "Action":

GET http://server:port/contentdiscovery/v1/recommendations/account/AC1234?recommendationRequest={"dataType":"vod","recommendationType":"preference","deviceType":"MediaPlayer"}&filter={"genre":["Action"]}

Excluding content from dynamic recommendations

Content can be excluded from future recommendations from CDG by submitting a HTTP POST to an appropriate URL using the parameters described below.

Refer to the CDG API reference, open the document corresponding to the Content Discovery API and go to the '/contentdiscovery/v1/excludedrecommendations' section.

Excluding a VOD content from future recommendations

To exclude a VOD content from future recommendations for an account, the client must POST an ExcludeRecommendationRequest JSON payload with the dataType, deviceType, and contentId set appropriately.

When requesting exclusion at account level, the account number is submitted as part of the URL.

In the example below, a user belonging to account "AC1234" is requesting that VOD content  "LYS000001468" is excluded from future recommendations:

POST http://server:port/contentdiscovery/v1/excludedrecommendations/account/AC1234
Content-Type: application/json
 
{"dataType":"vod","deviceType":"SetTopBox","contentId":"LYS000001468"}

Excluding a VOD node from future recommendations

To exclude a VOD node from future recommendations for a user, the client must POST an ExcludeRecommendationRequest JSON payload with the dataType, deviceType, and nodeId set appropriately.

When requesting exclusion at user level, the account number and user ID are submitted as part of the URL.

In the example below, user "US2468" belonging to account "AC1234" is requesting that VOD node "LYS000009876" is excluded from future recommendations:

POST http://server:port/contentdiscovery/v1/excludedrecommendations/account/AC1234/user/US2468
Content-Type: application/json
 
{"dataType":"vod","deviceType":"SetTopBox","nodeId":"LYS000009876"}

Excluding a BTV channel from future recommendations

To exclude a BTV channel from future recommendations for a user, the client must POST an ExcludeRecommendationRequest JSON payload with the dataType, deviceType, and channelId set appropriately.

When requesting exclusion at user level, the account number and user ID are submitted as part of the URL.

In the example below, user "US2468" belonging to account "AC1234" is requesting that BTV channel "LYS000088968" is excluded from future recommendations:

POST http://server:port/contentdiscovery/v1/excludedrecommendations/account/AC1234/user/US2468
Content-Type: application/json
 
{"dataType":"vod","deviceType":"SetTopBox","channelId":"LYS000088968"}

See also

The full CDG API documentation.