Skip to main content

Recommendation

This guide will present the basic steps to obtain media asset recommendations on the Streamdiver API.

What is a Recommender?​

A recommender is a system or algorithm designed to suggest relevant content, like videos, to users based on their preferences. It tries to predict which unseen content users might find interesting or valuable. Recommenders help users to discover new content more efficiently using personalized suggestions to improve the overall user experience.

Recommendation for Media Assets and Sections​

Streamdiver recommendations can be retrieved using one or more media assets and/or media sections as input. The endpoint will use the content metadata of the specified media input to compute related recommendations.

Recommendations can be retrieved by specifying one or more media asset ids and media section ids as input, like:

curl '{{baseUrl}}/recommendation?mediaids=8f8e0e9f-2ce8-4efd-8b07-9fc85db331e9&mediaids=8f8e0e9f-2ce8-4efd-8b07-9fc85db331e9&sectionids=1a6ea046-6493-473e-914b-8894b6036076' \
--header 'Authorization: Bearer eyJh...20yA' \

Query Parameters​

  • page Page of retrieved recommendations
  • perpage Number of retrieved recommendations per page
  • mediaids IDs of media assets to be considered as input for retrieval of recommendations
  • sectionids IDs of media sections to be considered as input for retrieval of recommendations

Recommendation for Current User​

As an alternative to specifying media assets and sections explicitly as input, personalized user recommendations can be retrieved. The endpoint will use the content metadata of assets viewed in the past to compute relevant recommendations.

NOTE: This endpoint is only working for registered and authenticated users.

curl '{{baseUrl}}/recommendation/user/current' \
--header 'Authorization: Bearer eyJh...20yA' \

Query Parameters​

  • page Page of retrieved recommendations
  • perpage Number of retrieved recommendations per page

Recommendation Response​

The structure of the recommendation response is identical for both endpoints and contains information of recommended media assets and their metadata. For audio and video assets, relevant sections are identified and grouped by their parent asset to provide recommendations in a structured manner.

NOTE: The API will only recommend media assets the current user is permitted to access.

The response returns a list of related media assets and sections:

{
  "data": {
    "mediaAssets": [
      {
        "id": "09a40e8f-f561-4274-9337-9f148ec8ef22",
        "audit": {...},
        "name": "Lorem ipsum",
        "description": "Lorem ipsum dolor sit.",
        "type": "video",
        "thumbnail": {
          "height": 640,
          "width": 480,
          "url": "https://api.streamdiver.com/v2/thumbnails..."
        },
        "preview": {
          "url": "https://cdn.streamdiver.com/vod-..."
        },
        "tags": [...],
        "filesize": 123456789,
        "bitrate": 8388608,
        "duration": 300,
        "usage": {
          "views": 100,
          "downloads": 3
        },
        "videoHeight": 640,
        "videoWidth": 480,
        "sections": [
          {
            "sectionId": "09a40e8f-f561-4274-9337-9f148ec8ef22",
            "start": 50.123,
            "duration": 100.957,
            "preview": {
              "url": "https://cdn.streamdiver.com/vod-..."
            },
            "thumbnail": {
              "height": 640,
              "width": 480,
              "url": "https://api.streamdiver.com/v2/thumbnails?..."
            },
            "transcript": [...]
          },
          ...
        ],
        "permissions": [
          "viewChannel"
        ]
      }
    ]
  },
  "status": "success"
}