Implementation and Migration: New features

The sections below identify features that were introduced in the v3 API. The v2 API did not support these features. Note that the items listed in this section are also listed in other documents in this series that correspond to the actual functionality of the new feature.

Search requests

Search by topic ID

The v3 API supports the topicId parameter, which indicates that the API response should only contain resources associated with the specified topic. The Searching with Freebase topics guide explains this functionality in detail.

Channels (profiles)

Retrieve a list of subscribers to the authorized user's channel

To retrieve a list of channels that subscribe to the currently authenticated user's channel, call the channels.list method and set the mySubscribers parameter's value to true. The request must be authorized using OAuth 2.0.

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.channels.list?
part=snippet,contentDetails
&mySubscribers=true

Update a channel's in-video promotional campaign data

You can call the channels.update method to modify a channel's in-video promotional campaign settings. A channel can use an in-video promotional campaign to display thumbnail images for a promoted video within the video player during playbacks of the channel's videos. This Python code sample demonstrates how to call this function using the Google APIs Client Library for Python.

Related code samples: Python

Manage channel sections

The API supports the channelSections.list, channelSections.insert, channelSections.update, and channelSections.delete methods for managing channel sections. A channel section is a set of videos that are featured on a channel. For example, a section could include a channel's latest uploads, most popular uploads, or videos from one or more playlists.

The example below retrieves the channel sections for Google's official YouTube channel. The request calls the channelSections.list method and sets the channelId parameter value to UCK8sQmJBp8GCxrOtXWBpyEA, which is the channel ID for Google's channel.

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.channelSections.list?
part=snippet,contentDetails
&channelId=UCK8sQmJBp8GCxrOtXWBpyEA

This request requires authorization if, instead of using the channelId parameter, you set the mine parameter value to true. That parameter indicates that you are retrieving channel sections for the currently authenticated user's channel.

Upload and set a watermark image for a channel

You can call the watermarks.set method to upload a watermark image and set it for a channel. The image then displays during playbacks of the specified channel's videos. You can also specify a target channel to which the image will link as well as timing details that determine when the watermark appears and how long it is visible.

The watermarks.unset method deletes a channel's watermark image.

Unfortunately, this query cannot be tested using the APIs Explorer because the APIs Explorer does not support the ability to upload media files, which is a requirement for this method.

Videos

Upload a custom thumbnail image and set it for a video

You can use the v3 API's thumbnails.set method to upload a custom thumbnail image and set it for a video. In your request, the videoId parameter's value identifies the video for which the thumbnail will be used.

This query cannot be tested using the APIs Explorer because the APIs Explorer does not support the ability to upload media files, which is a requirement for this method.

Related code samples: PHP, Python

Ratings

Retrieving the current user's rating of a video

The videos.getRating method lets you retrieve the currently authenticated user's rating of one or more videos. In your request, set the id parameter's value to a comma-separated list of YouTube video IDs for the resources for which you are retrieving rating data. Note that this request must be authorized using OAuth 2.0.

The sample request below retrieves the current user's rating of the video of the keynote speech at the 2014 Google I/O conference. (If you executed the previous example in the APIs Explorer, the API response should indicate that the rating is like.

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.getRating?
id=wtLJPvx7-ys

Retrieving videos rated by the current user

The videos.list method's myRating parameter lets you retrieve a list of videos rated by the user authorizing the API request. The parameter value indicates whether you want to retrieve liked or disliked videos.

The sample request below retrieves a list of videos to which the current user gave a like rating. The request must be authorized using OAuth 2.0.

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.list?
part=snippet
&myRating=like
Note: You can also retrieve a list of the user's liked videos (but not disliked videos) by following the flow for retrieving a channel's favorite videos. In step 1 of that process, instead of retrieving the playlist ID for the channel's favorite videos, retrieve the playlist ID for the channel's liked videos. The contentDetails.relatedPlaylists.likes property contains the value.

Thus, the API allows you to retrieve a list of videos that the user liked using either the videos.list method or the playlistItems.list method. Since different information is returned in a video resource than a playlistItem resource, you can choose the method that best suits your needs.

Comments

Retrieving channel comments

