Get recommendations (Recommendations Façade with XroadMedia NCanto)

Request

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

/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.

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

{
  "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.  

{
  "similarityEngines": [
    {
      "name": "related-vod",
      "contribution": 4,
      "seed": "seed"
    }
  ]
}

{
  "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:

   {
      "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

{
  "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": [
    {
      "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
    }
  ]
}

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.