YouTube

YouTube

API Reference

The YouTube Data API lets you incorporate functions normally executed on the YouTube website into your own website or application. The lists below identify the different types of resources that you can retrieve using the API. The API also supports methods to insert, update, or delete many of these resources.

This reference guide explains how to use the API to perform all of these operations. The guide is organized by resource type. A resource represents a type of item that comprises part of the YouTube experience, such as a video, a playlist, or a subscription. For each resource type, the guide lists one or more data representations, and resources are represented as JSON objects. The guide also lists one or more supported methods (LIST, POST, DELETE, etc.) for each resource type and explains how to use those methods in your application.

Calling the API

The following requirements apply to YouTube Data API requests:

  1. Every request must either specify an API key (with the key parameter) or provide an OAuth 2.0 token. Your API key is available in the API console's API Access pane for your project.

  2. You must send an authorization token for every insert, update, and delete request. You must also send an authorization token for any request that retrieves the authenticated user's private data.

    In addition, some API methods for retrieving resources may support parameters that require authorization or may contain additional metadata when requests are authorized. For example, a request to retrieve a user's uploaded videos may also contain private videos if the request is authorized by that specific user.

  3. The API supports the OAuth 2.0 authentication protocol. You can provide an OAuth 2.0 token in either of the following ways:

    • Use the access_token query parameter like this: ?access_token=oauth2-token
    • Use the HTTP Authorization header like this: Authorization: Bearer oauth2-token

    Complete instructions for implementing OAuth 2.0 authentication in your application can be found in the the authentication guide.

Resource types

The API interacts with the following types of resources:

  1. Activities
  2. ChannelBanners
  3. Channels
  4. GuideCategories
  5. PlaylistItems
  6. Playlists
  7. Search
  8. Subscriptions
  9. Thumbnails
  10. VideoCategories
  11. Videos
  12. Watermarks

Activities

An activity resource contains information about an action that a particular channel, or user, has taken on YouTube. The actions reported in activity feeds include rating a video, sharing a video, marking a video as a favorite, commenting on a video, uploading a video, and so forth. Each activity resource identifies the type of action, the channel associated with the action, and the resource(s) associated with the action, such as the video that was rated or uploaded.

For more information about this resource, see its resource representation and list of properties.

