# Source: https://developers.google.com/youtube/v3/docs/playlistItems.md.txt

# 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 also uses a playlist to identify a channel's list of uploaded videos, with each
`playlistItem` in that list representing one uploaded video. You can retrieve the
playlist ID for that list from the [channel](https://developers.google.com/youtube/v3/docs/channels)
resource for a given channel. You can then use the
[playlistItems.list](https://developers.google.com/youtube/v3/docs/playlistItems/list) method to the
list.

## Methods

The API supports the following methods for `playlistItems` resources:

[list](https://developers.google.com/youtube/v3/docs/playlistItems/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](https://developers.google.com/youtube/v3/docs/playlistItems/list#usage).

[insert](https://developers.google.com/youtube/v3/docs/playlistItems/insert)
:   Adds a resource to a playlist.
    [Try it now](https://developers.google.com/youtube/v3/docs/playlistItems/insert#usage).

[update](https://developers.google.com/youtube/v3/docs/playlistItems/update)
:   Modifies a playlist item. For example, you could update the item's position in the playlist.
    [Try it now](https://developers.google.com/youtube/v3/docs/playlistItems/update#usage).

[delete](https://developers.google.com/youtube/v3/docs/playlistItems/delete)
:   Deletes a playlist item.
    [Try it now](https://developers.google.com/youtube/v3/docs/playlistItems/delete#usage).

## Resource representation

The following JSON structure shows the format of a `playlistItems` resource:  

```text
{
  "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,
    "videoOwnerChannelTitle": string,
    "videoOwnerChannelId": string,
    "playlistId": string,
    "position": unsigned integer,
    "resourceId": {
      "kind": string,
      "videoId": string,
    }
  },
  "contentDetails": {
    "videoId": string,
    "startAt": string,
    "endAt": string,
    "note": string,
    "videoPublishedAt": datetime
  },
  "status": {
    "privacyStatus": string
  }
}
```

### Properties

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

|                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              Properties                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               ||
|-----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `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](https://www.w3.org/TR/NOTE-datetime) 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. - `standard` -- An even higher resolution version of the thumbnail image than the `high` resolution image. This image is available for some videos and other resources that refer to videos, like playlist items or search results. This image is 640px wide and 480px tall. - `maxres` -- The highest resolution version of the thumbnail image. This image size is available for some videos and other resources that refer to videos, like playlist items or search results. This image is 1280px wide and 720px 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.`videoOwnerChannelTitle`  | `string` The channel title of the channel that uploaded this video.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| snippet.`videoOwnerChannelId`     | `string` The channel ID of the channel that uploaded this video.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| 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](https://developers.google.com/youtube/v3/docs/videos/list), set the `id` query parameter to this value in your API request.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| contentDetails.`startAt`          | `string` **Note:** This property has been deprecated and, if set, its value is ignored. 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` **Note:** This property has been deprecated and, if set, its value is ignored. 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. The property value has a maximum length of 280 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| contentDetails.`videoPublishedAt` | `datetime` The date and time that the video was published to YouTube. The value is specified in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |