Ratings

Summary

The OpenTV Platform enables users to rate content. A content rating:

• Is stored by the platform so that the user's own rating can be shown in future.
• Can be used by the platform to derive an average rating of that content, which can also be shown to users.
• Can be used by an integrated recommendation engine to improve the user's recommendations.
• Can be reported to the service provider.

The platform is agnostic to the rating system. It supports any numerical value (for example, out of 5, 10, 100), but it is expected that clients of a service provider provide values that use the same rating system.

The Ratings API is present on the Content Discovery Gateway, the only exception being the average ratings API, which is accessed directly on the User Activity Vault.

Data models

Requests for ratings result in the following response entities:

{
    "contentId":"LYS987654",
    "accountId":"234521354",
    "userId":"usr12345",
    "rating":5
}

{
    "contentId":"LYS987654",
    "average":4.2,
    "count":231
}

To submit a rating the following data model is included as the payload:

{
    "dataType":"vod",
    "deviceType":"SetTopBox",
    "contentId":"TDLA0100000088341751",
    "rating":"3",
    "timestamp":"2017-07-17T12:20:02.000Z"
}

{
    "dataType":"btv",
    "deviceType":"SetTopBox",
    "entity" : "series",
    "contentId":"TDLA0100000088342567",
    "rating":"2",
    "timestamp":"2017-07-16T22:01:03.000Z"
}

Use cases

Rating data is submitted to and retrieved via the Content Discovery Gateway (CDG), however, the CDG is acting as a proxy to the User Activity Vault (UAV), which is where the rating data is persisted and managed.

Rate a VOD content for an account

In the example below, a user belonging to account "AC1234" is submitting a rating of "4" for VOD content "TDLA0100000088341751" .

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

POST http://server:port/contentdiscovery/v1/ratings/account/AC1234
Content-Type: application/json
 
{"dataType":"vod","deviceType":"MediaPlayer","contentId":"TDLA0100000088341751","rating":"4","timestamp":"2015-01-12T12:20:02.000Z"}

For more details, see /contentdiscovery/v1/ratings in the CDG Installation and User Guide. 

Rate a BTV content for an account and user

In the example below, user "USR1234" belonging to account "AC1234" is submitting a rating of "2" for BTV content "TDLA0100000088341751".

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

POST http://server:port/contentdiscovery/v1/ratings/account/AC1234/user/USR1234
Content-Type: application/json
 
{"dataType":"btv","deviceType":"SetTopBox","contentId":"TDLA0100000088341751","rating":"2","timestamp":"2015-01-12T14:20:02.000Z"}

For more details, see /contentdiscovery/v1/ratings in the CDG Installation and User Guide. 

Rate a series for an account and user

In the example below, user "USR1234" belonging to account "AC1234" is submitting a rating of "3" for a BTV series with ID "TDLA0100000088342451".

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

POST http://server:port/contentdiscovery/v1/ratings/account/AC1234/user/USR1234
Content-Type: application/json
 
{"dataType":"btv","deviceType":"SetTopBox", "entity": "series", "contentId":"TDLA0100000088342451","rating":"3","timestamp":"2017-07-17T19:22:01.000Z"}

For more details, see /contentdiscovery/v1/ratings in the CDG Installation and User Guide. 

Retrieve a VOD content rating for an account

In the example below, a user belonging to account "AC1234" is requesting their rating for VOD content "TDLA0100000088341751". The uniqueness of the contentId negates the need to specify a data type (for example, VOD or BTV).

When rating is at account level, the account number and contentid are submitted as part of the URL. 

GET http://server:port/contentdiscovery/v1/ratings/content/TDLA0100000088341751/account/AC1234

For more details, see /contentdiscovery/v1/ratings in the CDG Installation and User Guide. 

Retrieve a series content rating for an account and user

In the example below, a user belonging to account "AC1234" is requesting their rating for the series with the ID "TDLA0100000088342451". The uniqueness of the contentId negates the need to specify a data type (vod or btv) or entity type (content, series, or product).

When rating is at account level, the account number and contentid are submitted as part of the URL. 

GET http://server:port/contentdiscovery/v1/ratings/content/TDLA0100000088342451/account/AC1234/user/USR1234

For more details, see /contentdiscovery/v1/ratings in the CDG Installation and User Guide. 

Retrieve the average rating for a BTV content

In the example below, a user would like to find out the rating of content "Die Hard" with content id "DH1":

GET http://server:port/useractivityvault/v1/ratings/content/DH1/average

This will return a response containing both the average rating, and the number of ratings made against this content. For example:

{
  "contentId": "DH1",
  "average": 5.0,
  "count": 17
}

For more details, see  Api Doc - Ratings - Average in the UAV Installation and User Guide. 

Retrieve the average rating for a series

In the example below, a user would like to find out the rating of the series "Breaking Bad" with content ID "BB1":

GET http://server:port/useractivityvault/v1/ratings/content/BB1/average

You must include the SDP authentication token as part of the query string, in the form ?token=<token>.

This returns a response containing both the average rating and the number of ratings made against this content (count). It also includes the ID of the content (series) and the ID of the rating itself. For example:

{
  "id": "2127162",
  "contentId": "BB1",
  "average": 4.6,
  "count": 221
}

For more details, see  Api Doc - Ratings - Average in the UAV Installation and User Guide.