YouTube API v2.0 – Playlists

Note: The YouTube Data API (v2) has been officially deprecated as of March 4, 2014. Please refer to our deprecation policy for more information.

A 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:

  1. Retrieving a user's playlists
  2. Retrieving a single playlist
  3. Adding a playlist
  4. Updating a playlist
  5. Adding a video to a playlist
  6. Editing video information in a playlist
  7. Removing a video from a playlist
  8. Deleting a playlist
  9. Retrieving and updating a user's 'Watch Later' playlist

Retrieving a user's playlists

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 a GET request to the following URL. Note: For this request, you must provide an authorization token, which enables YouTube to verify that the user authorized access to the resource.

    https://gdata.youtube.com/feeds/api/users/default/playlists?v=2

  • To request a feed of another user's playlists, send a GET request to the following URL. This request does not require user authorization.

    https://gdata.youtube.com/feeds/api/users/userId/playlists?v=2

    In the URL above, you should replace the text userId with the user's YouTube user ID. For backward compatibility purposes, the API also supports having the user's YouTube username specified instead.

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/&quot;Dk8DRn47eCp7ImA9WxRQGEk.&quot;'>
  <id>tag:youtube,2008:user:GoogleDevelopers: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 GoogleDevelopers</title>
  <logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo>
  <link rel='related' type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers?v=2'/>
  <link rel='alternate' type='text/html'
    href='https://www.youtube.com/profile_play_list?user=GoogleDevelopers'/>
  <link rel='http://schemas.google.com/g/2005#feed'
    type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/playlists?v=2'/>
  <link rel='http://schemas.google.com/g/2005#post'
    type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/playlists?v=2'/>
  <link rel='http://schemas.google.com/g/2005#batch'
    type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/playlists/batch?v=2'/>
  <link rel='self' type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/playlists?...'/>
  <link rel='service' type='application/atomsvc+xml'
    href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/playlists?alt=...'/>
  <author>
    <name>GoogleDevelopers</name>
    <uri>https://gdata.youtube.com/feeds/api/users/GoogleDevelopers</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/&quot;Dk8DRn47eCp7ImA9WxRQGEk.&quot;'>
    <id>tag:youtube,2008:user:GoogleDevelopers: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='https://gdata.youtube.com/feeds/api/playlists/8BCDD04DE8F771B2?v=2'/>
    <link rel='related' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers?v=2'/>
    <link rel='alternate' type='text/html'
      href='https://www.youtube.com/view_play_list?p=8BCDD04DE8F771B2'/>
    <link rel='self' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/playlists/8BCDD04DE8F771B2?v=2'/>
    <link rel='edit' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/playlists/8BCDD04DE8F771B2?v=2'/>
    <author>
      <name>GoogleDevelopers</name>
      <uri>https://gdata.youtube.com/feeds/api/users/GoogleDevelopers</uri>
    </author>
    <yt:countHint>9</yt:countHint>
  </entry>
  <entry>
    ...
  </entry>
  ...
</feed>

Retrieving a single playlist

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='https://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.

Adding a playlist

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: Bearer ACCESS_TOKEN
GData-Version: 2
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.

    1. This use case begins with an API request to obtain information about a specific video.

    2. 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.

    3. Your application sends a POST request to https://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.

    4. 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.

    1. This use case begins with an API request to search for videos or to retrieve a particular video feed.

    2. 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.

    3. Your application displays a form to allow the user to enter a title and description for the playlist.

    4. Your application sends a POST request to https://gdata.youtube.com/feeds/api/users/default/playlists to create the playlist using the title and description entered by the user.

    5. Your application then loops through the selected videos and sends an additional API request to add each selected video to the playlist.

Updating a 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 a PUT request and the API URL must specify the ID of the playlist being updated.

PUT /feeds/api/users/default/playlists/PLAYLIST_ID HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
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:

  1. This use case begins with a request to retrieve a feed of the user's playlists.

  2. The user selects a playlist from the list and clicks a link to update the playlist.

  3. Your application displays a form that lets the user update the title and description of the playlist.

  4. Your application then sends a PUT request to the playlist's edit URL to update the playlist.

Adding a video to a playlist

To add a video to a playlist, 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, include the <yt:position> tag in your request and set its value to the position where the video should appear in the playlist.

