Printable versionA playlist is a collection of videos that can be viewed sequentially and shared with other users. A playlist can contain up to 200 videos, and YouTube does not limit the number of playlists that each user creates. A user can view and edit his list of playlists on his account page. Playlists can be public or private. A playlist will be publicly visible to other users unless it has been explicitly been designated as a private playlist.
The YouTube Data API enables users to retrieve, create, modify and delete playlists.
This page contains the following sections:
This section explains how to retrieve a feed listing a specific user's playlists. Note that some users may not have created any playlists.
To request a feed of the currently logged-in user's playlists, send an HTTP GET request to the following URL. Note: For this request, you must provide an authentication token in the Authorization HTTP request header. The authentication token enables YouTube to identify the user.
http://gdata.youtube.com/feeds/api/users/default/playlists?v=2
To request a feed of another user's playlists, send an HTTP GET request to the following URL. Note that this request does not require authentication.
http://gdata.youtube.com/feeds/api/users/username/playlists?v=2
In the URL above, you must replace the text username with the user's YouTube username.
The following XML shows a sample API response containing a playlists feed. The response contains a series of <entry> tags, with each entry describing a playlist. Each entry contains the playlist's title, description, author and modification date as well as a <content> tag that specifies the URL for retrieving the list of videos in the playlist.
<?xml version='1.0' encoding='UTF-8'?> <feed xmlns='http://www.w3.org/2005/Atom' xmlns:openSearch='http://a9.com/-/spec/opensearch/1.1/' xmlns:media='http://search.yahoo.com/mrss/' xmlns:batch='http://schemas.google.com/gdata/batch' xmlns:yt='http://gdata.youtube.com/schemas/2007' xmlns:gd='http://schemas.google.com/g/2005' gd:etag='W/"Dk8DRn47eCp7ImA9WxRQGEk."'> <id>tag:youtube,2008:user:andyland74:playlists</id> <updated>2008-07-21T16:43:25.232Z</updated> <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#playlistLink'/> <title>Playlists of andyland74</title> <logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo> <link rel='related' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74?v=2'/> <link rel='alternate' type='text/html' href='http://www.youtube.com/profile_play_list?user=andyland74'/> <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/playlists?v=2'/> <link rel='http://schemas.google.com/g/2005#post' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/playlists?v=2'/> <link rel='http://schemas.google.com/g/2005#batch' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/playlists/batch?v=2'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/playlists?...'/> <link rel='service' type='application/atomsvc+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/playlists?alt=...'/> <author> <name>andyland74</name> <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri> </author> <generator version='2.0' uri='http://gdata.youtube.com/'>YouTube data API</generator> <openSearch:totalResults>3</openSearch:totalResults> <openSearch:startIndex>1</openSearch:startIndex> <openSearch:itemsPerPage>25</openSearch:itemsPerPage> <entry gd:etag='W/"Dk8DRn47eCp7ImA9WxRQGEk."'> <id>tag:youtube,2008:user:andyland74:playlist:8BCDD04DE8F771B2</id> <published>2007-11-04T17:30:27.000-08:00</published> <updated>2008-07-15T12:33:20.000-07:00</updated> <app:edited xmlns:app='http://www.w3.org/2007/app'>2008-07-15T12:33:20.000-07:00</app:edited> <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#playlistLink'/> <title>My New Playlist Title</title> <summary>My new playlist Description</summary> <content type='application/atom+xml;type=feed' src='http://gdata.youtube.com/feeds/api/playlists/8BCDD04DE8F771B2?v=2'/> <link rel='related' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74?v=2'/> <link rel='alternate' type='text/html' href='http://www.youtube.com/view_play_list?p=8BCDD04DE8F771B2'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/playlists/8BCDD04DE8F771B2?v=2'/> <link rel='edit' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/playlists/8BCDD04DE8F771B2?v=2'/> <author> <name>andyland74</name> <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri> </author> <yt:countHint>9</yt:countHint> </entry> <entry> ... </entry> ... </feed>
As noted in the previous section, each entry in a user's playlists feed contains a <content> tag that specifies the URL for retrieving the list of videos in the playlist. The following example shows the URL for retrieving a playlist as that URL appears in a playlists feed entry:
<content type='application/atom+xml' src='http://gdata.youtube.com/feeds/api/playlists/8BCDD04DE8F771B2?v=2'/>
The API response for a playlist feed is almost identical to a typical video feed or set of search results. However, a video entry in a playlist feed differs from a typical video entry in the following ways:
Each playlist entry contains the <yt:position> tag, which specifies the place that the video appears in the playlist order. The <yt:position> tag is a subtag of the <entry> tag.
If the user defined a custom title for the video, that title appears in the <atom:title> tag, and the video's original title appears in the <media:title> tag. Note that YouTube no longer enables users to set custom titles or descriptions for playlist entries.
If the playlist owner defined a custom description for the video, that description will appear in a <summary> tag. The <summary> tag is a subtag of the <entry> tag. The <media:description> tag contains the video's original description. Note that YouTube no longer enables users to set custom titles or descriptions for playlist entries.
To create a playlist, you must provide a title and description for the playlist. The <yt:private> tag, which is optional, indicates whether the playlist will be publicly visible. (By default, playlists are visible to other users.)
The following request provides the URL and shows the XML format for creating a new playlist:
POST /feeds/api/users/default/playlists HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token="AUTHORIZATION_TOKEN" GData-Version: 2 X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <title type="text">Sports Highlights Playlist</title> <summary>A selection of sports highlights</summary> </entry>
The following list identifies two common use cases for creating a playlist and describes the API calls associated with each use case:
A user watches a video and creates a new playlist that includes the video.
This use case begins with an API request to obtain information about a specific video.
After watching the video, the user clicks a link to add the video to a new playlist. Your application displays a form to allow the user to enter a title and description for the playlist.
Your application sends an HTTP POST request to http://gdata.youtube.com/feeds/api/users/default/playlists to create the playlist. The API request specifies the playlist title and description that the user entered.
Your application sends an additional API request to add the selected video to the playlist.
A user looks at a list of videos and selects one or more videos to add to a new playlist.
This use case begins with an API request to search for videos or to retrieve a particular video feed.
The user selects one or more videos from the list to add to a new playlist – for example, the user could check a box next to each video.
Your application displays a form to allow the user to enter a title and description for the playlist.
Your application sends an HTTP POST request to http://gdata.youtube.com/feeds/api/users/default/playlists to create the playlist using the title and description entered by the user.
Your application then loops through the selected videos and sends an additional API request to add each selected video to the playlist.
The API request for updating a playlist allows the user to update the title, description and public/private status of that playlist. The API defines additional requests for adding a video to a playlist, updating a video in a playlist or removing a video from a playlist.
The following sample request provides the URL and illustrates the XML format for modifying a playlist. Please note that the XML submitted in the request has the same format as a request to create a playlist. However, this request is an HTTP PUT request and the API URL must specify the ID of the playlist being updated.
PUT /feeds/api/users/USER_ID/playlists/PLAYLIST_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token="AUTHORIZATION_TOKEN" GData-Version: 2 X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <title type="text">Sports Highlights Playlist</title> <summary>A selection of sports highlights</summary> </entry>
The following use case describes a scenario where a user would modify a playlist:
This use case begins with a request to retrieve a feed of the user's playlists.
The user selects a playlist from the list and clicks a link to update the playlist.
Your application displays a form that lets the user update the title and description of the playlist.
Your application then sends an HTTP PUT request to the playlist's edit URL to update the playlist.
To add a video to a playlist, you will send an API request that identifies the unique ID that YouTube assigned to the playlist as well as the unique ID that YouTube assigned to the video. By default, the newly added video will be added to the end of a playlist. To insert a video into a different spot in the playlist, you must first add the video. Then you must update the playlist entry using the <yt:position> tag to adjust the order in which the video appears in the playlist.
The following request provides the URL and illustrates the XML format for adding a video to a playlist:
POST /feeds/api/playlists/PLAYLIST_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token="AUTHORIZATION_TOKEN" GData-Version: 2 X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <id>VIDEO_ID</id> </entry>
The following list identifies two common use cases for adding a video to a playlist and describes the API calls associated with each use case:
A user watches a video and adds the video to a playlist.
This use case begins with an API request to obtain information about a specific video.
After watching the video, the user clicks a link to add the video to a playlist.
Your application submits an API request to retrieve a list of the user's playlists and then displays the list.
The user selects an existing playlist and your application sends a POST request to the edit URL for that playlist to add the selected video to the playlist.
A user looks at a list of videos and selects one or more videos to add to a playlist.
This use case begins with an API request to search for videos or to retrieve a particular video feed.
The user selects one or more videos from the list to add to a playlist – for example, the user could check a box next to each video.
Your application submits an API request to retrieve a list of the user's playlists and then displays the list.
The user selects a playlist. Your application loops through the selected videos and sends a POST request to the edit URL for that playlist to add each selected video to the playlist. In each API request, the <id> tag specifies the <yt:videoid> for the video you are adding.
Note: Playlists contain a maximum of 200 videos. As such, you will not be able to add a video to a playlist that already contains that many videos.
A user can update the order in which a video appears in a playlist entry. The following sample request illustrates the XML format for modifying a playlist entry. Please note that the XML submitted in the request has the same format as a request to create a playlist entry. However, this request is an HTTP PUT request and the API URL, which specifies the ID of the playlist entry being updated, is different.
PUT /feeds/api/playlists/PLAYLIST_ID/PLAYLIST_ENTRY_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token="AUTHORIZATION_TOKEN" GData-Version: 2 X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <yt:position>2</yt:position> </entry>
The following use case describes a scenario where a user would modify a playlist entry:
This use case begins with a request to retrieve a specific playlist. Please note that when you retrieve a list of videos in a playlist, each <entry> tag encapsulates information about a single video in the playlist. To update a playlist entry, send an HTTP PUT request to the edit URL for that entry.
Your application displays the list of playlist entries and presents an option for the user to rearrange the order in which YouTube plays the videos in the playlist.
The user reorders the playlist entries and clicks a link to update the playlist.
Your application loops through the entries in the playlist to update the value of the <yt:position> tag for each entry. Your application will need to send one API request for each entry that it is updating. Each API request must be sent to the playlist entry's edit URL.
The following sample API request demonstrates how to delete a playlist entry. Please note that when you retrieve a list of videos in a playlist, each <entry> tag encapsulates information about a single video in the playlist. To delete a playlist entry, send an HTTP DELETE request to the edit URL for that entry.
DELETE /feeds/api/playlists/PLAYLIST_ID/PLAYLIST_ENTRY_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Authorization: AuthSub token="AUTHORIZATION_TOKEN" GData-Version: 2 X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY
The following list describes a common use case for deleting a playlist entry:
This use case begins with a request to retrieve a specific playlist.
Your application displays the list of the entries in the playlist with a checkbox next to each entry so that the user can check the entries that will be deleted.
Your application loops through the selected entries and sends an HTTP DELETE request for each entry that is being deleted from the playlist. Your application would send each API request to the edit URL for the playlist entry being deleted.
Deleting a playlist removes a playlist altogether. The following sample API request demonstrates how to delete a playlist:
DELETE /feeds/api/users/USER_ID/playlists/PLAYLIST_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Authorization: AuthSub token="AUTHORIZATION_TOKEN" GData-Version: 2 X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY
The following list describes a common use case for deleting a playlist:
This use case begins with a request to retrieve a feed of the user's playlists.
The user selects a playlist from the list to delete and you send an API request to delete the playlist.
|