The API supports the ability to either retrieve comments threads about a channel or to retrieve all comment threads associated with a channel. In the latter case, the API could contain comments about the channel or about any of the channel's videos.

The request below retrieves all comment threads associated with the GoogleDevelopers YouTube channel:

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.commentThreads.list?
part=snippet,replies
&allThreadsRelatedToChannelId=UC_x5XG1OV2P6uZZ5FSM9Ttw

Updating a top-level comment or a reply to a comment

To update the text of a top-level comment or a reply to a top-level comment, call the comments.update method. Set the part parameter's value to snippet. In the request body, the id property identifies the comment that you are modifying and the new comment text.

  • In a commentThread resource, which identifies a top-level comment, the snippet.topLevelComment[].id property specifies the comment's unique ID.
  • In a comment resource, which can identify either a top-level comment or a reply to a comment, the id property specifies the comment's unique ID.

The sample request below updates the text of an existing comment.

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.comments.update?
part=snippet

The request body contains the JSON snippet shown below. To execute the request in the APIs Explorer, set the id property's value to identify the comment that you are updating. The request must be authorized by the comment's author.

{
  "id": "COMMENT_ID",
  "snippet": {
    "textOriginal": "That is true."
  }
}

Note: You can also use the commentThreads.update method to update the text of a top-level comment.

Marking a comment as spam

To mark a comment as spam, call the comments.markAsSpam method. Use the id parameter's value to identify the comment. Any authenticated user can mark a comment as spam.

If you test the query below in the APIs Explorer, you will need to substitute a valid comment ID or comment thread ID for the id parameter value in the request.

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.comments.markAsSpam?
id=COMMENT_ID

Setting a comment's moderation status

To set a comment's moderation status, call the comments.setModerationStatus method. This action is used when a channel owner moderates comments on the channel or the channel's videos.

When calling this method, set the id parameter's value to identify the comment. Also set the moderationStatus parameter to the desired status. A comment's status can only be adjusted by the owner of the channel where the comment appears.

  • Step 1: Retrieve comments that are being held for review

    Call the commentThreads.list method to retrieve comments for the channel or video. Set the moderationStatus parameter's value to heldForReview. The API response could be used to display a list of comments with an option for the channel owner to publish or reject each one.

  • Step 2: Update the moderation status of a comment

    Call the comments.setModerationStatus method to update the comment's status. Use the id parameter's value to specify the comment's unique ID. Set the moderationStatus parameter to either published or rejected. If you are rejecting a comment, you can also set the banAuthor parameter to true to prevent the author from making additional comments on the channel or video.

Note: The API does not provide a way to list or otherwise discover rejected comments. However, you can still change the moderation status of a rejected comment to published if the comment's unique ID is known. In addition, once a comment's moderation status is updated to either published or rejected, the moderation status cannot be changed back to heldForReview.

Captions

Set a caption track to not be publicly visible

If you set the caption resource's snippet.isDraft property to true, the track will not be publicly visible.

Video flagging

Retrieve video abuse reasons

An API request that reports an abusive video must specify the reason that the video is being flagged. For some types of reasons, a secondary reason is also supported and strongly encouraged.

The API's videoAbuseReportReasons.list method returns a list of reasons that a video might be flagged for containing abusive content. The JSON snippet below shows a sample videoAbuseReportReason resource:

{
  "kind": "youtube#videoAbuseReportReason",
  "etag": "\"tbWC5XrSXxe1WOAx6MK9z4hHSU8/Or2VqBIilpHU7j__oPzUFCvGVBw\"",
  "id": "S",
  "snippet": {
    "label": "Spam or misleading",
    "secondaryReasons": [
      {
        "id": "27",
        "label": "Spam or mass advertising"
      },
      {
        "id": "28",
        "label": "Misleading thumbnail"
      },
      {
        "id": "29",
        "label": "Malware or phishing"
      },
      {
        "id": "30",
        "label": "Pharmaceutical drugs for sale"
      },
      {
        "id": "31",
        "label": "Other misleading info"
      }
    ]
  }
}

Typically, a user who flags a video would be prompted to choose one of the reasons. Your application would then report the video itself using the videos.reportAbuse method.

Send feedback about...

YouTube Data API
YouTube Data API