Get recommendations

Request

To get recommendations, send a POST request to:

http://<host>:<port>/contentdiscovery/v2/recommendations/account/{accountId}

Headers

• Content-Type: application/json
• Authorization – the token obtained from IAS at signon
• accept-language – the ISO country code (e.g., en_GB). Ncanto uses this to return context explanations in the the appropriate language. If there are no explanations available for the specified language, no explanations are returned. (See the example response below.)

Mandatory fields

• accountId (in URL) – the ID of the account
• A contexts object containing at least one context request object, each of which must contain at least the following:
  • context – the context for which to get recommendations
  • numOfRecommendations – the number of recommended items to return
  • deviceType – the device type for which the recommendations are required. This can be any device type defined in the Metadata Server (MDS).
  • contentId – the ID of the content to be used as the basis for the recommendations. (This is only mandatory for certain contexts (e.g., "content related to...").)

Optional fields

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

• age – limits recommendations to those suitable for someone of the specified age (based on content's parental rating).

Example

This example payload requests recommendations for three contexts, two of which include additional filters:

{
  "contexts": [
    {
      "context": "magazine-view",
      "numOfRecommendations": 3,
      "deviceType": "Android"
    },
    {
      "context": "because-you-like"
      ],
      "age": 18,
      "numOfRecommendations": 2,
      "deviceType": "Android",
      "contentId": "ApocalypseNow"
    },
    {
      "context": "kids-favourites",
      "age": 12,
      "numOfRecommendations": 10,
      "deviceType": "Android"
    }
  ]
}

Response

A successful request returns an HTTP 200 status.

A bad request returns an HTTP 400 status.

Example

This response is to a request that includes multiple contexts. There is one response for each context – the first contains no recommendations (as the context is not recognised), while each of the others contains multiple recommendations.

The response also includes:

• error – the error code, if any
• contextNames – all the localised display names of the context
• presentationProperties – the values of any custom presentation properties that have been defined for the context(s). This can contain any valid JSON.

The response can include both live and VOD recommendations.

{
  "contextResults": [
  {
    "context": "kids-favourites",
    "recommendations": [],
    "error": "Context name: 'kids-favourites' not recognised by Ncanto"
  },
  {
    "context": "magazine-view",
    "recommendations": [
    {
      "asset":
      {
        "assetId": "000000308451",
        "assetType": "BTV",
        "programId": "prog_1234"
      },
      "explanations": [
      {
        "type": "trending-msg",
        "message": "Hottest movies this week"
      },
      {
        "type": "promotion-msg",
        "message": "Special offers for Christmas"
      }
      ]
    },
    {
      "asset":
      {
        "assetId": "000000308452",
        "assetType": "VOD",
        "programId": "prog_246"
      },
      "explanations": [
      {
        "type": "genre-msg",
        "message": "Best of SciFi"
      }
      ]
    },
    {
      "asset": {
        "assetId": "000000308453",
        "assetType": "BTV",
        "programId": "prog_8910"
      },
      "explanations": [
      {
        "type": "kids-msg",
        "message": "Family fun!"
      },
      {
        "type": "promotion-msg",
        "message": "Special offers for Christmas"
      }
      ]
    }
    ],
    "contextNames":
    {
      "en_GB": "Magazine view"
    },
    "presentationProperties":
    {
      "prop1": "value1",
      "prop2":
      {
        "prop2a": "nestedValue1",
        "prop2b": "nestedValue2"
      }
    }
  },
  {
    "context": "because-you-like",
    "recommendations":
    [
    {
      "asset":
      {
        "assetId": "000000308451",
        "assetType": "VOD",
          "programId": "prog_abc"
      },
      "explanations":
      [
      {
        "type": "related-msg",
        "message": "Similar content"
      }
      ]
    },
    {
      "asset": {
      "assetId": "000000308466",
      "assetType": "VOD",
      "programId": "prog_xyz"
      },
      "explanations":
      [
      {
        "type": "related-msg",
        "message": "Similar content"
      }
      ]
    }
    ],
    "contextNames":
    {
      "en_GB": "Because you like"
    },
    "presentationProperties":
    {
      "prop1": "value1",
      "prop2":
      {
        "prop2a": "nestedValue1",
        "prop2b": "nestedValue2"
      }
    }
  }
  ]
}

See also

For full details of this API, see Content Discovery Gateway (CDG) API documentation.