Get recommendations (Recommendations Façade with XroadMedia NCanto)

Request

To get recommendations based on the provided input send a POST request to:

CODE

/recommendations/v1/recommendations

Headers

Content-Type: application/json
Authorization – the token obtained from IAS at signon

Mandatory fields

A recommentationRequests object containing at least one recommendation type request object, each of which must contain at least the following:
- recommendationType – the type of recommendation that is to be invoked. This value must be one of those returned from the recommendation types API.
- numOfRecommendationsPerRow – the number of results to be returned on each row.
- language - allows the client to specify a preference for a particular language where appropriate.
- deviceTypes – the device type for which the recommendations are required. This can be any device type defined in the Metadata Server (MDS).

Optional fields

Each of the above-mentioned recommendation type request objects can also contain:

basedOnSeeds – the seeds will be used to create a filter that consists of appropriate criteria processed as a logical AND.

Example Input Example Output

Example filter

JS

{ 
  "basedOnSeeds": [ 
    { 
      "seedType": "ACTOR", 
      "seedValue": "Steve Buscemi" 
    },
    {
      "seedType": "GENRE",
      "seedValue": "Classic Movies" 
    } 
  ] 
}

Example filter

JS

{
  "filter": {
    "operator": "and",
    "criteria": [
      {
        "term": "persons.actors.canonical",
        "operator": "equals",
        "value": "Steve Buscemi"
      },
      {
        "term": "genreBroad",
        "operator": "contains",
        "value": "Classic Movies"
      }
    ]
  }
}

basedOnContent - Ncanto only supports a single content seed, so the first is taken from the array.
The Ncanto query parameter seed is populated with in accordance with the value of the content.contentType :
- VOD → contentItem.vodTechnicalId
- BTV → contentItem.btvProgrammeId
- SERIES → contentItem.seriesId
- SEASON → contentItem.seasonId
- DEEPLINK → contentItem.deeplinkId

This seed parameter is then referenced in the stored context as a parameter for the Ncanto similarity engine. For example, for recommendaions based upon a VOD content item, the URL invoked might look something like http://ncanto/recommendations?seed=vod_technical_10 Note that should a client invoke a context that requires a seed but doesn’t provide a basedOnContent, then this will result in an error.

Query parameter referenced in context definition	Submitted value substition
Example content seed JS `{ "similarityEngines": [ { "name": "related-vod", "contribution": 4, "seed": "seed" } ] }`	Example content seed JS `{ "similarityEngines": [ { "name": "related-vod", "contribution": 4, "seed": "vod_technical_10" } ] }`

maxAgeRating - Restricts results to content suitable for the age.

Geo-filtering/blocking

If appropriate, based on the configuration in ias-business-configmap and the geo blocking properties found in the sign-on token, additional filters are submitted in the ad-hoc context to perform restriction of recommendations based on geo location.

If ias-business-configmap has disabled geo filtering or the sign-on token shows that the user is geoBlockExempt then no additional geo filters are included in the ad-hoc context

Otherwise

the appropriate geo filter is included in the ad-hoc context
a variable named currentRegion is declared in the ad-hoc context
the users current location is added as query parameter region

Whitelist/blacklist filter added to ad-hoc context, plus currentRegion variable:

Example geo filter

JS

   {
      "rules": [
        {
          "then": {
            "global": {
              "filter": {
                "operator": "and",
                "criteria": [
                  {
                    "operator": "and",
                    "criteria": [
                      {
                        "operator": "or",
                        "criteria": [
                          {
                            "term": "clientCustomProperties.geoFilteringBillAddrCountryWhiteList",
                            "operator": "notExists"
                          },
                          {
                            "term": "clientCustomProperties.geoFilteringBillAddrCountryWhiteList",
                            "value": "default",
                            "variable": "currentRegion"
                          }
                        ]
                      },
                      {
                        "operator": "or",
                        "criteria": [
                          {
                            "term": "clientCustomProperties.geoFilteringBillAddrCountryBlackList",
                            "operator": "notExists"
                          },
                          {
                            "term": "clientCustomProperties.geoFilteringBillAddrCountryBlackList",
                            "operator": "notEquals",
                            "value": "default",
                            "variable": "currentRegion"
                          }
                        ]
                      }
                    ]
                  }
                ]
              }
            }
          }
        }
      ],
      "variables": {
        "currentRegion": {
          "type": "queryParameter",
          "parameterName": "region"
        }
      }
    }

Example Response mapping

Example Ncanto Response Corresponding Recommendations Facade Response Notes

Example Ncanto Response

JS

{
  "recommendations": [
    {
      "asset": {
        "assetType": "BTV",
        "assetId": "btvAsset1",
        "seriesId": "btvSeries1",
        "programId": "latest-movies-prog-1"
      }
    },
    {
      "asset": {
        "assetType": "VOD",
        "assetId": "vodAsset",
        "seriesId": "vodSeries",
        "programId": "latest-movies-prog-2"
      }
    },
    {
      "asset": {
        "assetType": "BTV",
        "assetId": "btvAsset2",
        "seriesId": "btvSeries2",
        "programId": "latest-movies-prog-3"
      }
    },
    {
      "asset": {
        "assetType": "DEEPLINK",
        "assetId": "netflix_1",
        "seriesId": "series2",
        "programId": "prog_2_1"
      }
    }
  ]
}

Recommendations Facade Response

JS

{
  "recommendations": [
    {
      "recommendationType": "latest-movies",
      "recommendationRows": [
        {
          "rowTitle": "latest-movies",
          "content": [
            {
              "contentType": "BTV",
              "btvProgrammeId": "btvAsset1",
              "vodTechnicalId": null,
              "editorialId": "latest-movies-prog-1",
              "deeplinkId": null,
              "seriesId": "btvSeries1",
              "seasonId": null
            },
            {
              "contentType": "VOD",
              "vodTechnicalId": "vodAsset",
              "btvProgrammeId": null,
              "editorialId": "latest-movies-prog-2",
              "deeplinkId": null,
              "seriesId": "vodSeries",
              "seasonId": null
            },
            {
              "contentType": "BTV",
              "btvProgrammeId": "btvAsset2",
              "vodTechnicalId": null,
              "editorialId": "latest-movies-prog-3",
              "deeplinkId": null,
              "seriesId": "btvSeries2",
              "seasonId": null
            },
            {
              "contentType": "DEEPLINK",
              "btvProgrammeId": null,
              "vodTechnicalId": null,
              "editorialId": "prog_2_1",
              "deeplinkId": "netflix_1",
              "seriesId": "series2",
              "seasonId": null
            }
          ]
        }
      ],
      "error": null
    }
  ]
}

recommendationType property of the response is derived from the request
rowTitle property is populated using the recommendation type (context name)

Response

A successful request returns an HTTP 200 status.

A bad request returns an HTTP 400 status.

An unauthorised request returns an HTTP 500 status.