PlaylistItems

A playlistItem resource identifies another resource, such as a video, that is included in a playlist. In addition, the playlistItem resource contains details about the included resource that pertain specifically to how that resource is used in that playlist.

YouTube uses playlists to identify special collections of videos for a channel, such as:

  • uploaded videos
  • favorite videos
  • positively rated (liked) videos
  • watch history
  • watch later
To be more specific, these lists are associated with a channel, which is a collection of a person, group, or company's videos, playlists, and other YouTube information.

You can retrieve the playlist IDs for each of these lists from the channel resource for a given channel. You can then use the playlistItems.list method to retrieve any of those lists. You can also add or remove items from those lists by calling the playlistItems.insert and playlistItems.delete methods. For example, if a user marks a video as a favorite video, you would insert that video into the favorite videos playlist for that user's channel.

Methods

The API supports the following methods for playlistItems resources:

list
Returns a collection of playlist items that match the API request parameters. You can retrieve all of the playlist items in a specified playlist or retrieve one or more playlist items by their unique IDs. Try it now.
insert
Adds a resource to a playlist. Try it now.
update
Modifies a playlist item. For example, you could update the item's position in the playlist. Try it now.
delete
Deletes a playlist item. Try it now.

Resource representation

The JSON structure below shows the format of a playlistItems resource:

{
  "kind": "youtube#playlistItem",
  "etag": etag,
  "id": string,
  "snippet": {
    "publishedAt": datetime,
    "channelId": string,
    "title": string,
    "description": string,
    "thumbnails": {
      (key): {
        "url": string,
        "width": unsigned integer,
        "height": unsigned integer
      }
    },
    "channelTitle": string,
    "playlistId": string,
    "position": unsigned integer,
    "resourceId": {
      "kind": string,
      "videoId": string,
    }
  },
  "contentDetails": {
    "videoId": string,
    "startAt": string,
    "endAt": string,
    "note": string
  },
  "status": {
    "privacyStatus": string
  }
}

Properties

The following table defines the properties that appear in this resource:

Property name Value Description
kind string Identifies the API resource's type. The value will be youtube#playlistItem.
etag etag The Etag of this resource.
id string The ID that YouTube uses to uniquely identify the playlist item.
snippet object The snippet object contains basic details about the playlist item, such as its title and position in the playlist.
snippet.publishedAt datetime The date and time that the item was added to the playlist. The value is specified in ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) format.
snippet.channelId string The ID that YouTube uses to uniquely identify the user that added the item to the playlist.
snippet.title string The item's title.
snippet.description string The item's description.
snippet.thumbnails object A map of thumbnail images associated with the playlist item. For each object in the map, the key is the name of the thumbnail image, and the value is an object that contains other information about the thumbnail.
snippet.thumbnails.(key) object Valid key values are:
  • default – The default thumbnail image. The default thumbnail for a video – or a resource that refers to a video, such as a playlist item or search result – is 120px wide and 90px tall. The default thumbnail for a channel is 88px wide and 88px tall.
  • medium – A higher resolution version of the thumbnail image. For a video (or a resource that refers to a video), this image is 320px wide and 180px tall. For a channel, this image is 240px wide and 240px tall.
  • high – A high resolution version of the thumbnail image. For a video (or a resource that refers to a video), this image is 480px wide and 360px tall. For a channel, this image is 800px wide and 800px tall.
snippet.thumbnails.(key).url string The image's URL.
snippet.thumbnails.(key).width unsigned integer The image's width.
snippet.thumbnails.(key).height unsigned integer The image's height.
snippet.channelTitle string The channel title of the channel that the playlist item belongs to.
snippet.playlistId string The ID that YouTube uses to uniquely identify the playlist that the playlist item is in.
snippet.position unsigned integer The order in which the item appears in the playlist. The value uses a zero-based index, so the first item has a position of 0, the second item has a position of 1, and so forth.
snippet.resourceId object The id object contains information that can be used to uniquely identify the resource that is included in the playlist as the playlist item.
snippet.resourceId.kind string The kind, or type, of the referred resource.
snippet.resourceId.videoId string If the snippet.resourceId.kind property's value is youtube#video, then this property will be present and its value will contain the ID that YouTube uses to uniquely identify the video in the playlist.
contentDetails object The contentDetails object is included in the resource if the included item is a YouTube video. The object contains additional information about the video.
contentDetails.videoId string The ID that YouTube uses to uniquely identify a video. To retrieve the video resource, set the id query parameter to this value in your API request.
contentDetails.startAt string The time, measured in seconds from the start of the video, when the video should start playing. (The playlist owner can specify the times when the video should start and stop playing when the video is played in the context of the playlist.) The default value is 0.
contentDetails.endAt string The time, measured in seconds from the start of the video, when the video should stop playing. (The playlist owner can specify the times when the video should start and stop playing when the video is played in the context of the playlist.) By default, assume that the video.endTime is the end of the video.
contentDetails.note string A user-generated note for this item.
status object The status object contains information about the playlist item's privacy status.
status.privacyStatus string The playlist item's privacy status. The channel that uploaded the video that the playlist item represents can set this value using either the videos.insert or videos.update method.

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.