Add a playlistItems Resource

Learn about the playlistItems resource and how it is used to identify a resource included in a playlist.

We'll cover the following

The playlistItems resource is mainly used to manage the content of the playlists that users create. The playlist resource, on the other hand, only manages the playlist itself. It doesn’t allow its user to add content to it. In order to do that, the user has to use the playlistItems resource.

In this lesson, we’ll explore the playlistItems resource, which offers multiple tools, like list, insert, update, and delete. We’ll interact with a playlist on YouTube through these methods.

Insert a playlist item

In this section, we’ll use the insert method of the playlistItems resource to add a playlist item in a YouTube playlist by sending a POST request to the following URL:

https://www.googleapis.com/youtube/v3/playlistItems

Here are some important parameters that we can use to call the endpoint:

Request parameters

Name

Type

Category

Description

part

String

Required

This parameter serves two functions. It specifies the properties that will be set by the user as well as the properties that will be included in the API response, which are contentDetails, id, snippet, and status.

onBehalfOfContentOwner

String

Optional

Used to identify that the authenticated user is making changes to the content on behalf of the content owner.

snippet.playlistId


String

Required

Used to pass the playlist ID of the content that the user wants to update.

snippet.kind


String

Required

Used to identify the resource type of the resource used in the API call.

snippet.resourceId

String

Required

Used to provide the resource ID that the user wants to add to their playlist.

Click the “Run” button to add our video to the playlist.

Press + to interact
import fetch from 'node-fetch';
const endpointUrl = new URL('https://www.googleapis.com/youtube/v3/playlistItems');
// Define Header Parameters here
const headerParameters = {
  Authorization: 'Bearer {{ACCESS_TOKEN}}',
  Accept: 'application/json',
};
const queryParameters = new URLSearchParams({
  part: 'snippet',
});
// Define Body Parameters her
const bodyParameters = JSON.stringify({
  snippet: {
    playlistId: '{{PLAYLIST_ID}}',
    resourceId: {
      kind: 'youtube#video',
      videoId: '{{VIDEO_ID}}',
    },
  },
});
const options = {
  method: 'POST',
  headers: headerParameters,
  body: bodyParameters,
};
async function insertPlaylistItem() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
insertPlaylistItem();

Let’s understand how the above code works by breaking it down:

  • Lines 11–13: We define a variable with the name queryParameters in which we set the value of the part parameter as snippet. We do this to indicate that the body provided a snippet object.

  • Lines 16–24: We define a variable with the name bodyParameters in which we set the values of the snippet properties.

Some important response fields are as follows:

Response fields

Name

Type

Description

kind

String

Reflect the resource type of the API call.

etag

ETag

Contains the resource ETag.

id

String

Contains the ID of the playlist item that is being added to the playlist.

snippet.thumbnails

Object

Contains the thumbnail details of the resource.

snippet.title

String

Contains the title of the playlist.

channelId

String

Contains the ID of the channel.

Update a playlist items

After inserting a playlist item into a playlist, we can also make changes to that playlist item. For that purpose, we’ll use the update method of the playlistItems resource by sending a PUT request to the following URL:

https://www.googleapis.com/youtube/v3/playlistItems

This endpoint mainly uses the same parameters used for the previous endpoint. We have to provide the id parameter to specify the playlist item that needs updating.
We need to add a title for our playlist item in the resourceId.title parameter in the below widget.

Click the “Run” button to add the title of the playlist item.

Press + to interact
import fetch from 'node-fetch';
const endpointUrl = new URL('https://www.googleapis.com/youtube/v3/playlistItems');
// Define Header Parameters here
const headerParameters = {
  Authorization: 'Bearer {{ACCESS_TOKEN}}',
  Accept: 'application/json',
};
const queryParameters = new URLSearchParams({
  part: 'snippet',
});
// Define Body Parameters here
const bodyParameters = JSON.stringify({
  id: '{{PLAYLIST_ITEM_ID}}',
  snippet: {
    playlistId: '{{PLAYLIST_ID}}',
    resourceId: {
      kind: 'youtube#video',
      videoId: '{{VIDEO_ID}}',
      title: 'This is a updated title for the playlist item',
    },
  },
});
const options = {
  method: 'PUT',
  headers: headerParameters,
  body: bodyParameters,
};
async function updatePlaylistItem() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
updatePlaylistItem();

We define an id parameter to identify the playlist item that we want to update. The method type is PUT for this endpoint. All of the remaining code is similar to the code used for inserting a playlist item. 

In the case of successful execution of the above code, it will mainly return the same response fields that we received in the insert method.

List the playlist items

Now that we’ve updated our playlist items, it’s time for us to verify whether they’ve been updated or not. To do that, we’ll use the list method of the PlaylistItems resource. In order to retrieve the playlist items of a playlist, we’ll send the GET request to the following URL:

https://www.googleapis.com/youtube/v3/playlistItems

Here are some important parameters that we can use to call the endpoint:

Request parameters

Name

Type

Category

Description

playlistId

String

Optional

Used to list all the playlist items of any specific playlist.

id

String

Optional

Used to list the details of a single playlist item defined by its ID.

Note: In this lesson, we are only listing a specific playlist item. But the playlistItems resource also offers multiple listing methods.

Click the “Run” button in the code widget below to retrieve the playlist items.

Press + to interact
// Importing libraries here
import fetch from 'node-fetch';
// Define endpoint URL here
const endpointUrl = new URL('https://www.googleapis.com/youtube/v3/playlistItems');
// Define Header Parameters here
const headerParameters = {
  Authorization: 'Bearer {{ACCESS_TOKEN}}',
  Accept: 'application/json',
};
// Define Query Parameters here
const queryParameters = new URLSearchParams({
  part: 'snippet,contentDetails',
  id: '{{PLAYLIST_ITEM_ID}}',
});
// Setting API call options
const options = {
  method: 'GET',
  headers: headerParameters,
};
// Function to make API call
async function fetchPlaylistItemList() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    // Printing response
    printResponse(response);
  } catch (error) {
    // Printing error message
    printError(error);
  }
}
// Calling function to make API call
fetchPlaylistItemList();

Let’s take a look at the following code explanation of the above code:

  • Line 5: We define a variable named endpointUrl in which we passed the endpoint URL.

  • Lines 14–17: We define a variable named queryParameters in which we define the id parameter, which is used to pass the playlist ID that the user wants to list.

Some of the response fields are as follows:

Response fields

Name

Type

Description

kind

String

Reflects the resource type of the API call.

etag

ETag

This field contains the resource ETag.

id

String

Contains the ID of the playlist item that is being updated.

snippet.description

String

Contains the description of the playlist item.

snippet.title

String

Contains the title of the playlist item.

channelId

String

Contains the ID of the channel.

items[]

List

Contains the list of the playlist item.