Method HTTP request Description
URIs relative to https://www.googleapis.com/youtube/v3
list GET /activities Returns a list of channel activity events that match the request criteria. For example, you can retrieve events associated with a particular channel, events associated with the user's subscriptions and Google+ friends, or the YouTube home page feed, which is customized for each user.
insert POST /activities Posts a bulletin for a specific channel. (The user submitting the request must be authorized to act on the channel's behalf.)

Note: Even though an activity resource can contain information about actions like a user rating a video or marking a video as a favorite, you need to use other API methods to generate those activity resources. For example, you would use the API's videos.rate() method to rate a video and the playlistItems.insert() method to mark a video as a favorite.

ChannelBanners

A channelBanner resource contains the URL that you would use to set a newly uploaded image as the banner image for a channel.

For more information about this resource, see its resource representation and list of properties.

Method HTTP request Description
URIs relative to https://www.googleapis.com/youtube/v3
insert POST /channelBanners/insert Uploads a channel banner image to YouTube. This method represents the first two steps in a three-step process to update the banner image for a channel:

  1. Call the channelBanners.insert method to upload the binary image data to YouTube. The image must have a 16:9 aspect ratio and be at least 2120x1192 pixels.
  2. Extract the url property's value from the response that the API returns for step 1.
  3. Call the channels.update method to update the channel's branding settings. Set the brandingSettings.image.bannerExternalUrl property's value to the URL obtained in step 2.

Channels

A channel resource contains information about a YouTube channel.

For more information about this resource, see its resource representation and list of properties.

Method HTTP request Description
URIs relative to https://www.googleapis.com/youtube/v3
list GET /channels Returns a collection of zero or more channel resources that match the request criteria.
update PUT /channels Updates a channel's metadata. Note that this method currently only supports updates to the channel resource's brandingSettings and invideoPromotion objects and their child properties.

GuideCategories

A guideCategory resource identifies a category that YouTube algorithmically assigns based on a channel's content or other indicators, such as the channel's popularity. The list is similar to video categories, with the difference being that a video's uploader can assign a video category but only YouTube can assign a channel category.

For more information about this resource, see its resource representation and list of properties.

Method HTTP request Description
URIs relative to https://www.googleapis.com/youtube/v3
list GET /guideCategories Returns a list of categories that can be associated with YouTube channels.

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.

For more information about this resource, see its resource representation and list of properties.

Method HTTP request Description
URIs relative to https://www.googleapis.com/youtube/v3
delete DELETE /playlistItems Deletes a playlist item.
insert POST /playlistItems Adds a resource to a playlist.
list GET /playlistItems 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.
update PUT /playlistItems Modifies a playlist item. For example, you could update the item's position in the playlist.

Playlists

A playlist resource represents a YouTube playlist. 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. By default, playlists are publicly visible to other users, but playlists can be public or private.

YouTube also 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 more information about this resource, see its resource representation and list of properties.

Method HTTP request Description
URIs relative to https://www.googleapis.com/youtube/v3
delete DELETE /playlists Deletes a playlist.
list GET /playlists Returns a collection of playlists that match the API request parameters. For example, you can retrieve all playlists that the authenticated user owns, or you can retrieve one or more playlists by their unique IDs.
insert POST /playlists Creates a playlist.
update PUT /playlists Modifies a playlist. For example, you could change a playlist's title, description, or privacy status.

A search result contains information about a YouTube video, channel, or playlist that matches the search parameters specified in an API request. While a search result points to a uniquely identifiable resource, like a video, it does not have its own persistent data.

For more information about this resource, see its resource representation and list of properties.

Method HTTP request Description
URIs relative to https://www.googleapis.com/youtube/v3
list GET /search Returns a collection of search results that match the query parameters specified in the API request. By default, a search result set identifies matching video, channel, and playlist resources, but you can also configure queries to only retrieve a specific type of resource.

Subscriptions

A subscription resource contains information about a YouTube user subscription. A subscription notifies a user when new videos are added to a channel or when another user takes one of several actions on YouTube, such as uploading a video, rating a video, or commenting on a video.

For more information about this resource, see its resource representation and list of properties.

Method HTTP request Description
URIs relative to https://www.googleapis.com/youtube/v3
delete DELETE /subscriptions Deletes a subscription.
insert POST /subscriptions Adds a subscription for the authenticated user's channel.
list GET /subscriptions Returns subscription resources that match the API request criteria.

Thumbnails

A thumbnail resource identifies different thumbnail image sizes associated with a resource. Please note the following characteristics of thumbnail images:

  • A resource's snippet.thumbnails property is an object that identifies the thumbnail images available for that resource.
  • A thumbnail resource contains a series of objects. The name of each object (default, medium, high, etc.) refers to the thumbnail image size.
  • Different types of resources may support different thumbnail image sizes.
  • Different types of resources may define different sizes for thumbnail images with the same name. For example, the default thumbnail image for a video resource is typically 120px by 90px, and the default thumbnail image for a channel resource is typically 88px by 88px.
  • Resources of the same type may still have different thumbnail image sizes for certain images depending on the resolution of the original image or content uploaded to YouTube. For example, an HD video may support higher resolution thumbnails than non-HD videos.
  • Each object that contains information about a thumbnail image size has a width property and a height property. However, the width and height properties may not be returned for that image.
  • If an uploaded thumbnail image does not match the required dimensions, the image is resized to match the correct size without changing its aspect ratio. The image is not cropped, but may include black bars so that the size is correct.

For more information about this resource, see its resource representation and list of properties.

Method HTTP request Description
URIs relative to https://www.googleapis.com/youtube/v3
set POST /thumbnails/set Uploads a custom video thumbnail to YouTube and sets it for a video.

VideoCategories

A videoCategory resource identifies a category that has been or could be associated with uploaded videos.

For more information about this resource, see its resource representation and list of properties.

Method HTTP request Description
URIs relative to https://www.googleapis.com/youtube/v3
list GET /videoCategories Returns a list of categories that can be associated with YouTube videos.

Videos

A video resource represents a YouTube video.

For more information about this resource, see its resource representation and list of properties.

Method HTTP request Description
URIs relative to https://www.googleapis.com/youtube/v3
insert POST /videos Uploads a video to YouTube and optionally sets the video's metadata.
list GET /videos Returns a list of videos that match the API request parameters.
delete DELETE /videos Deletes a YouTube video.
update PUT /videos Updates a video's metadata.
rate POST /videos/rate Add a like or dislike rating to a video or remove a rating from a video.
getRating GET /videos/getRating Retrieves the ratings that the authorized user gave to a list of specified videos.

Watermarks

A watermark resource identifies an image that displays during playbacks of a 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 during video playbacks and the length of time it is visible.

For more information about this resource, see its resource representation and list of properties.

Method HTTP request Description
URIs relative to https://www.googleapis.com/youtube/v3
set POST /watermarks/set Uploads a watermark image to YouTube and sets it for a channel.
unset POST /watermarks/unset Deletes a channel's watermark image.

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.