Recommendations Façade - Generic

Generic API

The Recommendations Façade attempts to provide a generic API that can provide uniform access to a variety of recommendation engines. The generic nature obviously means that functionality is restricted to what can be thought of as the core operations of a recommendation engine, therefore the more specialised functionality of the various operators cannot be catered for.

The full Open API spec can be viewed here: Recommendations Facade Open API Spec.

For details of how the generic API is implemented in a specific adapter, please see the relevant documentation. Currently support is provided for Xroad Media NCanto.

GET /recommendations/operator/v1/recommendationtypes

This API allows operators access to the types of recommendation that are supported by the recommendation engine that is in use.

It is a simple GET and the API is only exposed at the operator level, thus no user token is expected.

Schema

The response is a list of the recommendation types available.

Example recommendation types response

JS

{
  "recommendationTypes": [
    "latest-movies",
    "trending-series",
    "kids-favourites"
  ]
}

Response status

HTTP Status	Description
200	Operation successful
4xx	Client error e.g. bad request, unauthorized access etc
5xx	Server error

POST /recommendations/v1/recommendations

This API allows clients to request recommendations based on the criteria that is supplied in the payload. As it is client accessible it requires a valid sign-on token, from which the users account will be established.

Schema

The body of the POST is a JSON object as follows:

RecommendationRequest

Property Type Mandatory Description

recommendationRequests

Array of RecommendationTypeRequest

Yes

An array where each entry is a request for a certain type of recommendation.

Each entry can be specified in isolation to the others and no cross validation will be performed.

RecommendationTypeRequest:

Property	Type	Mandatory	Description
`recommendationType`	String	Yes	The type of recommendation that is to be invoked. This value must be one of those returned from the recommendation types API.
`numOfRecommendationsPerRow`	int	Yes	The number of results to be returned on each row. Depending on the recommendation engine in use and the type of recommendation requested, the response may contain less results than requested or even none. This is beyond the control of Recommendations Facade.
`maxNumOfRows`	int	No	If the recommendation engine returns multiple rows for this recommendation type, then the number of rows will not exceed this value. Defaults to 1
`basedOnSeeds`	Array of BasedOnSeed	No	This allows the client to specify additional filtering to be applied to the recommendations e.g. ACTOR="Al Pacino" Multiple entries can be specified for the same seed type e.g. ACTOR="Al Pacino", ACTOR="Robert DeNiro". How this is interpreted is controlled by the recommendation engine in use and so the documentation for that particular adapter should be consulted. As a general rule, multiple seeds will be applied as a logical AND, so specifying 2 actors would only return films that starred both those actors.
`basedOnContent`	Array of ContentItem	No	This allows the client to specify a piece of content that recommendations should be based on, e.g. content related to "Star Wars" It should be noted that this type of filtering is not always relevant and may require that a particular type of recommendation is invoked to take effect, this is of course dependent on the recommendation engine in use. Also, some recommendation engines will only support a single content item and so will simply take the first in the list and ignore the others.
`language`	String A valid language code e.g. en_gb	Yes	Allows the client to specify a preference for a particular language where appropriate. Whether this has any effect is dependent on the recommendation engine in use.
`maxAgeRating`	int	No	Allows the client to specify a maximum age rating for any recommendations made. Whether this has any effect is dependent on the recommendation engine in use.
`deviceTypes`	Array of String	Yes	The type of devices that the recommended content must be suitable for playback on. Some recommendation engines will only support specifying a single device type and so will simply take the first in the list and ignore the others.
`metadata`	JSON Object	No	This property allows for any additional engine specific data to be submitted. The configured adapter will process it accordingly.

BasedOnSeed:

Property Type Mandatory Description

seedType

String

One of:

ACTOR
DIRECTOR
CATEGORY
GENRE
SUBGENRE

Yes

The type of seed being specified

seedvalue String Yes The value of the seed.

ContentItem:

Property	Type	Mandatory*	Description
`contentType`	String One of: VOD BTV SERIES SEASON DEEPLINK	Yes	The type of the content. Note, that not all recommendation engines will support all types of content, so the documentation for the particular adapter should be consulted.
`vodTechnicalId`	String	No	If the contentType is VOD then this will contain the id of its technical.
`btvProgramId`	String	No	If the contentType is BTV then this will contain the id of its program.
`deeplinkId`	String	No	If the contentType is DEEPLINK then this will be the id of the MDS deeplink entity
`deeplinkType`	String One of: VOD BTV SERIES SEASON	No	If the contentType is DEEPLINK then this will indicate the content type of the links parent entity. The consuming client will use this to identify which MDS API the editorialId relates to in order to retrieve the entity and associated link details.
`editorialId`	String	No	The id of the editorial of the content. VOD = editorial.id BTV = programme.contentRef
`seriesId`	String	No	If applicable the id of the series.
`seasonId`	String	No	If applicable the id of the season.

Enforcement of required ID's will be down to the configured adapter to enforce.

RecommendationResponse

Property	Type	Mandatory*	Description
`recommendations`	Array of RecommendationTypeResponse	Yes	A JSON array containing the results for each requested recommendation type