The following request provides the URL and illustrates the XML format for adding a video to the beginning of 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: Bearer ACCESS_TOKEN
GData-Version: 2
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>
  <yt:position>1</yt:position>
</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.

    1. This use case begins with an API request to obtain information about a specific video.

    2. After watching the video, the user clicks a link to add the video to a playlist.

    3. Your application submits an API request to retrieve a list of the user's playlists and then displays the list.

    4. 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.

    1. This use case begins with an API request to search for videos or to retrieve a particular video feed.

    2. 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.

    3. Your application submits an API request to retrieve a list of the user's playlists and then displays the list.

    4. 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.

Editing video information in a playlist

A user can update the order in which a video appears in a playlist that the user created. To update the position of a playlist entry, send an authenticated PUT request to the following URL, replacing PLAYLIST_ID and PLAYLIST_ENTRY_ID with the appropriate values:

https://gdata.youtube.com/feeds/api/playlists/PLAYLIST_ID/PLAYLIST_ENTRY_ID

The following sample request illustrates the XML format for modifying a playlist entry.

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: Bearer ACCESS_TOKEN
GData-Version: 2
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:

  1. 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 a PUT request to the edit URL for that entry.

  2. 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.

  3. The user reorders the playlist entries and clicks a link to update the playlist.

  4. 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.

Removing a video from a playlist

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 a 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: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY

The following list describes a common use case for deleting a playlist entry:

  1. This use case begins with a request to retrieve a specific playlist.

  2. 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.

  3. Your application loops through the selected entries and sends a 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

Deleting a playlist removes a playlist altogether. The following sample API request demonstrates how to delete a playlist:

DELETE /feeds/api/users/default/playlists/PLAYLIST_ID HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY

The following list describes a common use case for deleting a playlist:

  1. This use case begins with a request to retrieve a feed of the user's playlists.

  2. The user selects a playlist from the list to delete and you send an API request to delete the playlist.

Retrieving and updating a user's 'Watch Later' playlist

YouTube's 'Watch Later' feature lets users save videos to watch at a later time. The 'Watch Later' list is stored as a playlist. However, that list is not included in a user's playlist feed.

You will be able to retrieve a user's watch_later playlist if either of the following conditions is true:

  • You are submitting an authenticated request to retrieve the logged-in user's watch_later playlist. For this request, send a GET request to the following URL.

    https://gdata.youtube.com/feeds/api/users/default/watch_later?v=2

  • The watch_later playlist that you are retrieving is publicly available. In this case, send a GET request to the following URL. You need to replace the string userId with the user's YouTube user ID or YouTube username.

    https://gdata.youtube.com/feeds/api/users/userId/watch_later?v=2

Note: The watch_later playlist is only accessible through API version 2 or greater.

By default, the watch_later playlist is an empty, private playlist. To determine whether a user's watch_later playlist is accessible or if it has entries, retrieve the user's profile and check for the presence of a <gd:feedLink> tag with a rel attribute value of http://gdata.youtube.com/schemas/2007#user.watchlater.

If the tag is present, then you can access the user's watch_later playlist via the API using the same authentication credentials as you used to retrieve the user's playlist. The tag's href attribute will specify the feed URL for the user's watch_later playlist, and its countHint attribute specifies the number of videos in that list. A sample tag is shown below:

<gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.watchlater'
    href='https://gdata.youtube.com/feeds/api/users/userId/watch_later?v=2'
    countHint='17'/>

Again, the link will only be present in a profile entry if either of the following conditions is true:

  • You submit an authenticated request to retrieve the logged-in user's own profile.

  • The watch_later playlist is publicly available for the user whose profile you are retrieving.

The API server will return a 40x HTTP response code if you try to retrieve a watch_later playlist and neither of the above conditions is true.

The API supports the same operations for adding, updating, and deleting videos in the watch_later playlist as for any other playlist, and the list below shows the API URLs to use for those operations. These requests are only supported for authenticated users who are updating their own watch_later playlist.

  • Adding a video to the playlist:
    https://gdata.youtube.com/feeds/api/users/default/watch_later.

  • Updating the position of a playlist entry:
    https://gdata.youtube.com/feeds/api/users/default/watch_later/<VIDEO_ID>.

  • Deleting a video from the playlist:
    https://gdata.youtube.com/feeds/api/users/default/watch_later/<VIDEO_ID>.

pagination links

« Previous
Favorite Videos 		Next »
Subscriptions

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.