Learn how to create and use 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 acceptablemetadata
body parameters that can be included in the call, such astitle
,description
, andauthor
. Although not required, we strongly recommend defining thetitle
of the playlist. All unnamed playlists are named Watch List upon creation. At a minimum, an emptymetadata
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"
}