RecommendationTypeResponse

Property Type Mandatory* Description

recommendationType

String

Yes

The recommendation type that resulted in these recommendations

recommendationRows

Array of RecommendationRow

No

An array with an entry per row of recommendations.

The array may be empty if the request resulted in no recommendations from the configured engine or an error occurred.

error

String

No

Details of any error that occurred for the request for this particular recommendation type.

If all recommendation types result in an error then the response will be a suitable HTTP error code, but if at least one recommendation type is a success then its results will be returned and any erroneous recommendation types will provide details of the error they encountered.

RecommendationRow

Property Type Mandatory* Description

rowTitle

String

No

If the recommendation engine provides a title then it will appear here, may otherwise be set using the recommendation type or another value depending on the adapters implementation.

recommendations

Array of ContentItem

No

The recommended content.

The array may be empty if the request resulted in no recommendations from the configured engine or an error occurred.

Example request

Body of request for 2 recommendation types - the second of which should produce an error as it is for an unsupported recommendation type.

Example recommendation request

JS

{
  "recommendationRequests": [
    {
      "recommendationType": "latest-movies",
      "basedOnContent": [
        {
          "contentType": "VOD",
          "vodTechnicalId": "tech-1",
          "editorialId": "editorial-1",
          "seasonId": "season-2",
          "seriesId": "series-3"
        }
      ],
      "basedOnSeeds": [
        {
          "seedType": "ACTOR",
          "seedValue": "Steve Buscemi"
        },
        {
          "seedType": "CATEGORY",
          "seedValue": "Classic Movies"
        },
        {
          "seedType": "GENRE",
          "seedValue": "Comedy"
        },
        {
          "seedType": "SUBGENRE",
          "seedValue": "Independent"
        },
        {
          "seedType": "DIRECTOR",
          "seedValue": "Coen Brothers"
        }
      ],
      "maxRatingAge": 15,
      "language": "en_GB",
      "deviceTypes": [
        "Android"
      ],
      "numOfRecommendations": 3,
      "maxNumOfRows": 1,
      "metadata": {
        "engineSpecificProperty": "someValue"
      }
    },
    {
      "recommendationType": "unknown-reco-type",
      "deviceTypes": [
        "Android"
      ],
      "numOfRecommendations": 3,
      "language": "en_GB"
    }
  ]
}

Example response

Body of response for two recommendation types - the first is successful but the second of has produce an error as it is for an unsupported recommendation type.

Example recommendation response

JS

{
  "recommendations": [
    {
      "recommendationType": "latest-movies",
      "recommendationRows": [
        {
          "rowTitle": "latest-movies",
          "content": [
            {
              "contentType": "BTV",
              "btvProgrammeId": "btvAsset1",
              "vodTechnicalId": null,
              "editorialId": "latest-movies-prog-1",
              "seriesId": "btvSeries1",
              "seasonId": null
            },
            {
              "contentType": "VOD",
              "vodTechnicalId": "vodAsset",
              "btvProgrammeId": null,
              "editorialId": "latest-movies-prog-2",
              "seriesId": "vodSeries",
              "seasonId": null
            },
            {
              "contentType": "BTV",
              "btvProgrammeId": "btvAsset2",
              "vodTechnicalId": null,
              "editorialId": "latest-movies-prog-3",
              "seriesId": "btvSeries2",
              "seasonId": null
            }
          ]
        }
      ],
      "error": null
    },
    {
      "recommendationType": "unknown-reco-type",
      "error": "Recommendation Type unknown-reco-type not recognised"
    }
  ]
}

Response status

HTTP Status	Description
200	Operation successful
4xx	Client error e.g. bad request, unauthorized access etc
5xx	Server error

POST /recommendations/v1/useractivity

This API allows clients to submit their activity related to a piece of content, thus allowing the recommendation engine to learn their preferences and make more appropriate recommendations.

Prioir to release 21.38, clients were required to report activity and metrics separately to both Recommendation Façade and to User Activity Vault (UAV). (The latter is required for reporting purposes.)

Since release 21.38, clients only need to report activity and metrics to UAV – they will be passed on to Recommendation Façade automatically without the client having to report them separately.

That means that the client no longer needs to make the request described below.

Schema

The body of the POST is a JSON object as follows:

UserActivityRequest:

Property Type Mandatory Description

activityType

String

Yes

The type of activity that is being reported.

content

ContentItem

See ContentItem

Yes

The content that is subject to the activity.

The configured adapter will enforce validation on the type(s) of ID that are required.

deviceType

String

Yes

The type of device the activity took place on.

Example request

Example user activity request

JS

{
  "activityType": "PLAY",
  "deviceType": "Android",
  "content": {
    "contentType": "BTV",
    "btvProgrammeId": "btv123",
    "editorialId": "editorial21",
    "seriesId": "ser_99",
    "seasonId": "ser_99_season_2"
  }
}

Response status

HTTP Status	Description
204	Operation successful
4xx	Client error e.g. bad request, unauthorized access etc
5xx	Server error