Creating and using a Watchlist playlist

A Watchlist playlist creates a list of videos instantly, typically based on the choices and viewing behavior of a user. An OTT App uses watchlist playlists to display the videos that a user has added to a Favorites list and the videos that a user has not completed watching.

Requirements

Account-level OTT Apps entitlement (contact your JW Player representative for more information)
Site ID
API secret

Create a Watchlist playlist

📘

Watchlist playlists can only be created through the Platform Management API.

Once created, a Watchlist playlist appears as an empty, uneditable playlist in your JW Player dashboard.

Watchlist playlists can be deleted through the Platform Management API or your JW Player dashboard.

Use the following steps to create a Watchlist playlist:

Retrieve the site ID for a property and the API secret.
Make an authenticated POST /v2/sites/{site_id}/playlists/watchlist_playlist call to create a new Watchlist playlist. Be sure to replace {site_id} with the site ID and include the API secret within the header of the API call.

Refer to the POST /v2/sites/{site_id}/playlists/watchlist_playlist reference for more information about acceptable metadata body parameters that can be included in the call, such as title, description, and author. Although not required, we strongly recommend defining the title of the playlist. All unnamed playlists are named Watch List upon creation. At a minimum, an empty metadata object must be included in the JSON body of the API request.

curl -L -X POST 'https://api.jwplayer.com/v2/sites/{site_id}/playlists/watchlist_playlist/' \
     -H 'Authorization: Bearer {api_v2_key}' \
     -H 'Content-Type: application/json' \
     -d '{"metadata": {}}'

import requests
import json

url = "https://api.jwplayer.com/v2/sites/{site_id}/playlists/watchlist_playlist"

payload = json.dumps({
  "metadata": {}
})
headers = {
  'Authorization': 'Bearer {api_v2_key}',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

The API returns a 201 response with the watchlist playlist information.

{
    "created": "2022-02-23T05:02:48+00:00",
    "id": "abcd1234",
    "last_modified": "2022-02-23T05:02:48+00:00",
    "metadata": {
        "author": null,
        "custom_params": {},
        "description": null,
        "link": null,
        "title": "Watch List"
    },
    "playlist_type": "watchlist",
    "relationships": {},
    "schema": null,
    "type": "playlist"
}

Request media with a Watchlist playlist

Use the following steps to request media:

Make an authenticated GET https://api.jwplayer.com/v2/sites/{site_id}/playlists/?q=playlist_type:watchlist. The API returns a list of all Watchlist playlists associated with the site ID.
Search the results for the playlists[].id of the Watchlist playlist.
Gather the media IDs for the media to be requested. The media IDs must be captured from the Favorite choices or watching behavior of the user.
Make an unauthenticated GET https://cdn.jwplayer.com/apps/watchlists/{watchlist_id}?media_ids={comma_separated_media_ids} to retrieve the media metadata.

curl -L -X GET 'https://cdn.jwplayer.com/apps/watchlists/{watchlist_id}/?media_ids=abcd1234,abcd1235' \

import requests

url = "https://cdn.jwplayer.com/apps/watchlists/{watchlist_id}/?media_ids=abcd1234,abcd1235"

payload = ""
headers = {}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

The API returns a 200 response with the media metadata. With this information, the media can be displayed in a list to the user, such as a Favorites shelf and Continue Watching shelf.

{
    "description": "",
    "feedid": "{watchlist_id}",
    "feed_instance_id": "{feed_instance_id}",
    "kind": "WATCHLIST",
    "playlist": [
        {
            "description": "The majestic beauty of the Dutch windmill.",
            "duration": 21,
            "image": "https://cdn.jwplayer.com/v2/media/abcd1234/poster.jpg?width=720",
            "images": [
                {
                    "src": "https://cdn.jwplayer.com/v2/media/abcd1234/poster.jpg?width=320",
                    "type": "image/jpeg",
                    "width": 320
                },
                . . .
                {
                    "src": "https://cdn.jwplayer.com/v2/media/abcd1234/poster.jpg?width=1920",
                    "type": "image/jpeg",
                    "width": 1920
                }
            ],
            "link": "https://cdn.jwplayer.com/previews/abcd1234",
            "mediaid": "abcd1234",
            "pubdate": 1641214320,
            "tags": "history, culture",
            "title": "Dutch Windmill",
            "requiresSubscription": "true"
        },
        {
            "description": "Windmill in Pennsylvania, USA",
            "duration": 35,
            "image": "https://cdn.jwplayer.com/v2/media/abcd1235/poster.jpg?width=720",
            "images": [
                {
                    "src": "https://cdn.jwplayer.com/v2/media/abcd1235/poster.jpg?width=320",
                    "type": "image/jpeg",
                    "width": 320
                },
                . . .
                {
                    "src": "https://cdn.jwplayer.com/v2/media/abcd1235/poster.jpg?width=1920",
                    "type": "image/jpeg",
                    "width": 1920
                }
            ],
            "link": "https://cdn.jwplayer.com/previews/abcd1235",
            "mediaid": "abcd12354",
            "pubdate": 164121740,
            "tags": "history, culture",
            "title": "American Windmill",
            "requiresSubscription": "true"
        }
    ],
    "title": "Watch List"
}