# Youtube Data Api > You can explore common use cases for the YouTube Data API and YouTube Live Streaming API on the [use cases and code samples](https://developers.google.com/youtube/v3/code_samples/code_snippets) page. --- # Source: https://developers.google.com/youtube/v3/code_samples.md.txt # YouTube Data API (v3) Code Samples You can explore common use cases for the YouTube Data API and YouTube Live Streaming API on the [use cases and code samples](https://developers.google.com/youtube/v3/code_samples/code_snippets) page. The page lets you select an API resource and method and then lists common use cases for that method. You can then click on any use case to populate the APIs Explorer widget with sample parameter and property values for that use case. You can also open the fullscreen APIs Explorer widget to see working code samples for Java, JavaScript, PHP, and Python. If you update parameter or property values in the APIs Explorer, the code samples also update to reflect your changes. The following section lists code samples available in other languages. ## Standalone code snippets The lists below identify code samples available for the YouTube Data API (v3) in languages other than Java, JavaScript, PHP, and Python. As noted in the previous section, code samples for those languages are available on the [use cases and code samples](https://developers.google.com/youtube/v3/code_samples/code_snippets) page. ### Apps Script | Code sample | Methods | |-------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------| | [Add a channel subscription](https://developers.google.com/youtube/v3/code_samples/apps-script#subscribe_to_channel) | [subscriptions.insert](https://developers.google.com/youtube/v3/docs/subscriptions/insert) | | [Retrieve current user's uploads](https://developers.google.com/youtube/v3/code_samples/apps-script#retrieve_my_uploads) | [channels.list](https://developers.google.com/youtube/v3/docs/channels/list) | | [Search for videos related to a keyword](https://developers.google.com/youtube/v3/code_samples/apps-script#search_by_keyword) | [search.list](https://developers.google.com/youtube/v3/docs/search/list) | | [Update a video](https://developers.google.com/youtube/v3/code_samples/apps-script#update_video) | [videos.update](https://developers.google.com/youtube/v3/docs/videos/update) | ### Go | Code sample | Methods | |----------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------| | [Authorize a request](https://developers.google.com/youtube/v3/code_samples/go#authorize_a_request) | Any method requiring authorization | | [Retrieve current user's uploads](https://developers.google.com/youtube/v3/code_samples/go#retrieve_my_uploads) | [playlistItems.list](https://developers.google.com/youtube/v3/docs/playlistItems/list) | | [Search for videos related to a keyword](https://developers.google.com/youtube/v3/code_samples/go#search_by_keyword) | [search.list](https://developers.google.com/youtube/v3/docs/search/list) | | [Upload a video](https://developers.google.com/youtube/v3/code_samples/go#upload_a_video) | [videos.insert](https://developers.google.com/youtube/v3/docs/videos/insert) | ### .NET | Code sample | Methods | |-----------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [Create a playlist](https://developers.google.com/youtube/v3/code_samples/dotnet#create_a_playlist) | [playlists.insert](https://developers.google.com/youtube/v3/docs/playlists/insert) | | [Retrieve current user's uploaded videos](https://developers.google.com/youtube/v3/code_samples/dotnet#retrieve_my_uploads) | [channels.list](https://developers.google.com/youtube/v3/docs/channels/list) [playlistItems.list](https://developers.google.com/youtube/v3/docs/playlistItems/list) | | [Search for videos related to a keyword](https://developers.google.com/youtube/v3/code_samples/dotnet#search_by_keyword) | [search.list](https://developers.google.com/youtube/v3/docs/search/list) | | [Upload a video](https://developers.google.com/youtube/v3/code_samples/dotnet#upload_a_video) | [videos.insert](https://developers.google.com/youtube/v3/docs/videos/insert) | ### Ruby | Code sample | Methods | |------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [Authorize a request](https://developers.google.com/youtube/v3/code_samples/ruby#authorize_a_request) | Any method requiring authorization | | [Create a channel subscription](https://developers.google.com/youtube/v3/code_samples/ruby#add_a_channel_subscription) | [subscriptions.insert](https://developers.google.com/youtube/v3/docs/subscriptions/insert) | | [Retrieve current user's uploads](https://developers.google.com/youtube/v3/code_samples/ruby#retrieve_my_uploads) | [channels.list](https://developers.google.com/youtube/v3/docs/channels/list) [playlistItems.list](https://developers.google.com/youtube/v3/docs/playlistItems/list) | | [Search for videos related to a keyword](https://developers.google.com/youtube/v3/code_samples/ruby#search_by_keyword) | [search.list](https://developers.google.com/youtube/v3/docs/search/list) | | [Upload a video](https://developers.google.com/youtube/v3/code_samples/ruby#upload_a_video) | [videos.insert](https://developers.google.com/youtube/v3/docs/videos/insert) | You may also be able to adapt one of the other [Ruby samples](https://github.com/googleapis/google-api-ruby-client/tree/main/samples). --- # Source: https://developers.google.com/youtube/v3/code_samples/apps-script.md.txt # Apps Script Code Samples The following Apps Script code samples are available for the YouTube Data API. You can download these code samples from the `apps-script` folder of the [YouTube APIs code sample repository on GitHub](https://github.com/youtube/api-samples). ## Retrieve my uploads This function retrieves the current script user's uploaded videos. To execute, it requires the OAuth read/write scope for YouTube as well as user authorization. In Apps Script's runtime environment, the first time a user runs a script, Apps Script will prompt the user for permission to access the services called by the script. After permissions are granted, they are cached for some period of time. The user running the script will be prompted for permission again once the permissions required change, or when they are invalidated by the `ScriptApp.invalidateAuth()` function. This script takes the following steps to retrieve the active user's uploaded videos: 1. Fetches the user's channels. 2. Fetches the user's 'uploads' playlist. 3. Iterates through this playlist and logs the video IDs and titles. 4. Fetches a next page token, if any. If there is one, fetches the next page. Repeat step 3. ```gdscript /** * This function retrieves the current script user's uploaded videos. To execute, * it requires the OAuth read/write scope for YouTube as well as user authorization. * In Apps Script's runtime environment, the first time a user runs a script, Apps * Script will prompt the user for permission to access the services called by the * script. After permissions are granted, they are cached for some periodF of time. * The user running the script will be prompted for permission again once the * permissions required change, or when they are invalidated by the * ScriptApp.invalidateAuth() function. * * This script takes the following steps to retrieve the active user's uploaded videos: * 1. Fetches the user's channels * 2. Fetches the user's 'uploads' playlist * 3. Iterates through this playlist and logs the video IDs and titles * 4. Fetches a next page token (if any). If there is one, fetches the next page. GOTO Step 3 */ function retrieveMyUploads() { var results = YouTube.Channels.list('contentDetails', {mine: true}); for(var i in results.items) { var item = results.items[i]; // Get the playlist ID, which is nested in contentDetails, as described in the // Channel resource: https://developers.google.com/youtube/v3/docs/channels var playlistId = item.contentDetails.relatedPlaylists.uploads; var nextPageToken = ''; // This loop retrieves a set of playlist items and checks the nextPageToken in the // response to determine whether the list contains additional items. It repeats that process // until it has retrieved all of the items in the list. while (nextPageToken != null) { var playlistResponse = YouTube.PlaylistItems.list('snippet', { playlistId: playlistId, maxResults: 25, pageToken: nextPageToken }); for (var j = 0; j < playlistResponse.items.length; j++) { var playlistItem = playlistResponse.items[j]; Logger.log('[%s] Title: %s', playlistItem.snippet.resourceId.videoId, playlistItem.snippet.title); } nextPageToken = playlistResponse.nextPageToken; } } } ``` ## Search by keyword This function searches for videos related to the keyword `'dogs'`. The video IDs and titles of the search results are logged to Apps Script's log. Note that this sample limits the results to 25. To return more results, pass additional parameters as documented in [Search:list](https://developers.google.com/youtube/v3/docs/search/list). ```transact-sql /** * This function searches for videos related to the keyword 'dogs'. The video IDs and titles * of the search results are logged to Apps Script's log. * * Note that this sample limits the results to 25. To return more results, pass * additional parameters as documented here: * https://developers.google.com/youtube/v3/docs/search/list */ function searchByKeyword() { var results = YouTube.Search.list('id,snippet', {q: 'dogs', maxResults: 25}); for(var i in results.items) { var item = results.items[i]; Logger.log('[%s] Title: %s', item.id.videoId, item.snippet.title); } } ``` ## Search by topic This function searches for videos that are associated with a particular Freebase topic, logging their video IDs and titles to the Apps Script log. This example uses the topic ID for Google Apps Script. Note that this sample limits the results to 25. To return more results, pass additional parameters as documented in [Search:list](https://developers.google.com/youtube/v3/docs/search/list). ```transact-sql /** * This function searches for videos that are associated with a particular Freebase * topic, logging their video IDs and titles to the Apps Script log. This example uses * the topic ID for Google Apps Script. * * Note that this sample limits the results to 25. To return more results, pass * additional parameters as documented here: * https://developers.google.com/youtube/v3/docs/search/list */ function searchByTopic() { var mid = '/m/0gjf126'; var results = YouTube.Search.list('id,snippet', {topicId: mid, maxResults: 25}); for(var i in results.items) { var item = results.items[i]; Logger.log('[%s] Title: %s', item.id.videoId, item.snippet.title); } } ``` ## Subscribe to channel This sample subscribes the active user to the Google Developers YouTube channel, specified by the channelId. ```gdscript /** * This sample subscribes the active user to the Google Developers * YouTube channel, specified by the channelId. */ function addSubscription() { // Replace this channel ID with the channel ID you want to subscribe to var channelId = 'UC_x5XG1OV2P6uZZ5FSM9Ttw'; var resource = { snippet: { resourceId: { kind: 'youtube#channel', channelId: channelId } } }; try { var response = YouTube.Subscriptions.insert(resource, 'snippet'); Logger.log(response); } catch (e) { if(e.message.match('subscriptionDuplicate')) { Logger.log('Cannot subscribe; already subscribed to channel: ' + channelId); } else { Logger.log('Error adding subscription: ' + e.message); } } } ``` ## Update video This sample finds the active user's uploads, then updates the most recent upload's description by appending a string. ```gdscript /** * This sample finds the active user's uploads, then updates the most recent * upload's description by appending a string. */ function updateVideo() { // 1. Fetch all the channels owned by active user var myChannels = YouTube.Channels.list('contentDetails', {mine: true}); // 2. Iterate through the channels and get the uploads playlist ID for (var i = 0; i < myChannels.items.length; i++) { var item = myChannels.items[i]; var uploadsPlaylistId = item.contentDetails.relatedPlaylists.uploads; var playlistResponse = YouTube.PlaylistItems.list('snippet', { playlistId: uploadsPlaylistId, maxResults: 1 }); // Get the videoID of the first video in the list var video = playlistResponse.items[0]; var originalDescription = video.snippet.description; var updatedDescription = originalDescription + ' Description updated via Google Apps Script'; video.snippet.description = updatedDescription; var resource = { snippet: { title: video.snippet.title, description: updatedDescription, categoryId: '22' }, id: video.snippet.resourceId.videoId }; YouTube.Videos.update(resource, 'id,snippet'); } } ``` --- # Source: https://developers.google.com/youtube/v3/code_samples/code_snippet_instructions.md.txt # Data API Code Snippets ## Instructions The interactive code snippets tool lets you easily test API requests and generate code samples specific to those requests. For any given method, the tool shows code snippets for one or more use cases, and each use case describes a common way of calling that method. For example, you can call the `channels.list` method to retrieve data about a specific channel or about the current user's channel. ### Execute API requests You can execute requests by clicking the **Execute** button next to the list of request parameters. If you have not previously authorized the application to submit API requests on your behalf, you will be prompted to do so. As an extra precaution, if your request performs a write operation -- inserting, updating, or deleting resources associated with your channel -- you will be asked to confirm that you want to execute the request before it actually executes. ![](https://developers.google.com/static/youtube/images/confirm-interactive-snippet-request.png) ### Toggle code snippets and full samples For each use case, the tool shows a code snippet that identifies code specific to the particular method being called. Each snippet identifies the method being called as well as parameter and property values used in the API request. In addition, the tool also shows a full code sample that puts that code snippet into a template that defines boilerplate functions for authorizing API requests and constructing API requests. You can use the slider above the samples to switch between the snippet and the full sample: ![](https://developers.google.com/static/youtube/images/interactive-snippet-slider.png) #### Run full code samples locally The full code samples are designed to be copied and run locally. Please note the following prerequisites and set up steps for running the full code samples: Java **Prerequisites** - Java 1.7 or greater - Gradle 2.3 or greater **Set up your project and run code samples** 1. Create a project in the [API Console](https://console.cloud.google.com/) and set up credentials for a web application. Set the authorized redirect URIs as appropriate. 2. Follow the instructions in the [API Java Quickstart Guide](https://developers.google.com/youtube/v3/quickstart/java) for preparing your project, but replace the contents of the default `build.gradle` file with the following code: ``` apply plugin: 'java' apply plugin: 'application' mainClassName = 'ApiExample' sourceCompatibility = 1.7 targetCompatibility = 1.7 version = '1.0' repositories { mavenCentral() } dependencies { compile 'com.google.api-client:google-api-client:1.22.0' compile 'com.google.oauth-client:google-oauth-client-jetty:1.22.0' compile 'com.google.apis:google-api-services-youtube:v3-rev182-1.22.0' compile group: 'com.google.code.gson', name: 'gson', version: '1.7.2' compile group: 'com.fasterxml.jackson.core', name: 'jackson-databind', version: '2.4.4' } compileJava { options.compilerArgs << "-Xlint:unchecked" << "-Xlint:deprecation" } ``` 3. From your working directory, save the `client_secrets.json` file associated with your credentials to `src/main/resources/client_secret.json`. 4. From your working directory, copy the full code sample to `src/main/java/ApiExample.java`. (The class name in each sample is `ApiExample` so that you do not need to modify the `build.gradle` file to run different samples.) 5. Run the sample from the command line: ``` gradle -q run ``` 6. Most samples print something to `STDOUT`. You can also check the YouTube website to see the effects of requests that write data, such as requests that create playlists or channel sections. JavaScript 1. Create a project in the [API Console](https://console.cloud.google.com/) and set up credentials for a web application. Set the authorized JavaScript origins to identify the URL from which you'll be sending requests (e.g. `http://localhost`). 2. Copy the full code sample to a local file accessible to your web server (e.g. `/var/www/html/example.html`). 3. Find the line in the code sample that sets the client ID to be used for the request, and replace the value with the client ID for your credentials: ``` gapi.client.init({ 'clientId': 'REPLACE_ME', ``` 4. Open the file in your browser (e.g. `http://localhost/example.html`). It is recommended to use a browser with a debugging console, such as Google Chrome. 5. Authorize the request if necessary. If the request is authorized, the debugging console should display the API response to the request as a JSON object. Node.js **Prerequisites** - Node.js must be installed. - The [npm](https://www.npmjs.com/) package management tool (comes with Node.js). - The Google APIs Client Library for Node.js: ``` npm install googleapis --save ``` - Access to the internet and a web browser. - A Google account. **Set up your project and run code samples** 1. Create a project in the [API Console](https://console.cloud.google.com/) and set up OAuth 2.0 credentials in the [Google API Console](https://console.cloud.google.com/). When setting up your credentials, set the application type to **Other**. 2. Save the `client_secret.json` file associated with your credentials to a local file. 3. Copy the full code sample to a local file in the same directory as the `client_secret.json` file (or modify the sample to correctly identify that file's location. 4. Run the sample from the command line: ``` node sample.js ``` 5. Most samples print something to `STDOUT` or, for web application examples, to the web page you're viewing. You can also check the YouTube website to see the effects of requests that write data, such as requests that create playlists or channel sections. Python **Prerequisites** - Python 2.6 or greater - The pip package management tool - The Google APIs Client Library for Python: ``` pip install --upgrade google-api-python-client ``` - The google-auth, google-auth-oauthlib, and google-auth-httplib2 for user authorization. ``` pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2 ``` - The Flask Python web application framework (if you are running the Python samples for web server applications). ``` pip install --upgrade flask ``` - The requests HTTP library. ``` pip install --upgrade requests ``` **Set up your project and run code samples** 1. Create a project in the [API Console](https://console.cloud.google.com/) and set up OAuth 2.0 credentials in the [Google API Console](https://console.cloud.google.com/). When setting up your credentials, set the application type to **Web application** for samples that use the Flask Python web application framework and also set authorized redirect URIs for those credentials. Otherwise, set the application type to **Other**. 2. Save the `client_secret.json` file associated with your credentials to a local file. 3. Copy the full code sample to a local file in the same directory as the `client_secret.json` file (or modify the sample to correctly identify that file's location. 4. Run the sample from the command line: ``` python sample.py ``` **Note for web server application examples:** If you are running the Python samples for web server applications, then running the script starts a local web server. To actually execute the API request, you need to go to the served web page in a browser. For example, the Python samples that use the Flask web application framework contain a line like this: `app.run('localhost', 8080, debug=True)` This code starts a local web server at `http://localhost:8080`. However, the script doesn't try to execute an API request until you actually navigate to `http://localhost:8080` in a browser. (The URL for your local server must also be set as an authorized redirect URI for your authorization credentials.) 5. Most samples print something to `STDOUT` or, for web application examples, to the web page you're viewing. You can also check the YouTube website to see the effects of requests that write data, such as requests that create playlists or channel sections. PHP **Prerequisites** - PHP 5.4 or greater with the command-line interface (CLI) and JSON extension installed. - The [Composer](https://getcomposer.org/) dependency management tool. - The Google APIs Client Library for PHP: ``` php composer.phar require google/apiclient:^2.0 ``` **Set up your project and run code samples** 1. Create a project in the [API Console](https://console.cloud.google.com/) and set up OAuth 2.0 credentials in the [Google API Console](https://console.cloud.google.com/). When setting up your credentials, set the application type to **Other**. 2. Save the `client_secret.json` file associated with your credentials to a local file. 3. Copy the full code sample to a local file in the same directory as the `client_secret.json` file (or modify the sample to correctly identify that file's location. 4. Run the sample from the command line: ``` php sample.php ``` 5. Most samples print something to `STDOUT` or, for web application examples, to the web page you're viewing. You can also check the YouTube website to see the effects of requests that write data, such as requests that create playlists or channel sections. Ruby **Prerequisites** - Ruby 2.0 or greater - The Google APIs Client Library for Ruby: ``` gem install google-api-client ``` **Set up your project and run code samples** 1. Create a project in the [API Console](https://console.cloud.google.com/) and set up OAuth 2.0 credentials in the [Google API Console](https://console.cloud.google.com/). When setting up your credentials, set the application type to **Other**. 2. Save the `client_secret.json` file associated with your credentials to a local file. 3. Copy the full code sample to a local file in the same directory as the `client_secret.json` file (or modify the sample to correctly identify that file's location. 4. Run the sample from the command line: ``` ruby sample.rb ``` 5. Most samples print something to `STDOUT` or, for web application examples, to the web page you're viewing. You can also check the YouTube website to see the effects of requests that write data, such as requests that create playlists or channel sections. Apps Script Follow the instructions for enabling [advanced Google services](https://developers.google.com/apps-script/guides/services/advanced) to enable YouTube features. Go 1. Create a project in the [API Console](https://console.cloud.google.com/) and set up OAuth 2.0 credentials in the [Google API Console](https://console.cloud.google.com/). When setting up your credentials, set the application type to **Other**. 2. Save the `client_secret.json` file associated with your credentials to a local file. 3. Copy the full code sample to a local file in the same directory as the `client_secret.json` file (or modify the sample to correctly identify that file's location. 4. Run the sample from the command line: ``` go run sample.go ``` 5. Most samples print something to `STDOUT` or, for web application examples, to the web page you're viewing. You can also check the YouTube website to see the effects of requests that write data, such as requests that create playlists or channel sections. ### Use boilerplate functions As noted above, full code samples use boilerplate code for authorizing and constructing API requests. For example, the `build_resource` function in Python samples uses a dictionary that maps resource properties to their values to construct a resource that can be inserted or updated. Similar functions are provided for JavaScript, PHP, Ruby, Go, and Apps Script. For example, the tabs below show how the boilerplate functions for building resources would be called to construct a `playlist` resource. Note that the boilerplate functions do not need to know what type of resource is being created. JavaScript ``` function createResource(properties) { var resource = {}; var normalizedProps = properties; for (var p in properties) { var value = properties[p]; if (p && p.substr(-2, 2) == '[]') { var adjustedName = p.replace('[]', ''); if (value) { normalizedProps[adjustedName] = value.split(','); } delete normalizedProps[p]; } } for (var p in normalizedProps) { // Leave properties that don't have values out of inserted resource. if (normalizedProps.hasOwnProperty(p) && normalizedProps[p]) { var propArray = p.split('.'); var ref = resource; for (var pa = 0; pa < propArray.length; pa++) { var key = propArray[pa]; if (pa == propArray.length - 1) { ref[key] = normalizedProps[p]; } else { ref = ref[key] = ref[key] || {}; } } }; } return resource; } var resource = createResource({ 'snippet.title': 'Sample playlist ', 'snippet.description': 'This is a sample playlist description.', 'snippet.tags[]': 'JavaScript code, interactive', 'snippet.defaultLanguage': '', 'status.privacyStatus': 'private' } ``` Python ``` # Build a resource based on a list of properties given as key-value pairs. # Leave properties with empty values out of the inserted resource. def build_resource(properties): resource = {} for p in properties: # Given a key like "snippet.title", split into "snippet" and "title", where # "snippet" will be an object and "title" will be a property in that object. prop_array = p.split('.') ref = resource for pa in range(0, len(prop_array)): is_array = False key = prop_array[pa] # Convert a name like "snippet.tags[]" to snippet.tags, but handle # the value as an array. if key[-2:] == '[]': key = key[0:len(key)-2:] is_array = True if pa == (len(prop_array) - 1): # Leave properties without values out of inserted resource. if properties[p]: if is_array: ref[key] = properties[p].split(',') else: ref[key] = properties[p] elif key not in ref: # For example, the property is "snippet.title", but the resource does # not yet have a "snippet" object. Create the snippet object here. # Setting "ref = ref[key]" means that in the next time through the # "for pa in range ..." loop, we will be setting a property in the # resource's "snippet" object. ref[key] = {} ref = ref[key] else: # For example, the property is "snippet.description", and the resource # already has a "snippet" object. ref = ref[key] return resource resource = build_resource({ 'snippet.title': 'Sample playlist ', 'snippet.description': 'This is a sample playlist description.', 'snippet.tags[]': 'Python code, interactive', 'snippet.defaultLanguage': '', 'status.privacyStatus': 'private'} ``` PHP ``` // Add a property to the resource. function addPropertyToResource(&$ref, $property, $value) { $keys = explode(".", $property); $is_array = false; foreach ($keys as $key) { // Convert a name like "snippet.tags[]" to "snippet.tags" and // set a boolean variable to handle the value like an array. if (substr($key, -2) == "[]") { $key = substr($key, 0, -2); $is_array = true; } $ref = &$ref[$key]; } // Set the property value. Make sure array values are handled properly. if ($is_array && $value) { $ref = $value; $ref = explode(",", $value); } elseif ($is_array) { $ref = array(); } else { $ref = $value; } } // Build a resource based on a list of properties given as key-value pairs. function createResource($properties) { $resource = array(); foreach ($properties as $prop => $value) { if ($value) { addPropertyToResource($resource, $prop, $value); } } return $resource; } $propertyObject = createResource(array( 'snippet.title' => 'Sample playlist ', 'snippet.description' => 'This is a sample playlist description.', 'snippet.tags[]' => 'Python code, interactive', 'snippet.defaultLanguage' => '', 'status.privacyStatus' => 'private')); ``` Ruby ``` # Build a resource based on a list of properties given as key-value pairs. def create_resource(properties) resource = {} properties.each do |prop, value| ref = resource prop_array = prop.to_s.split(".") for p in 0..(prop_array.size - 1) is_array = false key = prop_array[p] if key[-2,2] == "[]" key = key[0...-2] is_array = true end if p == (prop_array.size - 1) if is_array if value == "" ref[key.to_sym] = [] else ref[key.to_sym] = value.split(",") end elsif value != "" ref[key.to_sym] = value end elsif ref.include?(key.to_sym) ref = ref[key.to_sym] else ref[key.to_sym] = {} ref = ref[key.to_sym] end end end return resource end resource = create_resource({ 'snippet.title': 'Sample playlist ', 'snippet.description': 'This is a sample playlist description.', 'snippet.tags[]': 'Ruby code, interactive', 'snippet.default_language': '', 'status.privacy_status': 'private'}) ``` Apps Script ``` // Build an object from an object containing properties as key-value pairs function createResource(properties) { var res = {}; var normalizedProps = {}; for (var p in properties) { var value = properties[p]; if (p.substr(-2, 2) == '[]' && value) { var adjustedName = p.replace('[]', ''); normalizedProps[adjustedName] = value.split(','); } else { normalizedProps[p] = value; } } for (var p in normalizedProps) { if (normalizedProps.hasOwnProperty(p) && normalizedProps[p]) { var propArray = p.split('.'); var ref = res; for (var pa = 0; pa < propArray.length; pa++) { var key = propArray[pa]; if (pa == propArray.length - 1) { ref[key] = normalizedProps[p]; } else { ref = ref[key] = ref[key] || {}; } } }; } return res; } var resource = createResource({ 'snippet.title': 'Sample playlist ', 'snippet.description': 'This is a sample playlist description.', 'snippet.tags[]': 'Apps Script code, interactive', 'snippet.defaultLanguage': '', 'status.privacyStatus': 'private' }); ``` Go ``` func addPropertyToResource(ref map[string]interface{}, keys []string, value string, count int) map[string]interface{} { for k := count; k < (len(keys) - 1); k++ { switch val := ref[keys[k]].(type) { case map[string]interface{}: ref[keys[k]] = addPropertyToResource(val, keys, value, (k + 1)) case nil: next := make(map[string]interface{}) ref[keys[k]] = addPropertyToResource(next, keys, value, (k + 1)) } } // Only include properties that have values. if (count == len(keys) - 1 && value != "") { valueKey := keys[len(keys)-1] if valueKey[len(valueKey)-2:] == "[]" { ref[valueKey[0:len(valueKey)-2]] = strings.Split(value, ",") } else if len(valueKey) > 4 && valueKey[len(valueKey)-4:] == "|int" { ref[valueKey[0:len(valueKey)-4]], _ = strconv.Atoi(value) } else if value == "true" { ref[valueKey] = true } else if value == "false" { ref[valueKey] = false } else { ref[valueKey] = value } } return ref } func createResource(properties map[string]string) string { resource := make(map[string]interface{}) for key, value := range properties { keys := strings.Split(key, ".") ref := addPropertyToResource(resource, keys, value, 0) resource = ref } propJson, err := json.Marshal(resource) if err != nil { log.Fatal("cannot encode to JSON ", err) } return string(propJson) } func main() { properties := (map[string]string{ "snippet.title": "Sample playlist ", "snippet.description": "This is a sample playlist description.", "snippet.tags[]": "Go code, interactive", "snippet.defaultLanguage": "", "status.privacyStatus": "private", }) res := createResource(properties) ``` ### Load existing resources To test a request to update an existing resource, you can load the current property values for that resource into the update form. For example, to update metadata about a video, enter the video ID in the `id` property field and click the **Load resource** button. The current property values load into the form and you can update just the values that you want to change. ![](https://developers.google.com/static/youtube/images/interactive-snippet-load-resource.png) --- # Source: https://developers.google.com/youtube/v3/code_samples/code_snippets.md.txt # Use Cases and Code Snippets This page lets you explore common use cases for the YouTube Data API and YouTube Live Streaming API. When you select a resource and method, the table below updates to display a list of common use cases, including a description of each use case, for that method. In addition: - You can click on a use case name to populate the API Explorer widget with sample parameter and property values for that use case. - You can click the code icon (![](https://developers.google.com/site-assets/platform-html-color.svg)) next to any sample name to open the fullscreen APIs Explorer and populate it with the sample values for that use case. The fullscreen APIs Explorer shows working code samples for Java, JavaScript, PHP, Python, and `curl`. |--------------|------------| | ### Resource | ### Method | --- # Source: https://developers.google.com/youtube/v3/code_samples/dotnet.md.txt # .NET Code Samples The following code samples, which use the [Google APIs Client Library for .NET](https://developers.google.com/api-client-library/dotnet), are available for the YouTube Data API. You can download these code samples from the `dotnet` folder of the [YouTube APIs code sample repository on GitHub](https://github.com/youtube/api-samples). ## Create a playlist The following code sample calls the API's `playlists.insert` method to create a private playlist owned by the channel authorizing the request. ```gdscript using System; using System.IO; using System.Reflection; using System.Threading; using System.Threading.Tasks; using Google.Apis.Auth.OAuth2; using Google.Apis.Services; using Google.Apis.Upload; using Google.Apis.Util.Store; using Google.Apis.YouTube.v3; using Google.Apis.YouTube.v3.Data; namespace Google.Apis.YouTube.Samples { /// /// YouTube Data API v3 sample: create a playlist. /// Relies on the Google APIs Client Library for .NET, v1.7.0 or higher. /// See https://developers.google.com/api-client-library/dotnet/get_started /// internal class PlaylistUpdates { [STAThread] static void Main(string[] args) { Console.WriteLine("YouTube Data API: Playlist Updates"); Console.WriteLine("=================================="); try { new PlaylistUpdates().Run().Wait(); } catch (AggregateException ex) { foreach (var e in ex.InnerExceptions) { Console.WriteLine("Error: " + e.Message); } } Console.WriteLine("Press any key to continue..."); Console.ReadKey(); } private async Task Run() { UserCredential credential; using (var stream = new FileStream("client_secrets.json", FileMode.Open, FileAccess.Read)) { credential = await GoogleWebAuthorizationBroker.AuthorizeAsync( GoogleClientSecrets.Load(stream).Secrets, // This OAuth 2.0 access scope allows for full read/write access to the // authenticated user's account. new[] { YouTubeService.Scope.Youtube }, "user", CancellationToken.None, new FileDataStore(this.GetType().ToString()) ); } var youtubeService = new YouTubeService(new BaseClientService.Initializer() { HttpClientInitializer = credential, ApplicationName = this.GetType().ToString() }); // Create a new, private playlist in the authorized user's channel. var newPlaylist = new Playlist(); newPlaylist.Snippet = new PlaylistSnippet(); newPlaylist.Snippet.Title = "Test Playlist"; newPlaylist.Snippet.Description = "A playlist created with the YouTube API v3"; newPlaylist.Status = new PlaylistStatus(); newPlaylist.Status.PrivacyStatus = "public"; newPlaylist = await youtubeService.Playlists.Insert(newPlaylist, "snippet,status").ExecuteAsync(); // Add a video to the newly created playlist. var newPlaylistItem = new PlaylistItem(); newPlaylistItem.Snippet = new PlaylistItemSnippet(); newPlaylistItem.Snippet.PlaylistId = newPlaylist.Id; newPlaylistItem.Snippet.ResourceId = new ResourceId(); newPlaylistItem.Snippet.ResourceId.Kind = "youtube#video"; newPlaylistItem.Snippet.ResourceId.VideoId = "GNRMeaz6QRI"; newPlaylistItem = await youtubeService.PlaylistItems.Insert(newPlaylistItem, "snippet").ExecuteAsync(); Console.WriteLine("Playlist item id {0} was added to playlist id {1}.", newPlaylistItem.Id, newPlaylist.Id); } } } https://github.com/youtube/api-samples/blob/07263305b59a7c3275bc7e925f9ce6cabf774022/dotnet/PlaylistUpdates.cs ``` ## Retrieve my uploads The following code sample calls the API's `playlistItems.list` method to retrieve a list of videos uploaded to the channel associated with the request. The code also calls the `channels.list` method with the `mine` parameter set to `true` to retrieve the playlist ID that identifies the channel's uploaded videos. ```gdscript using System; using System.IO; using System.Reflection; using System.Threading; using System.Threading.Tasks; using Google.Apis.Auth.OAuth2; using Google.Apis.Services; using Google.Apis.Upload; using Google.Apis.Util.Store; using Google.Apis.YouTube.v3; using Google.Apis.YouTube.v3.Data; namespace Google.Apis.YouTube.Samples { /// /// YouTube Data API v3 sample: retrieve my uploads. /// Relies on the Google APIs Client Library for .NET, v1.7.0 or higher. /// See https://developers.google.com/api-client-library/dotnet/get_started /// internal class MyUploads { [STAThread] static void Main(string[] args) { Console.WriteLine("YouTube Data API: My Uploads"); Console.WriteLine("============================"); try { new MyUploads().Run().Wait(); } catch (AggregateException ex) { foreach (var e in ex.InnerExceptions) { Console.WriteLine("Error: " + e.Message); } } Console.WriteLine("Press any key to continue..."); Console.ReadKey(); } private async Task Run() { UserCredential credential; using (var stream = new FileStream("client_secrets.json", FileMode.Open, FileAccess.Read)) { credential = await GoogleWebAuthorizationBroker.AuthorizeAsync( GoogleClientSecrets.Load(stream).Secrets, // This OAuth 2.0 access scope allows for read-only access to the authenticated // user's account, but not other types of account access. new[] { YouTubeService.Scope.YoutubeReadonly }, "user", CancellationToken.None, new FileDataStore(this.GetType().ToString()) ); } var youtubeService = new YouTubeService(new BaseClientService.Initializer() { HttpClientInitializer = credential, ApplicationName = this.GetType().ToString() }); var channelsListRequest = youtubeService.Channels.List("contentDetails"); channelsListRequest.Mine = true; // Retrieve the contentDetails part of the channel resource for the authenticated user's channel. var channelsListResponse = await channelsListRequest.ExecuteAsync(); foreach (var channel in channelsListResponse.Items) { // From the API response, extract the playlist ID that identifies the list // of videos uploaded to the authenticated user's channel. var uploadsListId = channel.ContentDetails.RelatedPlaylists.Uploads; Console.WriteLine("Videos in list {0}", uploadsListId); var nextPageToken = ""; while (nextPageToken != null) { var playlistItemsListRequest = youtubeService.PlaylistItems.List("snippet"); playlistItemsListRequest.PlaylistId = uploadsListId; playlistItemsListRequest.MaxResults = 50; playlistItemsListRequest.PageToken = nextPageToken; // Retrieve the list of videos uploaded to the authenticated user's channel. var playlistItemsListResponse = await playlistItemsListRequest.ExecuteAsync(); foreach (var playlistItem in playlistItemsListResponse.Items) { // Print information about each video. Console.WriteLine("{0} ({1})", playlistItem.Snippet.Title, playlistItem.Snippet.ResourceId.VideoId); } nextPageToken = playlistItemsListResponse.NextPageToken; } } } } } https://github.com/youtube/api-samples/blob/07263305b59a7c3275bc7e925f9ce6cabf774022/dotnet/MyUploads.cs ``` ## Search by keyword The following code sample calls the API's `search.list` method to retrieve search results associated with a particular keyword. ```gdscript using System; using System.Collections.Generic; using System.IO; using System.Reflection; using System.Threading; using System.Threading.Tasks; using Google.Apis.Auth.OAuth2; using Google.Apis.Services; using Google.Apis.Upload; using Google.Apis.Util.Store; using Google.Apis.YouTube.v3; using Google.Apis.YouTube.v3.Data; namespace Google.Apis.YouTube.Samples { /// /// YouTube Data API v3 sample: search by keyword. /// Relies on the Google APIs Client Library for .NET, v1.7.0 or higher. /// See https://developers.google.com/api-client-library/dotnet/get_started /// /// Set ApiKey to the API key value from the APIs & auth > Registered apps tab of /// https://cloud.google.com/console /// Please ensure that you have enabled the YouTube Data API for your project. /// internal class Search { [STAThread] static void Main(string[] args) { Console.WriteLine("YouTube Data API: Search"); Console.WriteLine("========================"); try { new Search().Run().Wait(); } catch (AggregateException ex) { foreach (var e in ex.InnerExceptions) { Console.WriteLine("Error: " + e.Message); } } Console.WriteLine("Press any key to continue..."); Console.ReadKey(); } private async Task Run() { var youtubeService = new YouTubeService(new BaseClientService.Initializer() { ApiKey = "REPLACE_ME", ApplicationName = this.GetType().ToString() }); var searchListRequest = youtubeService.Search.List("snippet"); searchListRequest.Q = "Google"; // Replace with your search term. searchListRequest.MaxResults = 50; // Call the search.list method to retrieve results matching the specified query term. var searchListResponse = await searchListRequest.ExecuteAsync(); List videos = new List(); List channels = new List(); List playlists = new List(); // Add each result to the appropriate list, and then display the lists of // matching videos, channels, and playlists. foreach (var searchResult in searchListResponse.Items) { switch (searchResult.Id.Kind) { case "youtube#video": videos.Add(String.Format("{0} ({1})", searchResult.Snippet.Title, searchResult.Id.VideoId)); break; case "youtube#channel": channels.Add(String.Format("{0} ({1})", searchResult.Snippet.Title, searchResult.Id.ChannelId)); break; case "youtube#playlist": playlists.Add(String.Format("{0} ({1})", searchResult.Snippet.Title, searchResult.Id.PlaylistId)); break; } } Console.WriteLine(String.Format("Videos:\n{0}\n", string.Join("\n", videos))); Console.WriteLine(String.Format("Channels:\n{0}\n", string.Join("\n", channels))); Console.WriteLine(String.Format("Playlists:\n{0}\n", string.Join("\n", playlists))); } } } https://github.com/youtube/api-samples/blob/07263305b59a7c3275bc7e925f9ce6cabf774022/dotnet/Search.cs ``` ## Upload a video The following code sample calls the API's `videos.insert` method to upload a video to the channel associated with the request. ```objective-c using System; using System.IO; using System.Reflection; using System.Threading; using System.Threading.Tasks; using Google.Apis.Auth.OAuth2; using Google.Apis.Services; using Google.Apis.Upload; using Google.Apis.Util.Store; using Google.Apis.YouTube.v3; using Google.Apis.YouTube.v3.Data; namespace Google.Apis.YouTube.Samples { /// /// YouTube Data API v3 sample: upload a video. /// Relies on the Google APIs Client Library for .NET, v1.7.0 or higher. /// See https://developers.google.com/api-client-library/dotnet/get_started /// internal class UploadVideo { [STAThread] static void Main(string[] args) { Console.WriteLine("YouTube Data API: Upload Video"); Console.WriteLine("=============================="); try { new UploadVideo().Run().Wait(); } catch (AggregateException ex) { foreach (var e in ex.InnerExceptions) { Console.WriteLine("Error: " + e.Message); } } Console.WriteLine("Press any key to continue..."); Console.ReadKey(); } private async Task Run() { UserCredential credential; using (var stream = new FileStream("client_secrets.json", FileMode.Open, FileAccess.Read)) { credential = await GoogleWebAuthorizationBroker.AuthorizeAsync( GoogleClientSecrets.Load(stream).Secrets, // This OAuth 2.0 access scope allows an application to upload files to the // authenticated user's YouTube channel, but doesn't allow other types of access. new[] { YouTubeService.Scope.YoutubeUpload }, "user", CancellationToken.None ); } var youtubeService = new YouTubeService(new BaseClientService.Initializer() { HttpClientInitializer = credential, ApplicationName = Assembly.GetExecutingAssembly().GetName().Name }); var video = new Video(); video.Snippet = new VideoSnippet(); video.Snippet.Title = "Default Video Title"; video.Snippet.Description = "Default Video Description"; video.Snippet.Tags = new string[] { "tag1", "tag2" }; video.Snippet.CategoryId = "22"; // See https://developers.google.com/youtube/v3/docs/videoCategories/list video.Status = new VideoStatus(); video.Status.PrivacyStatus = "unlisted"; // or "private" or "public" var filePath = @"REPLACE_ME.mp4"; // Replace with path to actual movie file. using (var fileStream = new FileStream(filePath, FileMode.Open)) { var videosInsertRequest = youtubeService.Videos.Insert(video, "snippet,status", fileStream, "video/*"); videosInsertRequest.ProgressChanged += videosInsertRequest_ProgressChanged; videosInsertRequest.ResponseReceived += videosInsertRequest_ResponseReceived; await videosInsertRequest.UploadAsync(); } } void videosInsertRequest_ProgressChanged(Google.Apis.Upload.IUploadProgress progress) { switch (progress.Status) { case UploadStatus.Uploading: Console.WriteLine("{0} bytes sent.", progress.BytesSent); break; case UploadStatus.Failed: Console.WriteLine("An error prevented the upload from completing.\n{0}", progress.Exception); break; } } void videosInsertRequest_ResponseReceived(Video video) { Console.WriteLine("Video id '{0}' was successfully uploaded.", video.Id); } } } https://github.com/youtube/api-samples/blob/07263305b59a7c3275bc7e925f9ce6cabf774022/dotnet/UploadVideo.cs ``` --- # Source: https://developers.google.com/youtube/v3/code_samples/go.md.txt # Go Code Samples The following code samples, which use the [Google APIs Client Library for Go](https://github.com/google/google-api-go-client), are available for the YouTube Data API. You can download these code samples from the `go` folder of the [YouTube APIs code sample repository on GitHub](https://github.com/youtube/api-samples). ## Authorize a request This code sample performs OAuth 2.0 authorization by checking for the presence of a local file that contains authorization credentials. If the file is not present, the script opens a browser and waits for a response, then saves the returned credentials locally. ```go package main import ( "encoding/json" "fmt" "io/ioutil" "log" "net" "net/http" "net/url" "os" "os/exec" "os/user" "path/filepath" "runtime" "golang.org/x/net/context" "golang.org/x/oauth2" "golang.org/x/oauth2/google" ) // This variable indicates whether the script should launch a web server to // initiate the authorization flow or just display the URL in the terminal // window. Note the following instructions based on this setting: // * launchWebServer = true // 1. Use OAuth2 credentials for a web application // 2. Define authorized redirect URIs for the credential in the Google APIs // Console and set the RedirectURL property on the config object to one // of those redirect URIs. For example: // config.RedirectURL = "http://localhost:8090" // 3. In the startWebServer function below, update the URL in this line // to match the redirect URI you selected: // listener, err := net.Listen("tcp", "localhost:8090") // The redirect URI identifies the URI to which the user is sent after // completing the authorization flow. The listener then captures the // authorization code in the URL and passes it back to this script. // * launchWebServer = false // 1. Use OAuth2 credentials for an installed application. (When choosing // the application type for the OAuth2 client ID, select "Other".) // 2. Set the redirect URI to "urn:ietf:wg:oauth:2.0:oob", like this: // config.RedirectURL = "urn:ietf:wg:oauth:2.0:oob" // 3. When running the script, complete the auth flow. Then copy the // authorization code from the browser and enter it on the command line. const launchWebServer = false const missingClientSecretsMessage = ` Please configure OAuth 2.0 To make this sample run, you need to populate the client_secrets.json file found at: %v with information from the {{ Google Cloud Console }} {{ https://cloud.google.com/console }} For more information about the client_secrets.json file format, please visit: https://developers.google.com/api-client-library/python/guide/aaa_client_secrets ` // getClient uses a Context and Config to retrieve a Token // then generate a Client. It returns the generated Client. func getClient(scope string) *http.Client { ctx := context.Background() b, err := ioutil.ReadFile("client_secret.json") if err != nil { log.Fatalf("Unable to read client secret file: %v", err) } // If modifying the scope, delete your previously saved credentials // at ~/.credentials/youtube-go.json config, err := google.ConfigFromJSON(b, scope) if err != nil { log.Fatalf("Unable to parse client secret file to config: %v", err) } // Use a redirect URI like this for a web app. The redirect URI must be a // valid one for your OAuth2 credentials. config.RedirectURL = "http://localhost:8090" // Use the following redirect URI if launchWebServer=false in oauth2.go // config.RedirectURL = "urn:ietf:wg:oauth:2.0:oob" cacheFile, err := tokenCacheFile() if err != nil { log.Fatalf("Unable to get path to cached credential file. %v", err) } tok, err := tokenFromFile(cacheFile) if err != nil { authURL := config.AuthCodeURL("state-token", oauth2.AccessTypeOffline) if launchWebServer { fmt.Println("Trying to get token from web") tok, err = getTokenFromWeb(config, authURL) } else { fmt.Println("Trying to get token from prompt") tok, err = getTokenFromPrompt(config, authURL) } if err == nil { saveToken(cacheFile, tok) } } return config.Client(ctx, tok) } // startWebServer starts a web server that listens on http://localhost:8080. // The webserver waits for an oauth code in the three-legged auth flow. func startWebServer() (codeCh chan string, err error) { listener, err := net.Listen("tcp", "localhost:8090") if err != nil { return nil, err } codeCh = make(chan string) go http.Serve(listener, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { code := r.FormValue("code") codeCh <- code // send code to OAuth flow listener.Close() w.Header().Set("Content-Type", "text/plain") fmt.Fprintf(w, "Received code: %v\r\nYou can now safely close this browser window.", code) })) return codeCh, nil } // openURL opens a browser window to the specified location. // This code originally appeared at: // http://stackoverflow.com/questions/10377243/how-can-i-launch-a-process-that-is-not-a-file-in-go func openURL(url string) error { var err error switch runtime.GOOS { case "linux": err = exec.Command("xdg-open", url).Start() case "windows": err = exec.Command("rundll32", "url.dll,FileProtocolHandler", "http://localhost:4001/").Start() case "darwin": err = exec.Command("open", url).Start() default: err = fmt.Errorf("Cannot open URL %s on this platform", url) } return err } // Exchange the authorization code for an access token func exchangeToken(config *oauth2.Config, code string) (*oauth2.Token, error) { tok, err := config.Exchange(oauth2.NoContext, code) if err != nil { log.Fatalf("Unable to retrieve token %v", err) } return tok, nil } // getTokenFromPrompt uses Config to request a Token and prompts the user // to enter the token on the command line. It returns the retrieved Token. func getTokenFromPrompt(config *oauth2.Config, authURL string) (*oauth2.Token, error) { var code string fmt.Printf("Go to the following link in your browser. After completing " + "the authorization flow, enter the authorization code on the command " + "line: \n%v\n", authURL) if _, err := fmt.Scan(&code); err != nil { log.Fatalf("Unable to read authorization code %v", err) } fmt.Println(authURL) return exchangeToken(config, code) } // getTokenFromWeb uses Config to request a Token. // It returns the retrieved Token. func getTokenFromWeb(config *oauth2.Config, authURL string) (*oauth2.Token, error) { codeCh, err := startWebServer() if err != nil { fmt.Printf("Unable to start a web server.") return nil, err } err = openURL(authURL) if err != nil { log.Fatalf("Unable to open authorization URL in web server: %v", err) } else { fmt.Println("Your browser has been opened to an authorization URL.", " This program will resume once authorization has been provided.\n") fmt.Println(authURL) } // Wait for the web server to get the code. code := <-codeCh return exchangeToken(config, code) } // tokenCacheFile generates credential file path/filename. // It returns the generated credential path/filename. func tokenCacheFile() (string, error) { usr, err := user.Current() if err != nil { return "", err } tokenCacheDir := filepath.Join(usr.HomeDir, ".credentials") os.MkdirAll(tokenCacheDir, 0700) return filepath.Join(tokenCacheDir, url.QueryEscape("youtube-go.json")), err } // tokenFromFile retrieves a Token from a given file path. // It returns the retrieved Token and any read error encountered. func tokenFromFile(file string) (*oauth2.Token, error) { f, err := os.Open(file) if err != nil { return nil, err } t := &oauth2.Token{} err = json.NewDecoder(f).Decode(t) defer f.Close() return t, err } // saveToken uses a file path to create a file and store the // token in it. func saveToken(file string, token *oauth2.Token) { fmt.Println("trying to save token") fmt.Printf("Saving credential file to: %s\n", file) f, err := os.OpenFile(file, os.O_RDWR|os.O_CREATE|os.O_TRUNC, 0600) if err != nil { log.Fatalf("Unable to cache oauth token: %v", err) } defer f.Close() json.NewEncoder(f).Encode(token) } https://github.com/youtube/api-samples/blob/07263305b59a7c3275bc7e925f9ce6cabf774022/go/oauth2.go ``` ## List playlists This code sample calls the API's `playlists.list` method. Use command-line flags to define the parameters you want to use in the request as shown in the following examples: ``` # Retrieve playlists for a specified channel go run playlists.go oauth.go errors.go --channelId=UC_x5XG1OV2P6uZZ5FSM9Ttw # Retrieve authenticated user's playlists go run playlists.go oauth.go errors.go --mine=true ``` ```go package main import ( "flag" "fmt" "log" "google.golang.org/api/youtube/v3" ) var ( method = flag.String("method", "list", "The API method to execute. (List is the only method that this sample currently supports.") channelId = flag.String("channelId", "", "Retrieve playlists for this channel. Value is a YouTube channel ID.") hl = flag.String("hl", "", "Retrieve localized resource metadata for the specified application language.") maxResults = flag.Int64("maxResults", 5, "The maximum number of playlist resources to include in the API response.") mine = flag.Bool("mine", false, "List playlists for authenticated user's channel. Default: false.") onBehalfOfContentOwner = flag.String("onBehalfOfContentOwner", "", "Indicates that the request's auth credentials identify a user authorized to act on behalf of the specified content owner.") pageToken = flag.String("pageToken", "", "Token that identifies a specific page in the result set that should be returned.") part = flag.String("part", "snippet", "Comma-separated list of playlist resource parts that API response will include.") playlistId = flag.String("playlistId", "", "Retrieve information about this playlist.") ) func playlistsList(service *youtube.Service, part string, channelId string, hl string, maxResults int64, mine bool, onBehalfOfContentOwner string, pageToken string, playlistId string) *youtube.PlaylistListResponse { call := service.Playlists.List(part) if channelId != "" { call = call.ChannelId(channelId) } if hl != "" { call = call.Hl(hl) } call = call.MaxResults(maxResults) if mine != false { call = call.Mine(true) } if onBehalfOfContentOwner != "" { call = call.OnBehalfOfContentOwner(onBehalfOfContentOwner) } if pageToken != "" { call = call.PageToken(pageToken) } if playlistId != "" { call = call.Id(playlistId) } response, err := call.Do() handleError(err, "") return response } func main() { flag.Parse() if *channelId == "" && *mine == false && *playlistId == "" { log.Fatalf("You must either set a value for the channelId or playlistId flag or set the mine flag to 'true'.") } client := getClient(youtube.YoutubeReadonlyScope) service, err := youtube.New(client) if err != nil { log.Fatalf("Error creating YouTube client: %v", err) } response := playlistsList(service, "snippet,contentDetails", *channelId, *hl, *maxResults, *mine, *onBehalfOfContentOwner, *pageToken, *playlistId) for _, playlist := range response.Items { playlistId := playlist.Id playlistTitle := playlist.Snippet.Title // Print the playlist ID and title for the playlist resource. fmt.Println(playlistId, ": ", playlistTitle) } } https://github.com/youtube/api-samples/blob/07263305b59a7c3275bc7e925f9ce6cabf774022/go/playlists.go ``` ## Retrieve my uploads This code sample calls the API's `playlistItems.list` method to retrieve a list of videos uploaded to the channel associated with the request. The code also calls the `channels.list` method with the `mine` parameter set to `true` to retrieve the playlist ID that identifies the channel's uploaded videos. ```go package main import ( "fmt" "log" "google.golang.org/api/youtube/v3" ) // Retrieve playlistItems in the specified playlist func playlistItemsList(service *youtube.Service, part string, playlistId string, pageToken string) *youtube.PlaylistItemListResponse { call := service.PlaylistItems.List(part) call = call.PlaylistId(playlistId) if pageToken != "" { call = call.PageToken(pageToken) } response, err := call.Do() handleError(err, "") return response } // Retrieve resource for the authenticated user's channel func channelsListMine(service *youtube.Service, part string) *youtube.ChannelListResponse { call := service.Channels.List(part) call = call.Mine(true) response, err := call.Do() handleError(err, "") return response } func main() { client := getClient(youtube.YoutubeReadonlyScope) service, err := youtube.New(client) if err != nil { log.Fatalf("Error creating YouTube client: %v", err) } response := channelsListMine(service, "contentDetails") for _, channel := range response.Items { playlistId := channel.ContentDetails.RelatedPlaylists.Uploads // Print the playlist ID for the list of uploaded videos. fmt.Printf("Videos in list %s\r\n", playlistId) nextPageToken := "" for { // Retrieve next set of items in the playlist. playlistResponse := playlistItemsList(service, "snippet", playlistId, nextPageToken) for _, playlistItem := range playlistResponse.Items { title := playlistItem.Snippet.Title videoId := playlistItem.Snippet.ResourceId.VideoId fmt.Printf("%v, (%v)\r\n", title, videoId) } // Set the token to retrieve the next page of results // or exit the loop if all results have been retrieved. nextPageToken = playlistResponse.NextPageToken if nextPageToken == "" { break } fmt.Println() } } } https://github.com/youtube/api-samples/blob/07263305b59a7c3275bc7e925f9ce6cabf774022/go/my_uploads.go ``` ## Search by keyword This code sample calls the API's `search.list` method to retrieve search results associated with a particular keyword. ```go package main import ( "flag" "fmt" "log" "net/http" "google.golang.org/api/googleapi/transport" "google.golang.org/api/youtube/v3" ) var ( query = flag.String("query", "Google", "Search term") maxResults = flag.Int64("max-results", 25, "Max YouTube results") ) const developerKey = "YOUR DEVELOPER KEY" func main() { flag.Parse() client := &http.Client{ Transport: &transport.APIKey{Key: developerKey}, } service, err := youtube.New(client) if err != nil { log.Fatalf("Error creating new YouTube client: %v", err) } // Make the API call to YouTube. call := service.Search.List("id,snippet"). Q(*query). MaxResults(*maxResults) response, err := call.Do() handleError(err, "") // Group video, channel, and playlist results in separate lists. videos := make(map[string]string) channels := make(map[string]string) playlists := make(map[string]string) // Iterate through each item and add it to the correct list. for _, item := range response.Items { switch item.Id.Kind { case "youtube#video": videos[item.Id.VideoId] = item.Snippet.Title case "youtube#channel": channels[item.Id.ChannelId] = item.Snippet.Title case "youtube#playlist": playlists[item.Id.PlaylistId] = item.Snippet.Title } } printIDs("Videos", videos) printIDs("Channels", channels) printIDs("Playlists", playlists) } // Print the ID and title of each result in a list as well as a name that // identifies the list. For example, print the word section name "Videos" // above a list of video search results, followed by the video ID and title // of each matching video. func printIDs(sectionName string, matches map[string]string) { fmt.Printf("%v:\n", sectionName) for id, title := range matches { fmt.Printf("[%v] %v\n", id, title) } fmt.Printf("\n\n") } https://github.com/youtube/api-samples/blob/07263305b59a7c3275bc7e925f9ce6cabf774022/go/search_by_keyword.go ``` ## Upload a video This code sample calls the API's `videos.insert` method to upload a video to the channel associated with the request. ```go package main import ( "flag" "fmt" "log" "os" "strings" "google.golang.org/api/youtube/v3" ) var ( filename = flag.String("filename", "", "Name of video file to upload") title = flag.String("title", "Test Title", "Video title") description = flag.String("description", "Test Description", "Video description") category = flag.String("category", "22", "Video category") keywords = flag.String("keywords", "", "Comma separated list of video keywords") privacy = flag.String("privacy", "unlisted", "Video privacy status") ) func main() { flag.Parse() if *filename == "" { log.Fatalf("You must provide a filename of a video file to upload") } client := getClient(youtube.YoutubeUploadScope) service, err := youtube.New(client) if err != nil { log.Fatalf("Error creating YouTube client: %v", err) } upload := &youtube.Video{ Snippet: &youtube.VideoSnippet{ Title: *title, Description: *description, CategoryId: *category, }, Status: &youtube.VideoStatus{PrivacyStatus: *privacy}, } // The API returns a 400 Bad Request response if tags is an empty string. if strings.Trim(*keywords, "") != "" { upload.Snippet.Tags = strings.Split(*keywords, ",") } call := service.Videos.Insert("snippet,status", upload) file, err := os.Open(*filename) defer file.Close() if err != nil { log.Fatalf("Error opening %v: %v", *filename, err) } response, err := call.Media(file).Do() handleError(err, "") fmt.Printf("Upload successful! Video ID: %v\n", response.Id) } https://github.com/youtube/api-samples/blob/07263305b59a7c3275bc7e925f9ce6cabf774022/go/upload_video.go ``` --- # Source: https://developers.google.com/youtube/v3/code_samples/python_appengine.md.txt # Python on App Engine Code Samples The following Python code samples demonstrate how to use App Engine to make YouTube Data API (v3) calls. You can download these code samples from the [Google App Engine Python code sample repositories on GitHub](https://github.com/youtube/api-samples/tree/master/python_appengine). ## Prerequisites You must set up a project in the [Google API Console](https://console.cloud.google.com/) and get an API key to be able to run the code samples below. Currently, each project defines an `API_KEY` variable that is set to the value `REPLACE_ME`. You need to replace that value with your own API key to be able to run the samples. **Important:** To be able to run all of these examples, you must enable the YouTube Data API (v3) and the Freebase API for the project associated with your API key. If your application accesses private user or channel data, you will also need an OAuth 2.0 client ID. See instructions for creating an API key and getting your OAuth 2.0 client ID. ### Create your project and get authorization credentials 1. Open the [Credentials page](https://console.cloud.google.com/apis/credentials) in the API Console. 2. This API supports two types of credentials. Create whichever credentials are appropriate for your project: - **OAuth 2.0:** Whenever your application requests private user data, it must send an OAuth 2.0 token along with the request. Your application first sends a client ID and, possibly, a client secret to obtain a token. You can generate OAuth 2.0 credentials for web applications, service accounts, or installed applications. For more information, see the [OAuth 2.0 documentation](https://developers.google.com/identity/protocols/OAuth2). - **API keys:** A request that does not provide an OAuth 2.0 token must send an API key. The key identifies your project and provides API access, quota, and reports. The API supports several types of restrictions on API keys. If the API key that you need doesn't already exist, then create an API key in the Console by clicking **[Create credentials](https://console.cloud.google.com/apis/credentials) \> API key** . You can restrict the key before using it in production by clicking **Restrict key** and selecting one of the **Restrictions**. To keep your API keys secure, follow the [best practices for securely using API keys](https://cloud.google.com/docs/authentication/api-keys). ## Code samples ### Search by keyword The code sample below calls the API's `search.list` method to retrieve search results associated with a particular keyword. ```python import os import urllib import webapp2 import jinja2 from apiclient.discovery import build from optparse import OptionParser JINJA_ENVIRONMENT = jinja2.Environment( loader=jinja2.FileSystemLoader(os.path.dirname(__file__)), extensions=['jinja2.ext.autoescape']) # Set DEVELOPER_KEY to the "API key" value from the Google Developers Console: # https://console.developers.google.com/project/_/apiui/credential # Please ensure that you have enabled the YouTube Data API for your project. DEVELOPER_KEY = "REPLACE_ME" YOUTUBE_API_SERVICE_NAME = "youtube" YOUTUBE_API_VERSION = "v3" class MainHandler(webapp2.RequestHandler): def get(self): if DEVELOPER_KEY == "REPLACE_ME": self.response.write("""You must set up a project and get an API key to run this project. Please visit to do so.""" else: youtube = build( YOUTUBE_API_SERVICE_NAME, YOUTUBE_API_VERSION, developerKey=DEVELOPER_KEY) search_response = youtube.search().list( q="Hello", part="id,snippet", maxResults=5 ).execute() videos = [] channels = [] playlists = [] for search_result in search_response.get("items", []): if search_result["id"]["kind"] == "youtube#video": videos.append("%s (%s)" % (search_result["snippet"]["title"], search_result["id"]["videoId"])) elif search_result["id"]["kind"] == "youtube#channel": channels.append("%s (%s)" % (search_result["snippet"]["title"], search_result["id"]["channelId"])) elif search_result["id"]["kind"] == "youtube#playlist": playlists.append("%s (%s)" % (search_result["snippet"]["title"], search_result["id"]["playlistId"])) template_values = { 'videos': videos, 'channels': channels, 'playlists': playlists } self.response.headers['Content-type'] = 'text/plain' template = JINJA_ENVIRONMENT.get_template('index.html') self.response.write(template.render(template_values)) app = webapp2.WSGIApplication([ ('/.*', MainHandler), ], debug=True) ``` ### Search by topic The code sample below calls the API's `search.list` method to retrieve search results associated with a particular Freebase topic. ```python import os import urllib import webapp2 import jinja2 from apiclient.discovery import build from optparse import OptionParser import json JINJA_ENVIRONMENT = jinja2.Environment( loader=jinja2.FileSystemLoader(os.path.dirname(__file__)), extensions=['jinja2.ext.autoescape']) REGISTRATION_INSTRUCTIONS = """ You must set up a project and get an API key to run this code. Please see the instructions for creating a project and a key at https://developers.google.com/youtube/registering_an_application.

Make sure that you have enabled the YouTube Data API (v3) and the Freebase API for your project.""" # Set API_KEY to the "API key" value from the Google Developers Console: # https://console.developers.google.com/project/_/apiui/credential # Please ensure that you have enabled the YouTube Data API and Freebase API # for your project. API_KEY = "REPLACE_ME" YOUTUBE_API_SERVICE_NAME = "youtube" YOUTUBE_API_VERSION = "v3" FREEBASE_SEARCH_URL = "https://www.googleapis.com/freebase/v1/search?%s" QUERY_TERM = "dog" class MainHandler(webapp2.RequestHandler): def get(self): if API_KEY == 'REPLACE_ME': self.response.write(REGISTRATION_INSTRUCTIONS) else: # Present a list of Freebase topic IDs for the query term self.list_topics(QUERY_TERM) def list_topics(self, QUERY_TERM): # Retrieve a list of Freebase topics associated with the query term freebase_params = dict(query=QUERY_TERM, key=API_KEY) freebase_url = FREEBASE_SEARCH_URL % urllib.urlencode(freebase_params) freebase_response = json.loads(urllib.urlopen(freebase_url).read()) if len(freebase_response["result"]) == 0: exit("No matching terms were found in Freebase.") # Create a page that shows a select box listing the topics. # When the user selects a topic and submits the form, the # 'post' method below will handle the form submission and # retrieve videos for the selected topic. select_topic_page = ('''

The following topics were found:

''' # Display the HTML page listing the topic choices. self.response.out.write(select_topic_page) def post(self): topic_id = self.request.get('topic') # Service for calling the YouTube API youtube = build(YOUTUBE_API_SERVICE_NAME, YOUTUBE_API_VERSION, developerKey=API_KEY) # Execute the search request using default query term and retrieved topic. search_response = youtube.search().list( part = 'id,snippet', type = 'video', topicId = topic_id ).execute() videos = [] for search_result in search_response.get("items", []): videos.append(search_result) template_values = { 'videos': videos } self.response.headers['Content-type'] = 'text/html' template = JINJA_ENVIRONMENT.get_template('index.html') self.response.write(template.render(template_values)) app = webapp2.WSGIApplication([ ('/.*', MainHandler), ], debug=True) ``` ### Retrieve a channel's uploads The code sample below calls the API's `playlistItems.list` method to retrieve a list of videos uploaded to a specified channel. The channel can be identified by its channel ID or channel name. The code also calls the `channels.list` method to retrieve the playlist ID that identifies the channel's uploaded videos. ```python import os import urllib import webapp2 import jinja2 from apiclient.discovery import build from optparse import OptionParser import json JINJA_ENVIRONMENT = jinja2.Environment( loader=jinja2.FileSystemLoader(os.path.dirname(__file__)), extensions=['jinja2.ext.autoescape']) REGISTRATION_INSTRUCTIONS = """ You must set up a project and get an API key to run this code. Please see the instructions for creating a project and a key at https://developers.google.com/youtube/registering_an_application.

Make sure that you have enabled the YouTube Data API (v3) and the Freebase API for your project.""" # Set API_KEY to the "API key" value from the Google Developers Console: # https://console.developers.google.com/project/_/apiui/credential # Please ensure that you have enabled the YouTube Data API and Freebase API # for your project. API_KEY = "REPLACE_ME" YOUTUBE_API_SERVICE_NAME = "youtube" YOUTUBE_API_VERSION = "v3" FREEBASE_SEARCH_URL = "https://www.googleapis.com/freebase/v1/search?%s" QUERY_TERM = "dog" class MainHandler(webapp2.RequestHandler): def get(self): if API_KEY == 'REPLACE_ME': self.response.write(REGISTRATION_INSTRUCTIONS) else: # Present a list of Freebase topic IDs for the query term self.request_channel() def request_channel(self): # Display a text box where the user can enter a channel name or # channel ID. select_channel_page = '''

Which channel's videos do you want to see?

  

''' # Display the HTML page that shows the form. self.response.out.write(select_channel_page) def post(self): # Service for calling the YouTube API youtube = build(YOUTUBE_API_SERVICE_NAME, YOUTUBE_API_VERSION, developerKey=API_KEY) # Use form inputs to create request params for channel details channel_type = self.request.get('channel_type') channels_response = None if channel_type == 'id': channels_response = youtube.channels().list( id=self.request.get('channel'), part='snippet,contentDetails' ).execute() else: channels_response = youtube.channels().list( forUsername=self.request.get('channel'), part='snippet,contentDetails' ).execute() channel_name = '' videos = [] for channel in channels_response['items']: uploads_list_id = channel['contentDetails']['relatedPlaylists']['uploads'] channel_name = channel['snippet']['title'] next_page_token = '' while next_page_token is not None: playlistitems_response = youtube.playlistItems().list( playlistId=uploads_list_id, part='snippet', maxResults=50, pageToken=next_page_token ).execute() for playlist_item in playlistitems_response['items']: videos.append(playlist_item) next_page_token = playlistitems_response.get('tokenPagination', {}).get( 'nextPageToken') if len(videos) > 100: break template_values = { 'channel_name': channel_name, 'videos': videos } self.response.headers['Content-type'] = 'text/html' template = JINJA_ENVIRONMENT.get_template('index.html') self.response.write(template.render(template_values)) app = webapp2.WSGIApplication([ ('/.*', MainHandler), ], debug=True) ``` --- # Source: https://developers.google.com/youtube/v3/code_samples/ruby.md.txt # Ruby Code Samples The following code samples, which use the [Google APIs Client Library for Ruby](https://developers.google.com/api-client-library/ruby), are available for the YouTube Data API. You can download these code samples from the `ruby` folder of the [YouTube APIs code sample repository on GitHub](https://github.com/youtube/api-samples). ## Add a channel subscription This sample calls the API's `subscriptions.insert` method to add a subscription to a specified channel. ```ruby #!/usr/bin/ruby require 'rubygems' gem 'google-api-client', '>0.7' require 'google/api_client' require 'google/api_client/client_secrets' require 'google/api_client/auth/file_storage' require 'google/api_client/auth/installed_app' require 'trollop' # This OAuth 2.0 access scope allows for full read/write access to the # authenticated user's account. YOUTUBE_SCOPE = 'https://www.googleapis.com/auth/youtube' YOUTUBE_API_SERVICE_NAME = 'youtube' YOUTUBE_API_VERSION = 'v3' def get_authenticated_service client = Google::APIClient.new( :application_name => $PROGRAM_NAME, :application_version => '1.0.0' ) youtube = client.discovered_api(YOUTUBE_API_SERVICE_NAME, YOUTUBE_API_VERSION) file_storage = Google::APIClient::FileStorage.new("#{$PROGRAM_NAME}-oauth2.json") if file_storage.authorization.nil? client_secrets = Google::APIClient::ClientSecrets.load flow = Google::APIClient::InstalledAppFlow.new( :client_id => client_secrets.client_id, :client_secret => client_secrets.client_secret, :scope => [YOUTUBE_SCOPE] ) client.authorization = flow.authorize(file_storage) else client.authorization = file_storage.authorization end return client, youtube end def main opts = Trollop::options do opt :channel_id, 'ID of the channel to subscribe to.', :type => String, :default => 'UCtVd0c0tGXuTSbU5d8cSBUg' end client, youtube = get_authenticated_service begin body = { :snippet => { :resourceId => { :channelId => opts[:channel_id] } } } # Call the API's youtube.subscriptions.insert method to add the subscription # to the specified channel. subscriptions_response = client.execute!( :api_method => youtube.subscriptions.insert, :parameters => { :part => body.keys.join(',') }, :body_object => body ) puts "A subscription to '#{subscriptions_response.data.snippet.title}' was added." rescue Google::APIClient::TransmissionError => e puts e.result.body end end main https://github.com/youtube/api-samples/blob/07263305b59a7c3275bc7e925f9ce6cabf774022/ruby/add_subscription.rb ``` ## Authorize a request The following code sample performs OAuth 2.0 authorization by checking for the presence of a local file that contains authorization credentials. If the file is not present, the script opens a browser and waits for a response, then saves the returned credentials locally. ```ruby require 'google/api_client' require 'google/api_client/client_secrets' require 'json' require 'launchy' require 'thin' RESPONSE_HTML = < OAuth 2 Flow Complete You have successfully completed the OAuth 2 flow. Please close this browser window and return to your program. stop FILE_POSTFIX = '-oauth2.json' # Small helper for the sample apps for performing OAuth 2.0 flows from the command # line. Starts an embedded server to handle redirects. class CommandLineOAuthHelper def initialize(scope) credentials = Google::APIClient::ClientSecrets.load @authorization = Signet::OAuth2::Client.new( :authorization_uri => credentials.authorization_uri, :token_credential_uri => credentials.token_credential_uri, :client_id => credentials.client_id, :client_secret => credentials.client_secret, :redirect_uri => credentials.redirect_uris.first, :scope => scope ) end # Request authorization. Checks to see if a local file with credentials is present, and uses that. # Otherwise, opens a browser and waits for response, then saves the credentials locally. def authorize credentialsFile = $0 + FILE_POSTFIX if File.exist? credentialsFile File.open(credentialsFile, 'r') do |file| credentials = JSON.load(file) @authorization.access_token = credentials['access_token'] @authorization.client_id = credentials['client_id'] @authorization.client_secret = credentials['client_secret'] @authorization.refresh_token = credentials['refresh_token'] @authorization.expires_in = (Time.parse(credentials['token_expiry']) - Time.now).ceil if @authorization.expired? @authorization.fetch_access_token! save(credentialsFile) end end else auth = @authorization url = @authorization.authorization_uri().to_s server = Thin::Server.new('0.0.0.0', 8080) do run lambda { |env| # Exchange the auth code & quit req = Rack::Request.new(env) auth.code = req['code'] auth.fetch_access_token! server.stop() [200, {'Content-Type' => 'text/html'}, RESPONSE_HTML] } end Launchy.open(url) server.start() save(credentialsFile) end return @authorization end def save(credentialsFile) File.open(credentialsFile, 'w', 0600) do |file| json = JSON.dump({ :access_token => @authorization.access_token, :client_id => @authorization.client_id, :client_secret => @authorization.client_secret, :refresh_token => @authorization.refresh_token, :token_expiry => @authorization.expires_at }) file.write(json) end end end https://github.com/youtube/api-samples/blob/07263305b59a7c3275bc7e925f9ce6cabf774022/ruby/oauth/oauth_util.rb ``` ## Retrieve my uploads This sample calls the API's `playlistItems.list` method to retrieve a list of videos uploaded to the channel associated with the request. The code also calls the `channels.list` method with the `mine` parameter set to `true` to retrieve the playlist ID that identifies the channel's uploaded videos. ```ruby #!/usr/bin/ruby require 'rubygems' gem 'google-api-client', '>0.7' require 'google/api_client' require 'google/api_client/client_secrets' require 'google/api_client/auth/file_storage' require 'google/api_client/auth/installed_app' # This OAuth 2.0 access scope allows for read-only access to the authenticated # user's account, but not other types of account access. YOUTUBE_READONLY_SCOPE = 'https://www.googleapis.com/auth/youtube.readonly' YOUTUBE_API_SERVICE_NAME = 'youtube' YOUTUBE_API_VERSION = 'v3' def get_authenticated_service client = Google::APIClient.new( :application_name => $PROGRAM_NAME, :application_version => '1.0.0' ) youtube = client.discovered_api(YOUTUBE_API_SERVICE_NAME, YOUTUBE_API_VERSION) file_storage = Google::APIClient::FileStorage.new("#{$PROGRAM_NAME}-oauth2.json") if file_storage.authorization.nil? client_secrets = Google::APIClient::ClientSecrets.load flow = Google::APIClient::InstalledAppFlow.new( :client_id => client_secrets.client_id, :client_secret => client_secrets.client_secret, :scope => [YOUTUBE_READONLY_SCOPE] ) client.authorization = flow.authorize(file_storage) else client.authorization = file_storage.authorization end return client, youtube end def main client, youtube = get_authenticated_service begin # Retrieve the "contentDetails" part of the channel resource for the # authenticated user's channel. channels_response = client.execute!( :api_method => youtube.channels.list, :parameters => { :mine => true, :part => 'contentDetails' } ) channels_response.data.items.each do |channel| # From the API response, extract the playlist ID that identifies the list # of videos uploaded to the authenticated user's channel. uploads_list_id = channel['contentDetails']['relatedPlaylists']['uploads'] # Retrieve the list of videos uploaded to the authenticated user's channel. next_page_token = '' until next_page_token.nil? playlistitems_response = client.execute!( :api_method => youtube.playlist_items.list, :parameters => { :playlistId => uploads_list_id, :part => 'snippet', :maxResults => 50, :pageToken => next_page_token } ) puts "Videos in list #{uploads_list_id}" # Print information about each video. playlistitems_response.data.items.each do |playlist_item| title = playlist_item['snippet']['title'] video_id = playlist_item['snippet']['resourceId']['videoId'] puts "#{title} (#{video_id})" end next_page_token = playlistitems_response.next_page_token end puts end rescue Google::APIClient::TransmissionError => e puts e.result.body end end main https://github.com/youtube/api-samples/blob/07263305b59a7c3275bc7e925f9ce6cabf774022/ruby/my_uploads.rb ``` ## Search by keyword This sample calls the API's `search.list` method to retrieve search results associated with a particular keyword. ```ruby #!/usr/bin/ruby require 'rubygems' gem 'google-api-client', '>0.7' require 'google/api_client' require 'trollop' # Set DEVELOPER_KEY to the API key value from the APIs & auth > Credentials # tab of # {{ Google Cloud Console }} <{{ https://cloud.google.com/console }}> # Please ensure that you have enabled the YouTube Data API for your project. DEVELOPER_KEY = 'REPLACE_ME' YOUTUBE_API_SERVICE_NAME = 'youtube' YOUTUBE_API_VERSION = 'v3' def get_service client = Google::APIClient.new( :key => DEVELOPER_KEY, :authorization => nil, :application_name => $PROGRAM_NAME, :application_version => '1.0.0' ) youtube = client.discovered_api(YOUTUBE_API_SERVICE_NAME, YOUTUBE_API_VERSION) return client, youtube end def main opts = Trollop::options do opt :q, 'Search term', :type => String, :default => 'Google' opt :max_results, 'Max results', :type => :int, :default => 25 end client, youtube = get_service begin # Call the search.list method to retrieve results matching the specified # query term. search_response = client.execute!( :api_method => youtube.search.list, :parameters => { :part => 'snippet', :q => opts[:q], :maxResults => opts[:max_results] } ) videos = [] channels = [] playlists = [] # Add each result to the appropriate list, and then display the lists of # matching videos, channels, and playlists. search_response.data.items.each do |search_result| case search_result.id.kind when 'youtube#video' videos << "#{search_result.snippet.title} (#{search_result.id.videoId})" when 'youtube#channel' channels << "#{search_result.snippet.title} (#{search_result.id.channelId})" when 'youtube#playlist' playlists << "#{search_result.snippet.title} (#{search_result.id.playlistId})" end end puts "Videos:\n", videos, "\n" puts "Channels:\n", channels, "\n" puts "Playlists:\n", playlists, "\n" rescue Google::APIClient::TransmissionError => e puts e.result.body end end main https://github.com/youtube/api-samples/blob/07263305b59a7c3275bc7e925f9ce6cabf774022/ruby/search.rb ``` ## Upload a video This sample calls the API's `videos.insert` method to upload a video to the channel associated with the request. ```ruby #!/usr/bin/ruby require 'rubygems' gem 'google-api-client', '>0.7' require 'google/api_client' require 'google/api_client/client_secrets' require 'google/api_client/auth/file_storage' require 'google/api_client/auth/installed_app' require 'trollop' # A limited OAuth 2 access scope that allows for uploading files, but not other # types of account access. YOUTUBE_UPLOAD_SCOPE = 'https://www.googleapis.com/auth/youtube.upload' YOUTUBE_API_SERVICE_NAME = 'youtube' YOUTUBE_API_VERSION = 'v3' def get_authenticated_service client = Google::APIClient.new( :application_name => $PROGRAM_NAME, :application_version => '1.0.0' ) youtube = client.discovered_api(YOUTUBE_API_SERVICE_NAME, YOUTUBE_API_VERSION) file_storage = Google::APIClient::FileStorage.new("#{$PROGRAM_NAME}-oauth2.json") if file_storage.authorization.nil? client_secrets = Google::APIClient::ClientSecrets.load flow = Google::APIClient::InstalledAppFlow.new( :client_id => client_secrets.client_id, :client_secret => client_secrets.client_secret, :scope => [YOUTUBE_UPLOAD_SCOPE] ) client.authorization = flow.authorize(file_storage) else client.authorization = file_storage.authorization end return client, youtube end def main opts = Trollop::options do opt :file, 'Video file to upload', :type => String opt :title, 'Video title', :default => 'Test Title', :type => String opt :description, 'Video description', :default => 'Test Description', :type => String opt :category_id, 'Numeric video category. See https://developers.google.com/youtube/v3/docs/videoCategories/list', :default => 22, :type => :int opt :keywords, 'Video keywords, comma-separated', :default => '', :type => String opt :privacy_status, 'Video privacy status: public, private, or unlisted', :default => 'public', :type => String end if opts[:file].nil? or not File.file?(opts[:file]) Trollop::die :file, 'does not exist' end client, youtube = get_authenticated_service begin body = { :snippet => { :title => opts[:title], :description => opts[:description], :tags => opts[:keywords].split(','), :categoryId => opts[:category_id], }, :status => { :privacyStatus => opts[:privacy_status] } } videos_insert_response = client.execute!( :api_method => youtube.videos.insert, :body_object => body, :media => Google::APIClient::UploadIO.new(opts[:file], 'video/*'), :parameters => { :uploadType => 'resumable', :part => body.keys.join(',') } ) videos_insert_response.resumable_upload.send_all(client) puts "Video id '#{videos_insert_response.data.id}' was successfully uploaded." rescue Google::APIClient::TransmissionError => e puts e.result.body end end main https://github.com/youtube/api-samples/blob/07263305b59a7c3275bc7e925f9ce6cabf774022/ruby/upload_video.rb ``` --- # Source: https://developers.google.com/youtube/v3/determine_quota_cost.md.txt # Quota Calculator The following table shows the quota cost for calling each API method. All API requests, including invalid requests, incur a quota cost of at least one point. Projects that enable the YouTube Data API have a default quota allocation of 10,000 units per day, an amount sufficient for the majority of our API users. You can see your quota usage on [Quotas](https://console.cloud.google.com/iam-admin/quotas) page in the Google API Console. Daily quotas reset at midnight Pacific Time (PT). The following two points are worth calling out as they both affect your quota usage: - If your application calls a method, such as `search.list`, that returns multiple pages of results, each request to retrieve an additional page of results incurs the estimated quota cost. - [YouTube Live Streaming API](https://developers.google.com/youtube/v3/live) methods are, technically, part of the YouTube Data API, and calls to those methods also incur quota costs. As such, API methods for live streaming are also listed in the table. | Quota costs ||| |-----------------------------|---------------------|------| | resource | method | cost | | ### activities | list | 1 | | ### captions | list | 50 | | | insert | 400 | | | update | 450 | | | delete | 50 | | ### channelBanners | insert | 50 | | ### channels | list | 1 | | | update | 50 | | ### channelSections | list | 1 | | | insert | 50 | | | update | 50 | | | delete | 50 | | ### comments | list | 1 | | | insert | 50 | | | update | 50 | | | setModerationStatus | 50 | | | delete | 50 | | ### commentThreads | list | 1 | | | insert | 50 | | | update | 50 | | ### guideCategories | list | 1 | | ### i18nLanguages | list | 1 | | ### i18nRegions | list | 1 | | ### members | list | 1 | | ### membershipsLevels | list | 1 | | ### playlistItems | list | 1 | | | insert | 50 | | | update | 50 | | | delete | 50 | | ### playlists | list | 1 | | | insert | 50 | | | update | 50 | | | delete | 50 | | ### search | list | 100 | | ### subscriptions | list | 1 | | | insert | 50 | | | delete | 50 | | ### thumbnails | set | 50 | | ### videoAbuseReportReasons | list | 1 | | ### videoCategories | list | 1 | | ### videos | list | 1 | | | insert | 1600 | | | update | 50 | | | rate | 50 | | | getRating | 1 | | | reportAbuse | 50 | | | delete | 50 | | ### watermarks | set | 50 | | | unset | 50 | --- # Source: https://developers.google.com/youtube/v3/docs.md.txt The YouTube Data API lets you incorporate functions normally executed on the YouTube website into your own website or application. The following sections 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. ## Call 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 [Developer Console's](https://console.developers.google.com/) **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 [authentication guide](https://developers.google.com/youtube/v3/guides/authentication). ## Resource types ### 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, 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](https://developers.google.com/youtube/v3/docs/activities#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/activities#properties). | Method | HTTP request | Description | |-----------------------------------------------------------------------|-------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | URIs relative to `https://www.googleapis.com/youtube/v3` ||| | [list](https://developers.google.com/youtube/v3/docs/activities/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 or with the user's own channel. | ### Captions A **caption** resource represents a YouTube caption track. A caption track is associated with exactly one YouTube video. For more information about this resource, see its [resource representation](https://developers.google.com/youtube/v3/docs/captions#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/captions#properties). | Method | HTTP request | Description | |-----------------------------------------------------------------------------|---------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | URIs relative to `https://www.googleapis.com/youtube/v3` ||| | [delete](https://developers.google.com/youtube/v3/docs/captions/delete) | `DELETE /captions` | Deletes the specified caption track. | | [download](https://developers.google.com/youtube/v3/docs/captions/download) | `GET /captions/`id | Downloads a caption track. The caption track is returned in its original format unless the request specifies a value for the `tfmt` parameter and in its original language unless the request specifies a value for the `tlang` parameter. | | [insert](https://developers.google.com/youtube/v3/docs/captions/insert) | `POST /captions` | Uploads a caption track. | | [list](https://developers.google.com/youtube/v3/docs/captions/list) | `GET /captions` | Returns a list of caption tracks that are associated with a specified video. The API response does not contain the actual captions and that the [captions.download](https://developers.google.com/youtube/v3/docs/captions/download) method provides the ability to retrieve a caption track. | | [update](https://developers.google.com/youtube/v3/docs/captions/update) | `PUT /captions` | Updates a caption track. When updating a caption track, you can change the track's [draft status](https://developers.google.com/youtube/v3/docs/captions#snippet.isDraft), upload a new caption file for the track, or both. | ### 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](https://developers.google.com/youtube/v3/docs/channelBanners#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/channelBanners#properties). | Method | HTTP request | Description | |-------------------------------------------------------------------------------|-------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | URIs relative to `https://www.googleapis.com/youtube/v3` ||| | [insert](https://developers.google.com/youtube/v3/docs/channelBanners/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 2048x1152 pixels. We recommend uploading a 2560px by 1440px image. 2. Extract the `url` property's value from the response that the API returns for step 1. 3. Call the [channels.update](https://developers.google.com/youtube/v3/docs/channels/update) method to update the channel's branding settings. Set the [brandingSettings.image.bannerExternalUrl](https://developers.google.com/youtube/v3/docs/channels#brandingSettings.image.bannerExternalUrl) property's value to the URL obtained in step 2. | ### ChannelSections A **channelSection** resource contains information about a set of videos that a channel has chosen to feature. For example, a section could feature a channel's latest uploads, most popular uploads, or videos from one or more playlists. A channel's sections are only visible if the channel displays content in a browse view (rather than a feed view). To enable a channel to display content in a browse view, set the [brandingSettings.channel.showBrowseView](https://developers.google.com/youtube/v3/docs/channels#brandingSettings.channel.showBrowseView) property to `true` for the specified channel. A channel can create a maximum of 10 shelves. For more information about this resource, see its [resource representation](https://developers.google.com/youtube/v3/docs/channelSections#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/channelSections#properties). | Method | HTTP request | Description | |--------------------------------------------------------------------------------|---------------------------|-----------------------------------------------------------------------------------------------------------| | URIs relative to `https://www.googleapis.com/youtube/v3` ||| | [delete](https://developers.google.com/youtube/v3/docs/channelSections/delete) | `DELETE /channelSections` | Deletes a channel section. | | [insert](https://developers.google.com/youtube/v3/docs/channelSections/insert) | `POST /channelSections` | Adds a channel section to the authenticated user's channel. A channel can create a maximum of 10 shelves. | | [list](https://developers.google.com/youtube/v3/docs/channelSections/list) | `GET /channelSections` | Returns a list of `channelSection` resources that match the API request criteria. | | [update](https://developers.google.com/youtube/v3/docs/channelSections/update) | `PUT /channelSections` | Updates a channel section. | ### Channels A **channel** resource contains information about a YouTube channel. For more information about this resource, see its [resource representation](https://developers.google.com/youtube/v3/docs/channels#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/channels#properties). | Method | HTTP request | Description | |-------------------------------------------------------------------------|-----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | URIs relative to `https://www.googleapis.com/youtube/v3` ||| | [list](https://developers.google.com/youtube/v3/docs/channels/list) | `GET /channels` | Returns a collection of zero or more **channel** resources that match the request criteria. | | [update](https://developers.google.com/youtube/v3/docs/channels/update) | `PUT /channels` | Updates a channel's metadata. This method only supports updates to the `channel` resource's `brandingSettings` and `invideoPromotion` objects and their child properties. | ### CommentThreads A **commentThread** resource contains information about a YouTube comment thread, which comprises a top-level comment and replies, if any exist, to that comment. A `commentThread` resource can represent comments about either a video or a channel. Both the top-level comment and the replies are actually [comment](https://developers.google.com/youtube/v3/docs/comments) resources nested inside the `commentThread` resource. The `commentThread` resource does not necessarily contain all replies to a comment, and you need to use the [comments.list](https://developers.google.com/youtube/v3/docs/comments/list) method if you want to retrieve all replies for a particular comment. Also, some comments don't have replies. For more information about this resource, see its [resource representation](https://developers.google.com/youtube/v3/docs/commentThreads#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/commentThreads#properties). | Method | HTTP request | Description | |-------------------------------------------------------------------------------|------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | URIs relative to `https://www.googleapis.com/youtube/v3` ||| | [list](https://developers.google.com/youtube/v3/docs/commentThreads/list) | `GET /commentThreads` | Returns a list of comment threads that match the API request parameters. | | [insert](https://developers.google.com/youtube/v3/docs/commentThreads/insert) | `POST /commentThreads` | Creates a new top-level comment. To add a reply to an existing comment, use the [comments.insert](https://developers.google.com/youtube/v3/docs/comments/insert) method instead. | ### Comments A **comment** resource contains information about a single YouTube comment. A `comment` resource can represent a comment about either a video or a channel. In addition, the comment could be a top-level comment or a reply to a top-level comment. For more information about this resource, see its [resource representation](https://developers.google.com/youtube/v3/docs/comments#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/comments#properties). | Method | HTTP request | Description | |---------------------------------------------------------------------------------------------------|--------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | URIs relative to `https://www.googleapis.com/youtube/v3` ||| | [list](https://developers.google.com/youtube/v3/docs/comments/list) | `GET /comments` | Returns a list of comments that match the API request parameters. | | [setModerationStatus](https://developers.google.com/youtube/v3/docs/comments/setModerationStatus) | `POST /comments/setModerationStatus` | Sets the moderation status of one or more comments. The API request must be authorized by the owner of the channel or video associated with the comments. | | [insert](https://developers.google.com/youtube/v3/docs/comments/insert) | `POST /comments` | Creates a reply to an existing comment. **Note:** To create a top-level comment, use the [commentThreads.insert](https://developers.google.com/youtube/v3/docs/commentThreads/insert) method. | | [delete](https://developers.google.com/youtube/v3/docs/comments/delete) | `DELETE /comments` | Deletes a comment. | | [update](https://developers.google.com/youtube/v3/docs/comments/update) | `PUT /comments` | Modifies a comment. | ### I18nLanguages An **i18nLanguage** resource identifies an application language that the YouTube website supports. The application language can also be referred to as a UI language. For the YouTube website, an application language could be automatically selected based on Google Account settings, browser language, or IP location. A user could also manually select the UI language from the YouTube site footer. Each `i18nLanguage` resource identifies a language code and a name. The language code can be used as the value of the `hl` parameter when calling API methods like `videoCategories.list`. For more information about this resource, see its [resource representation](https://developers.google.com/youtube/v3/docs/i18nLanguages#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/i18nLanguages#properties). | Method | HTTP request | Description | |--------------------------------------------------------------------------|----------------------|----------------------------------------------------------------------------| | URIs relative to `https://www.googleapis.com/youtube/v3` ||| | [list](https://developers.google.com/youtube/v3/docs/i18nLanguages/list) | `GET /i18nLanguages` | Returns a list of application languages that the YouTube website supports. | ### I18nRegions An **i18nRegion** resource identifies a geographic area that a YouTube user can select as the preferred content region. The content region can also be referred to as a content locale. For the YouTube website, a content region could be automatically selected based on heuristics like the YouTube domain or the user's IP location. A user could also manually select the content region from the YouTube site footer. Each `i18nRegion` resource identifies a region code and a name. The region code can be used as the value of the `regionCode` parameter when calling API methods like `search.list`, `videos.list`, `activities.list`, and `videoCategories.list`. For more information about this resource, see its [resource representation](https://developers.google.com/youtube/v3/docs/i18nRegions#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/i18nRegions#properties). | Method | HTTP request | Description | |------------------------------------------------------------------------|--------------------|----------------------------------------------------------------------| | URIs relative to `https://www.googleapis.com/youtube/v3` ||| | [list](https://developers.google.com/youtube/v3/docs/i18nRegions/list) | `GET /i18nRegions` | Returns a list of content regions that the YouTube website supports. | ### Members A **member** resource represents a channel member for a YouTube channel. A member provides recurring monetary support to a creator and receives special benefits. For example, members are able to chat when the creator turns on members-only mode for a chat. For more information about this resource, see its [resource representation](https://developers.google.com/youtube/v3/docs/members#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/members#properties). | Method | HTTP request | Description | |--------------------------------------------------------------------|----------------|----------------------------------------------------------------------------------------------------------------------| | URIs relative to `https://www.googleapis.com/youtube/v3` ||| | [list](https://developers.google.com/youtube/v3/docs/members/list) | `GET /members` | Lists members (formerly known as "sponsors") for a channel. The API request must be authorized by the channel owner. | ### MembershipsLevels A **membershipsLevel** resource identifies a pricing level for the creator that authorized the API request. For more information about this resource, see its [resource representation](https://developers.google.com/youtube/v3/docs/membershipsLevels#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/membershipsLevels#properties). | Method | HTTP request | Description | |------------------------------------------------------------------------------|--------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | URIs relative to `https://www.googleapis.com/youtube/v3` ||| | [list](https://developers.google.com/youtube/v3/docs/membershipsLevels/list) | `GET /membershipsLevels` | Returns a collection of zero or more **membershipsLevel** resources owned by the channel that authorized the API request. Levels are returned in implicit display order. | ### 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 resource](https://developers.google.com/youtube/v3/docs/channels) for a given channel. You can then use the [playlistItems.list](https://developers.google.com/youtube/v3/docs/playlistItems/list) method to the list. For more information about this resource, see its [resource representation](https://developers.google.com/youtube/v3/docs/playlistItems#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/playlistItems#properties). | Method | HTTP request | Description | |------------------------------------------------------------------------------|-------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | URIs relative to `https://www.googleapis.com/youtube/v3` ||| | [delete](https://developers.google.com/youtube/v3/docs/playlistItems/delete) | `DELETE /playlistItems` | Deletes a playlist item. | | [insert](https://developers.google.com/youtube/v3/docs/playlistItems/insert) | `POST /playlistItems` | Adds a resource to a playlist. | | [list](https://developers.google.com/youtube/v3/docs/playlistItems/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](https://developers.google.com/youtube/v3/docs/playlistItems/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. 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 - 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](https://developers.google.com/youtube/v3/docs/channels) for a given channel. You can then use the [playlistItems.list](https://developers.google.com/youtube/v3/docs/playlistItems/list) method to retrieve any of those lists. You can also add or remove items from those lists by calling the [playlistItems.insert](https://developers.google.com/youtube/v3/docs/playlistItems/insert) and [playlistItems.delete](https://developers.google.com/youtube/v3/docs/playlistItems/delete) methods. For more information about this resource, see its [resource representation](https://developers.google.com/youtube/v3/docs/playlists#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/playlists#properties). | Method | HTTP request | Description | |--------------------------------------------------------------------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | URIs relative to `https://www.googleapis.com/youtube/v3` ||| | [delete](https://developers.google.com/youtube/v3/docs/playlists/delete) | `DELETE /playlists` | Deletes a playlist. | | [list](https://developers.google.com/youtube/v3/docs/playlists/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](https://developers.google.com/youtube/v3/docs/playlists/insert) | `POST /playlists` | Creates a playlist. | | [update](https://developers.google.com/youtube/v3/docs/playlists/update) | `PUT /playlists` | Modifies a playlist. For example, you could change a playlist's title, description, or privacy status. | ### Search 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](https://developers.google.com/youtube/v3/docs/search#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/search#properties). | Method | HTTP request | Description | |-------------------------------------------------------------------|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | URIs relative to `https://www.googleapis.com/youtube/v3` ||| | [list](https://developers.google.com/youtube/v3/docs/search/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](https://developers.google.com/youtube/v3/docs/videos), [channel](https://developers.google.com/youtube/v3/docs/channels), and [playlist](https://developers.google.com/youtube/v3/docs/playlists) 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](https://developers.google.com/youtube/v3/docs/subscriptions#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/subscriptions#properties). | Method | HTTP request | Description | |------------------------------------------------------------------------------|-------------------------|---------------------------------------------------------------------| | URIs relative to `https://www.googleapis.com/youtube/v3` ||| | [delete](https://developers.google.com/youtube/v3/docs/subscriptions/delete) | `DELETE /subscriptions` | Deletes a subscription. | | [insert](https://developers.google.com/youtube/v3/docs/subscriptions/insert) | `POST /subscriptions` | Adds a subscription for the authenticated user's channel. | | [list](https://developers.google.com/youtube/v3/docs/subscriptions/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. 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](https://developers.google.com/youtube/v3/docs/thumbnails#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/thumbnails#properties). | Method | HTTP request | Description | |---------------------------------------------------------------------|------------------------|----------------------------------------------------------------------| | URIs relative to `https://www.googleapis.com/youtube/v3` ||| | [set](https://developers.google.com/youtube/v3/docs/thumbnails/set) | `POST /thumbnails/set` | Uploads a custom video thumbnail to YouTube and sets it for a video. | ### VideoAbuseReportReasons A **videoAbuseReportReason** resource contains information about a reason that a video would be flagged for containing abusive content. When your application calls the [videos.reportAbuse](https://developers.google.com/youtube/v3/docs/videos/reportAbuse) method to report an abusive video, the request uses the information from a `videoAbuseReportReason` resource to identify the reason that the video is being reported. For more information about this resource, see its [resource representation](https://developers.google.com/youtube/v3/docs/videoAbuseReportReasons#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/videoAbuseReportReasons#properties). | Method | HTTP request | Description | |------------------------------------------------------------------------------------|--------------------------------|-----------------------------------------------------------------------| | URIs relative to `https://www.googleapis.com/youtube/v3` ||| | [list](https://developers.google.com/youtube/v3/docs/videoAbuseReportReasons/list) | `GET /videoAbuseReportReasons` | Retrieve a list of reasons that can be used to report abusive videos. | ### 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](https://developers.google.com/youtube/v3/docs/videoCategories#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/videoCategories#properties). | Method | HTTP request | Description | |----------------------------------------------------------------------------|------------------------|--------------------------------------------------------------------------| | URIs relative to `https://www.googleapis.com/youtube/v3` ||| | [list](https://developers.google.com/youtube/v3/docs/videoCategories/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](https://developers.google.com/youtube/v3/docs/videos#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/videos#properties). | Method | HTTP request | Description | |---------------------------------------------------------------------------------|----------------------------|------------------------------------------------------------------------------------| | URIs relative to `https://www.googleapis.com/youtube/v3` ||| | [insert](https://developers.google.com/youtube/v3/docs/videos/insert) | `POST /videos` | Uploads a video to YouTube and optionally sets the video's metadata. | | [list](https://developers.google.com/youtube/v3/docs/videos/list) | `GET /videos` | Returns a list of videos that match the API request parameters. | | [delete](https://developers.google.com/youtube/v3/docs/videos/delete) | `DELETE /videos` | Deletes a YouTube video. | | [update](https://developers.google.com/youtube/v3/docs/videos/update) | `PUT /videos` | Updates a video's metadata. | | [rate](https://developers.google.com/youtube/v3/docs/videos/rate) | `POST /videos/rate` | Add a like or dislike rating to a video or remove a rating from a video. | | [getRating](https://developers.google.com/youtube/v3/docs/videos/getRating) | `GET /videos/getRating` | Retrieves the ratings that the authorized user gave to a list of specified videos. | | [reportAbuse](https://developers.google.com/youtube/v3/docs/videos/reportAbuse) | `POST /videos/reportAbuse` | Report a video for containing abusive content. | ### 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](https://developers.google.com/youtube/v3/docs/watermarks#resource) and list of [properties](https://developers.google.com/youtube/v3/docs/watermarks#properties). | Method | HTTP request | Description | |-------------------------------------------------------------------------|--------------------------|-----------------------------------------------------------------| | URIs relative to `https://www.googleapis.com/youtube/v3` ||| | [set](https://developers.google.com/youtube/v3/docs/watermarks/set) | `POST /watermarks/set` | Uploads a watermark image to YouTube and sets it for a channel. | | [unset](https://developers.google.com/youtube/v3/docs/watermarks/unset) | `POST /watermarks/unset` | Deletes a channel's watermark image. | --- # Source: https://developers.google.com/youtube/v3/docs/activities.md.txt 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, 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. ## Methods The API supports the following methods for `activities` resources: [list](https://developers.google.com/youtube/v3/docs/activities/list) : Returns a list of channel activity events that match the request criteria. For example, you can retrieve events associated with a particular channel or with the user's own channel. [Try it now](https://developers.google.com/youtube/v3/docs/activities/list#usage). ## Resource representation The following JSON structure shows the format of an `activities` resource: ```gdscript { "https://developers.google.com/youtube/v3/docs/activities#kind": "youtube#activity", "https://developers.google.com/youtube/v3/docs/activities#etag": etag, "https://developers.google.com/youtube/v3/docs/activities#id": string, "https://developers.google.com/youtube/v3/docs/activities#snippet": { "https://developers.google.com/youtube/v3/docs/activities#snippet.publishedAt": datetime, "https://developers.google.com/youtube/v3/docs/activities#snippet.channelId": string, "https://developers.google.com/youtube/v3/docs/activities#snippet.title": string, "https://developers.google.com/youtube/v3/docs/activities#snippet.description": string, "https://developers.google.com/youtube/v3/docs/activities#snippet.thumbnails": { (key): { "https://developers.google.com/youtube/v3/docs/activities#snippet.thumbnails.(key).url": string, "https://developers.google.com/youtube/v3/docs/activities#snippet.thumbnails.(key).width": unsigned integer, "https://developers.google.com/youtube/v3/docs/activities#snippet.thumbnails.(key).height": unsigned integer } }, "https://developers.google.com/youtube/v3/docs/activities#snippet.channelTitle": string, "https://developers.google.com/youtube/v3/docs/activities#snippet.type": string, "https://developers.google.com/youtube/v3/docs/activities#snippet.groupId": string }, "https://developers.google.com/youtube/v3/docs/activities#contentDetails": { "https://developers.google.com/youtube/v3/docs/activities#contentDetails.upload": { "https://developers.google.com/youtube/v3/docs/activities#contentDetails.upload.videoId": string }, "https://developers.google.com/youtube/v3/docs/activities#contentDetails.like": { "https://developers.google.com/youtube/v3/docs/activities#contentDetails.like.resourceId": { "https://developers.google.com/youtube/v3/docs/activities#contentDetails.like.resourceId.kind": string, "https://developers.google.com/youtube/v3/docs/activities#contentDetails.like.resourceId.videoId": string, } }, "https://developers.google.com/youtube/v3/docs/activities#contentDetails.favorite": { "https://developers.google.com/youtube/v3/docs/activities#contentDetails.favorite.resourceId": { "https://developers.google.com/youtube/v3/docs/activities#contentDetails.favorite.resourceId.kind": string, "https://developers.google.com/youtube/v3/docs/activities#contentDetails.favorite.resourceId.videoId": string, } }, "https://developers.google.com/youtube/v3/docs/activities#contentDetails.comment": { "https://developers.google.com/youtube/v3/docs/activities#contentDetails.comment.resourceId": { "https://developers.google.com/youtube/v3/docs/activities#contentDetails.comment.resourceId.kind": string, "https://developers.google.com/youtube/v3/docs/activities#contentDetails.comment.resourceId.videoId": string, "https://developers.google.com/youtube/v3/docs/activities#contentDetails.comment.resourceId.channelId": string, } }, "https://developers.google.com/youtube/v3/docs/activities#contentDetails.subscription": { "https://developers.google.com/youtube/v3/docs/activities#contentDetails.subscription.resourceId": { "https://developers.google.com/youtube/v3/docs/activities#contentDetails.subscription.resourceId.kind": string, "https://developers.google.com/youtube/v3/docs/activities#contentDetails.subscription.resourceId.channelId": string, } }, "https://developers.google.com/youtube/v3/docs/activities#contentDetails.playlistItem": { "https://developers.google.com/youtube/v3/docs/activities#contentDetails.playlistItem.resourceId": { "https://developers.google.com/youtube/v3/docs/activities#contentDetails.playlistItem.resourceId.kind": string, "https://developers.google.com/youtube/v3/docs/activities#contentDetails.playlistItem.resourceId.videoId": string, }, "https://developers.google.com/youtube/v3/docs/activities#contentDetails.playlistItem.playlistId": string, "https://developers.google.com/youtube/v3/docs/activities#contentDetails.playlistItem.playlistItemId": string }, "https://developers.google.com/youtube/v3/docs/activities#contentDetails.recommendation": { "https://developers.google.com/youtube/v3/docs/activities#contentDetails.recommendation.resourceId": { "https://developers.google.com/youtube/v3/docs/activities#contentDetails.recommendation.resourceId.kind": string, "https://developers.google.com/youtube/v3/docs/activities#contentDetails.recommendation.resourceId.videoId": string, "https://developers.google.com/youtube/v3/docs/activities#contentDetails.recommendation.resourceId.channelId": string, }, "https://developers.google.com/youtube/v3/docs/activities#contentDetails.recommendation.reason": string, "https://developers.google.com/youtube/v3/docs/activities#contentDetails.recommendation.seedResourceId": { "https://developers.google.com/youtube/v3/docs/activities#contentDetails.recommendation.seedResourceId.kind": string, "https://developers.google.com/youtube/v3/docs/activities#contentDetails.recommendation.seedResourceId.videoId": string, "https://developers.google.com/youtube/v3/docs/activities#contentDetails.recommendation.seedResourceId.channelId": string, "https://developers.google.com/youtube/v3/docs/activities#contentDetails.recommendation.seedResourceId.playlistId": string } }, "https://developers.google.com/youtube/v3/docs/activities#contentDetails.social": { "https://developers.google.com/youtube/v3/docs/activities#contentDetails.social.type": string, "https://developers.google.com/youtube/v3/docs/activities#contentDetails.social.resourceId": { "https://developers.google.com/youtube/v3/docs/activities#contentDetails.social.resourceId.kind": string, "https://developers.google.com/youtube/v3/docs/activities#contentDetails.social.resourceId.videoId": string, "https://developers.google.com/youtube/v3/docs/activities#contentDetails.social.resourceId.channelId": string, "https://developers.google.com/youtube/v3/docs/activities#contentDetails.social.resourceId.playlistId": string }, "https://developers.google.com/youtube/v3/docs/activities#contentDetails.social.author": string, "https://developers.google.com/youtube/v3/docs/activities#contentDetails.social.referenceUrl": string, "https://developers.google.com/youtube/v3/docs/activities#contentDetails.social.imageUrl": string }, "https://developers.google.com/youtube/v3/docs/activities#contentDetails.channelItem": { "https://developers.google.com/youtube/v3/docs/activities#contentDetails.channelItem.resourceId": { } }, } } ``` ### 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#activity`. | | `etag` | `etag` The Etag of this resource. | | `id` | `string` The ID that YouTube uses to uniquely identify the activity. | | `snippet` | `object` The `snippet` object contains basic details about the activity, including the activity's type and group ID. | | snippet.`publishedAt` | `datetime` The date and time that the activity occurred. 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 channel associated with the activity. | | snippet.`title` | `string` The title of the resource primarily associated with the activity. | | snippet.`description` | `string` The description of the resource primarily associated with the activity. | | snippet.`thumbnails` | `object` A map of thumbnail images associated with the resource that is primarily associated with the activity. 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` Channel title for the channel responsible for this activity | | snippet.`type` | `string` The type of activity that the resource describes. Valid values for this property are: - `channelItem` - `comment` -- (not currently returned) - `favorite` - `like` - `playlistItem` - `promotedItem` - `recommendation` - `social` - `subscription` - `upload` | | snippet.`groupId` | `string` The group ID associated with the activity. A group ID identifies user events that are associated with the same user and resource. For example, if a user rates a video and marks the same video as a favorite, the entries for those events would have the same group ID in the user's activity feed. In your user interface, you can avoid repetition by grouping events with the same `groupId` value. | | `contentDetails` | `object` The `contentDetails` object contains information about the content associated with the activity. For example, if the `snippet.type` value is `videoRated`, then the `contentDetails` object's content identifies the rated video. | | contentDetails.`upload` | `object` The `upload` object contains information about the uploaded video. This property is only present if the `snippet.type` is `upload`. | | contentDetails.upload.`videoId` | `string` The ID that YouTube uses to uniquely identify the uploaded video. | | contentDetails.`like` | `object` The `like` object contains information about a resource that received a positive (like) rating. This property is only present if the `snippet.type` is `like`. | | contentDetails.like.`resourceId` | `object` The `resourceId` object contains information that identifies the rated resource. | | contentDetails.like.resourceId.`kind` | `string` The type of the API resource. | | contentDetails.like.resourceId.`videoId` | `string` The ID that YouTube uses to uniquely identify the video, if the rated resource is a video. This property is only present if the `resourceId.kind` is `youtube#video`. | | contentDetails.`favorite` | `object` The `favorite` object contains information about a video that was marked as a favorite video. This property is only present if the `snippet.type` is `favorite`. | | contentDetails.favorite.`resourceId` | `object` The `resourceId` object contains information that identifies the resource that was marked as a favorite. | | contentDetails.favorite.resourceId.`kind` | `string` The type of the API resource. | | contentDetails.favorite.resourceId.`videoId` | `string` The ID that YouTube uses to uniquely identify the favorite video. This property is only present if the `resourceId.kind` is `youtube#video`. **Note:** The `activities.list` method does not currently return resources for new comments. | | contentDetails.`comment` | `object` The `comment` object contains information about a resource that received a comment. This property is only present if the `snippet.type` is `comment`. | | contentDetails.comment.`resourceId` | `object` The `resourceId` object contains information that identifies the resource associated with the comment. | | contentDetails.comment.resourceId.`kind` | `string` The type of the API resource. | | contentDetails.comment.resourceId.`videoId` | `string` The ID that YouTube uses to uniquely identify the video associated with a comment. This property is only present if the `resourceId.kind` is `youtube#video`. | | contentDetails.comment.resourceId.`channelId` | `string` The ID that YouTube uses to uniquely identify the channel associated with a comment. This property is only present if the `resourceId.kind` is `youtube#channel`. | | contentDetails.`subscription` | `object` The `subscription` object contains information about a channel that a user subscribed to. This property is only present if the `snippet.type` is `subscription`. | | contentDetails.subscription.`resourceId` | `object` The `resourceId` object contains information that identifies the resource that the user subscribed to. | | contentDetails.subscription.resourceId.`kind` | `string` The type of the API resource. | | contentDetails.subscription.resourceId.`channelId` | `string` The ID that YouTube uses to uniquely identify the channel that the user subscribed to. This property is only present if the `resourceId.kind` is `youtube#channel`. | | contentDetails.`playlistItem` | `object` The `playlistItem` object contains information about a new playlist item. This property is only present if the `snippet.type` is `playlistItem`. | | contentDetails.playlistItem.`resourceId` | `object` The `resourceId` object contains information that identifies the resource that was added to the playlist. | | contentDetails.playlistItem.resourceId.`kind` | `string` The type of the API resource. | | contentDetails.playlistItem.resourceId.`videoId` | `string` The ID that YouTube uses to uniquely identify the video that was added to the playlist. This property is only present if the `resourceId.kind` is `youtube#video`. | | contentDetails.playlistItem.`playlistId` | `string` The value that YouTube uses to uniquely identify the playlist. | | contentDetails.playlistItem.`playlistItemId` | `string` The value that YouTube uses to uniquely identify the item in the playlist. | | contentDetails.`recommendation` | `object` The `recommendation` object contains information about a recommended resource. This property is only present if the `snippet.type` is `recommendation`. | | contentDetails.recommendation.`resourceId` | `object` The `resourceId` object contains information that identifies the recommended resource. | | contentDetails.recommendation.resourceId.`kind` | `string` The type of the API resource. | | contentDetails.recommendation.resourceId.`videoId` | `string` The ID that YouTube uses to uniquely identify the video, if the recommended resource is a video. This property is only present if the `resourceId.kind` is `youtube#video`. | | contentDetails.recommendation.resourceId.`channelId` | `string` The ID that YouTube uses to uniquely identify the channel, if the recommended resource is a channel. This property is only present if the `resourceId.kind` is `youtube#channel`. | | contentDetails.recommendation.`reason` | `string` The reason that the resource is recommended to the user. Valid values for this property are: - `videoFavorited` - `videoLiked` - `videoWatched` | | contentDetails.recommendation.`seedResourceId` | `object` The `seedResourceId` object contains information about the resource that caused the recommendation. | | contentDetails.recommendation.seedResourceId.`kind` | `string` The type of the API resource. | | contentDetails.recommendation.seedResourceId.`videoId` | `string` The ID that YouTube uses to uniquely identify the video, if the recommendation was caused by a particular video. This property is only present if the `seedResourceId.kind` is `youtube#video`. | | contentDetails.recommendation.seedResourceId.`channelId` | `string` The ID that YouTube uses to uniquely identify the channel, if the recommendation was caused by a particular channel. This property is only present if the `seedResourceId.kind` is `youtube#channel`. | | contentDetails.recommendation.seedResourceId.`playlistId` | `string` The ID that YouTube uses to uniquely identify the playlist, if the recommendation was caused by a particular playlist. This property is only present if the `seedResourceId.kind` is `youtube#playlist`. | | contentDetails.`social` | `object` The `social` object contains details about a social network post. This property is only present if the `snippet.type` is `social`. | | contentDetails.social.`type` | `string` The name of the social network. Valid values for this property are: - `facebook` - `googlePlus` - `twitter` - `unspecified` | | contentDetails.social.`resourceId` | `object` The `resourceId` object encapsulates information that identifies the resource associated with a social network post. | | contentDetails.social.resourceId.`kind` | `string` The type of the API resource. | | contentDetails.social.resourceId.`videoId` | `string` The ID that YouTube uses to uniquely identify the video featured in a social network post, if the post refers to a video. This property will only be present if the value of the `social.resourceId.kind` property is `youtube#video`. | | contentDetails.social.resourceId.`channelId` | `string` The ID that YouTube uses to uniquely identify the channel featured in a social network post, if the post refers to a channel. This property will only be present if the value of the `social.resourceId.kind` property is `youtube#channel`. | | contentDetails.social.resourceId.`playlistId` | `string` The ID that YouTube uses to uniquely identify the playlist featured in a social network post, if the post refers to a playlist. This property will only be present if the value of the `social.resourceId.kind` property is `youtube#playlist`. | | contentDetails.social.`author` | `string` The author of the social network post. | | contentDetails.social.`referenceUrl` | `string` The URL of the social network post. | | contentDetails.social.`imageUrl` | `string` An image of the post's author. | | contentDetails.`channelItem` | `object` The `channelItem` object contains details about a resource that was added to a channel. This property is only present if the `snippet.type` is `channelItem`. | | contentDetails.channelItem.`resourceId` | `object` The `resourceId` object contains information that identifies the resource that was added to the channel. | --- # Source: https://developers.google.com/youtube/v3/docs/activities/insert.md.txt # Activities: insert **YouTube has deprecated the channel bulletin feature, and this method is no longer supported.** For more details, please see the [YouTube Help Center](https://support.google.com/youtube?p=channel-bulletins). 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()](https://developers.google.com/youtube/v3/docs/videos/rate) method to rate a video and the [playlistItems.insert()](https://developers.google.com/youtube/v3/docs/playlistItems/insert) method to mark a video as a favorite. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 50 units. ## Request ### HTTP request ``` POST https://www.googleapis.com/youtube/v3/activities ``` ### Authorization This request requires authorization with at least one of the following scopes ([read more about authentication and authorization](https://developers.google.com/youtube/v3/guides/authentication)). | Scope | |-----------------------------------------------------| | `https://www.googleapis.com/auth/youtube` | | `https://www.googleapis.com/auth/youtube.force-ssl` | ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters || |--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---| | **Required parameters** ||| | `part` | `string` The **part** parameter serves two purposes in this operation. It identifies the properties that the write operation will set as well as the properties that the API response will include. The following list contains the `part` names that you can include in the parameter value: - `contentDetails` - `id` - `snippet` | ### Request body Provide an [activity resource](https://developers.google.com/youtube/v3/docs/activities#resource) in the request body. For that resource: - You must specify a value for these properties: - `snippet.description` - You can set values for these properties: - `snippet.description` - `contentDetails.bulletin.resourceId` ## Response If successful, this method returns an [activity resource](https://developers.google.com/youtube/v3/docs/activities#resource) in the response body. ## Errors The following table identifies error messages that the API could return in response to a call to this method. Please see the [error message](https://developers.google.com/youtube/v3/docs/errors) documentation for more detail. | Error type | Error detail | Description | |-------------------------------|------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `bulletinTextRequired` | The request must use the `snippet` object's `description` property to provide the text for the bulletin post. | | `badRequest (400)` | `invalidMetadata` | The `kind` property does not match the type of ID provided. | | `forbidden (403)` | `forbidden` | The request is not properly authorized. | | `notFound (404)` | `playlistNotFound` | YouTube cannot find the video that you are trying to associate with the bulletin post. Check the value of the `contentDetails.bulletinPosted.playlistId` property. | | `notFound (404)` | `videoNotFound` | YouTube cannot find the video that you are trying to associate with the bulletin post. Check the value of the `contentDetails.bulletinPosted.videoId` property. | | `userRateLimitExceeded (403)` | `rateLimitExceeded` | The request cannot be completed because you have exceeded your [quota](https://developers.google.com/youtube/v3/getting-started#quota). | --- # Source: https://developers.google.com/youtube/v3/docs/activities/list.md.txt # Activities: list YouTube has deprecated the channel bulletin feature. The `activities.list` method does not still return channel bulletins, and the [activities.insert](https://developers.google.com/youtube/v3/docs/activities/insert) method is no longer supported. For more details, please see the [YouTube Help Center](https://support.google.com/youtube?p=channel-bulletins). Returns a list of channel activity events that match the request criteria. For example, you can retrieve events associated with a particular channel or with the user's own channel. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 1 unit. ## Common use cases The list below shows common use cases for this method. Hover over a use case to see its description, or click on a use case to load sample parameter values in the APIs Explorer. You can open the [fullscreen APIs Explorer](https://developers.google.com/youtube/v3/docs/activities/list#) to see code samples that dynamically update to reflect the parameter values entered in the Explorer. The table below shows common use cases for this method. You can click on a use case name to load sample parameter values in the APIs Explorer. Or you can see code samples for a use case in the fullscreen APIs Explorer by clicking on the code icon below a use case name. In the fullscreen UI, you can update parameter and property values and the code samples will dynamically update to reflect the values you enter. This method has one common use case, which is described below. The buttons below the description populate the APIs Explorer with sample values or open the fullscreen APIs Explorer to show code samples that use those values. The code samples also dynamically update if you change the values.
## Request ### HTTP request ``` GET https://www.googleapis.com/youtube/v3/activities ``` ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters || |-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---| | **Required parameters** ||| | `part` | `string` The **part** parameter specifies a comma-separated list of one or more `activity` resource properties that the API response will include. If the parameter identifies a property that contains child properties, the child properties will be included in the response. For example, in an `activity` resource, the `snippet` property contains other properties that identify the type of activity, a display title for the activity, and so forth. If you set **part=snippet**, the API response will also contain all of those nested properties. The following list contains the `part` names that you can include in the parameter value: - `contentDetails` - `id` - `snippet` | | **Filters (specify exactly one of the following parameters)** ||| | `channelId` | `string` The **channelId** parameter specifies a unique YouTube channel ID. The API will then return a list of that channel's activities. | | `home` | `boolean` **Note:** This parameter has been deprecated. For requests that set this parameter, the API response contains items similar to those that a logged-out user would see on the YouTube home page. Note that this parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication). | | `mine` | `boolean` This parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication). Set this parameter's value to `true` to retrieve a feed of the authenticated user's activities. | | **Optional parameters** ||| | `maxResults` | `unsigned integer` The **maxResults** parameter specifies the maximum number of items that should be returned in the result set. Acceptable values are `0` to `50`, inclusive. The default value is `5`. | | `pageToken` | `string` The **pageToken** parameter identifies a specific page in the result set that should be returned. In an API response, the `nextPageToken` and `prevPageToken` properties identify other pages that could be retrieved. | | `publishedAfter` | `datetime` The **publishedAfter** parameter specifies the earliest date and time that an activity could have occurred for that activity to be included in the API response. If the parameter value specifies a day, but not a time, then any activities that occurred that day will be included in the result set. The value is specified in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) (`YYYY-MM-DDThh:mm:ss.sZ`) format. | | `publishedBefore` | `datetime` The **publishedBefore** parameter specifies the date and time before which an activity must have occurred for that activity to be included in the API response. If the parameter value specifies a day, but not a time, then any activities that occurred that day will be excluded from the result set. The value is specified in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) (`YYYY-MM-DDThh:mm:ss.sZ`) format. | | `regionCode` | `string` The **regionCode** parameter instructs the API to return results for the specified country. The parameter value is an [ISO 3166-1 alpha-2](http://www.iso.org/iso/country_codes/iso_3166_code_lists/country_names_and_code_elements.htm) country code. YouTube uses this value when the authorized user's previous activity on YouTube does not provide enough information to generate the activity feed. | ### Request body Do not provide a request body when calling this method. ## Response If successful, this method returns a response body with the following structure: ```objective-c { "kind": "youtube#activityListResponse", "etag": etag, "nextPageToken": string, "prevPageToken": string, "pageInfo": { "totalResults": integer, "resultsPerPage": integer }, "items": [ activity Resource ] } ``` ### 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#activityListResponse`. | | `etag` | `etag` The Etag of this resource. | | `nextPageToken` | `string` The token that can be used as the value of the `pageToken` parameter to retrieve the next page in the result set. | | `prevPageToken` | `string` The token that can be used as the value of the `pageToken` parameter to retrieve the previous page in the result set. | | `pageInfo` | `object` The `pageInfo` object encapsulates paging information for the result set. | | pageInfo.`totalResults` | `integer` The total number of results in the result set. | | pageInfo.`resultsPerPage` | `integer` The number of results included in the API response. | | `items[]` | `list` A list of activities, or events, that match the request criteria. | ## Errors The following table identifies error messages that the API could return in response to a call to this method. Please see the [error message](https://developers.google.com/youtube/v3/docs/errors) documentation for more detail. | Error type | Error detail | Description | |----------------------|---------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `forbidden (403)` | `forbidden` | The request is not properly authorized. | | `forbidden (403)` | `homeParameterDeprecated` | The user's home page activity data is not available through this API. This error might occur if you set the `home` parameter to `true` in an unauthorized request. | | `notFound (404)` | `channelNotFound` | The channel ID identified by the request's `channelId` parameter cannot be found. | | `notFound (404)` | `homeChannelNotFound` | A YouTube home page feed cannot be found for the currently authenticated user. | | `unauthorized (401)` | `authorizationRequired` | The request uses the `home` parameter but is not properly authorized. | ## Try it! Use the APIs Explorer to call this API and see the API request and response. --- # Source: https://developers.google.com/youtube/v3/docs/captions.md.txt # Captions **Note:** On March 13, 2024, YouTube announced that it is deprecating the `sync` parameter for the [captions.insert](https://developers.google.com/youtube/v3/docs/captions/insert) and [captions.update](https://developers.google.com/youtube/v3/docs/captions/insert) API endpoints. Captions auto-syncing is still available in YouTube Creator Studio. See the [API revision history](https://developers.google.com/youtube/v3/revision_history#release_notes_03_13_2024) for more details. A **caption** resource represents a YouTube caption track. A caption track is associated with exactly one YouTube video. ## Methods The API supports the following methods for `captions` resources: [list](https://developers.google.com/youtube/v3/docs/captions/list) : Retrieve a list of caption tracks that are associated with a specified video. Note that the API response does not contain the actual captions and that the [captions.download](https://developers.google.com/youtube/v3/docs/captions/download) method provides the ability to retrieve a caption track. [Try it now](https://developers.google.com/youtube/v3/docs/captions/list#usage). [insert](https://developers.google.com/youtube/v3/docs/captions/insert) : Upload a caption track. [Try it now](https://developers.google.com/youtube/v3/docs/captions/insert). [update](https://developers.google.com/youtube/v3/docs/captions/update) : Update a caption track. When updating a caption track, you can change the track's [draft status](https://developers.google.com/youtube/v3/docs/captions#snippet.isDraft), upload a new caption file for the track, or both. [Try it now](https://developers.google.com/youtube/v3/docs/captions/update). [download](https://developers.google.com/youtube/v3/docs/captions/download) : Download a caption track. The caption track is returned to its original format unless the request specifies a value for the `tfmt` parameter and to its original language unless the request specifies a value for the `tlang` parameter. [Try it now](https://developers.google.com/youtube/v3/docs/captions/download). [delete](https://developers.google.com/youtube/v3/docs/captions/delete) : Delete a specified caption track. [Try it now](https://developers.google.com/youtube/v3/docs/captions/delete). ## Resource representation The following JSON structure shows the format of a `captions` resource: ```text { "kind": "youtube#caption", "etag": etag, "id": string, "snippet": { "videoId": string, "lastUpdated": datetime, "trackKind": string, "language": string, "name": string, "audioTrackType": string, "isCC": boolean, "isLarge": boolean, "isEasyReader": boolean, "isDraft": boolean, "isAutoSynced": boolean, "status": string, "failureReason": 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#caption`. | | `etag` | `etag` The Etag of this resource. | | `id` | `string` The ID that YouTube uses to uniquely identify the caption track. | | `snippet` | `object` The `snippet` object contains basic details about the caption. | | snippet.`videoId` | `string` The ID that YouTube uses to uniquely identify the video associated with the caption track. | | snippet.`lastUpdated` | `datetime` The date and time when the caption track was last updated. The value is specified in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format. | | snippet.`trackKind` | `string` The caption track's type. Valid values for this property are: - `ASR` -- A caption track generated using automatic speech recognition. - `forced` -- A caption track that plays when no other track is selected in the player. For example, a video that shows aliens speaking in an alien language might have a forced caption track to only show subtitles for the alien language. - `standard` -- A regular caption track. This is the default value. | | snippet.`language` | `string` The language of the caption track. The property value is a [BCP-47](http://www.rfc-editor.org/rfc/bcp/bcp47.txt) language tag. | | snippet.`name` | `string` The name of the caption track. The name is intended to be visible to the user as an option during playback. The maximum name length supported is 150 characters. | | snippet.`audioTrackType` | `string` The type of audio track associated with the caption track. Valid values for this property are: - `commentary` -- The caption track corresponds to an alternate audio track that includes commentary, such as directory commentary. - `descriptive` -- The caption track corresponds to an alternate audio track that includes additional descriptive audio. - `primary` -- The caption track corresponds to the primary audio track for the video, which is the audio track normally associated with the video. - `unknown` -- This is the default value. | | snippet.`isCC` | `boolean` Indicates whether the track contains closed captions for the deaf and hard of hearing. The default value is `false`. | | snippet.`isLarge` | `boolean` Indicates whether the caption track uses large text for the vision-impaired. The default value is `false`. | | snippet.`isEasyReader` | `boolean` Indicates whether caption track is formatted for "easy reader," meaning it is at a third-grade level for language learners. The default value is `false`. | | snippet.`isDraft` | `boolean` Indicates whether the caption track is a draft. If the value is `true`, then the track is not publicly visible. The default value is `false`. | | snippet.`isAutoSynced` | `boolean` Indicates whether YouTube synchronized the caption track to the audio track in the video. The value will be `true` if a sync was explicitly requested when the caption track was uploaded. For example, when calling the `captions.insert` or `captions.update` methods, you can set the `sync` parameter to `true` to instruct YouTube to sync the uploaded track to the video. If the value is `false`, YouTube uses the time codes in the uploaded caption track to determine when to display captions. | | snippet.`status` | `string` The caption track's status. Valid values for this property are: - `failed` - `serving` - `syncing` | | snippet.`failureReason` | `string` The reason that YouTube failed to process the caption track. This property is only present if the [state](https://developers.google.com/youtube/v3/docs/captions#state) property's value is `failed`. Valid values for this property are: - `processingFailed` -- YouTube failed to process the uploaded caption track. - `unknownFormat` -- The caption track's format was not recognized. - `unsupportedFormat` -- The caption track's format is not supported. | --- # Source: https://developers.google.com/youtube/v3/docs/captions/delete.md.txt # Captions: delete Deletes a specified caption track. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 50 units. ## Common use cases The list below shows common use cases for this method. Hover over a use case to see its description, or click on a use case to load sample parameter values in the APIs Explorer. You can open the [fullscreen APIs Explorer](https://developers.google.com/youtube/v3/docs/captions/delete#) to see code samples that dynamically update to reflect the parameter values entered in the Explorer. The table below shows common use cases for this method. You can click on a use case name to load sample parameter values in the APIs Explorer. Or you can see code samples for a use case in the fullscreen APIs Explorer by clicking on the code icon below a use case name. In the fullscreen UI, you can update parameter and property values and the code samples will dynamically update to reflect the values you enter. This method has one common use case, which is described below. The buttons below the description populate the APIs Explorer with sample values or open the fullscreen APIs Explorer to show code samples that use those values. The code samples also dynamically update if you change the values.
## Request ### HTTP request ``` DELETE https://www.googleapis.com/youtube/v3/captions ``` ### Authorization This request requires authorization with at least one of the following scopes. To read more about authentication and authorization, see [Implementing OAuth 2.0 authorization](https://developers.google.com/youtube/v3/guides/authentication). | Scope | |-----------------------------------------------------| | `https://www.googleapis.com/auth/youtube.force-ssl` | | `https://www.googleapis.com/auth/youtubepartner` | ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters || |--------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---| | **Required parameters** ||| | `id` | `string` The **id** parameter identifies the caption track that is being deleted. The value is a caption track ID as identified by the [id](https://developers.google.com/youtube/v3/docs/captions#id) property in a `caption` resource. | | **Optional parameters** ||| | `onBehalfOfContentOwner` | `string` This parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication). **Note:** This parameter is intended exclusively for YouTube content partners. The **onBehalfOfContentOwner** parameter indicates that the request's authorization credentials identify a YouTube CMS user who is acting on behalf of the content owner specified in the parameter value. This parameter is intended for YouTube content partners that own and manage many different YouTube channels. It allows content owners to authenticate once and get access to all their video and channel data, without having to provide authentication credentials for each individual channel. The actual CMS account that the user authenticates with must be linked to the specified YouTube content owner. | ### Request body Do not provide a request body when calling this method. ## Response If successful, this method returns an HTTP `204 No Content` status code. ## Errors The following table identifies error messages that the API could return in response to a call to this method. Fore more details, see [YouTube Data API - Errors](https://developers.google.com/youtube/v3/docs/errors). | Error type | Error detail | Description | |-------------------|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------| | `forbidden (403)` | `forbidden` | The permissions associated with the request are not sufficient to delete the caption track. The request might not be properly authorized. | | `notFound (404)` | `captionNotFound` | The caption track could not be found. Check the value of the request's `id` parameter to ensure that it is correct. | ## Try it! Use the APIs Explorer to call this API and see the API request and response. --- # Source: https://developers.google.com/youtube/v3/docs/captions/download.md.txt # Captions: download Downloads a caption track. The caption track is returned in its original format unless the request specifies a value for the `tfmt` parameter and in its original language unless the request specifies a value for the `tlang` parameter. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 200 units. This method is requires the user to have permission to edit the video. ## Common use cases The list below shows common use cases for this method. Hover over a use case to see its description, or click on a use case to load sample parameter values in the APIs Explorer. You can open the [fullscreen APIs Explorer](https://developers.google.com/youtube/v3/docs/captions/download#) to see code samples that dynamically update to reflect the parameter values entered in the Explorer. The table below shows common use cases for this method. You can click on a use case name to load sample parameter values in the APIs Explorer. Or you can see code samples for a use case in the fullscreen APIs Explorer by clicking on the code icon below a use case name. In the fullscreen UI, you can update parameter and property values and the code samples will dynamically update to reflect the values you enter. This method has one common use case, which is described below. The buttons below the description populate the APIs Explorer with sample values or open the fullscreen APIs Explorer to show code samples that use those values. The code samples also dynamically update if you change the values.
## Request ### HTTP request ``` GET https://www.googleapis.com/youtube/v3/captions/id ``` ### Authorization This request requires authorization with at least one of the following scopes ([read more about authentication and authorization](https://developers.google.com/youtube/v3/guides/authentication)). | Scope | |-----------------------------------------------------| | `https://www.googleapis.com/auth/youtube.force-ssl` | | `https://www.googleapis.com/auth/youtubepartner` | ### Parameters The table below lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters || |--------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---| | **Required parameters** ||| | `id` | `string` The **id** parameter identifies the caption track that is being retrieved. The value is a caption track ID as identified by the [id](https://developers.google.com/youtube/v3/docs/captions#id) property in a `caption` resource. | | **Optional parameters** ||| | `onBehalfOfContentOwner` | `string` This parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication). **Note:** This parameter is intended exclusively for YouTube content partners. The **onBehalfOfContentOwner** parameter indicates that the request's authorization credentials identify a YouTube CMS user who is acting on behalf of the content owner specified in the parameter value. This parameter is intended for YouTube content partners that own and manage many different YouTube channels. It allows content owners to authenticate once and get access to all their video and channel data, without having to provide authentication credentials for each individual channel. The actual CMS account that the user authenticates with must be linked to the specified YouTube content owner. | | `tfmt` | `string` The **tfmt** parameter specifies that the caption track should be returned in a specific format. If the parameter is not included in the request, the track is returned in its original format. Supported values are: - **sbv** -- SubViewer subtitle - **scc** -- Scenarist Closed Caption format - **srt** -- SubRip subtitle - **ttml** -- Timed Text Markup Language caption - **vtt** -- Web Video Text Tracks caption | | `tlang` | `string` The **tlang** parameter specifies that the API response should return a translation of the specified caption track. The parameter value is an [ISO 639-1 two-letter language code](http://www.loc.gov/standards/iso639-2/php/code_list.php) that identifies the desired caption language. The translation is generated by using machine translation, such as Google Translate. | ### Request body Do not provide a request body when calling this method. ## Response If successful, this method returns a binary file. The `Content-Type` header for the response is `application/octet-stream`. ## Errors The table below identifies error messages that the API could return in response to a call to this method. Please see the [error message](https://developers.google.com/youtube/v3/docs/errors) documentation for more detail. | Error type | Error detail | Description | |----------------------|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `forbidden (403)` | `forbidden` | The permissions associated with the request are not sufficient to download the caption track. The request might not be properly authorized. | | `invalidValue (400)` | `couldNotConvert` | The caption track data could not be converted to the requested language and/or format. Ensure that the requested `tfmt` and `tlang` values are valid, and that the `snippet.status` of the requested caption track is not `failed`. | | `notFound (404)` | `captionNotFound` | The caption track could not be found. Check the value of the request's `id` parameter to ensure that it is correct. | ## Try it! Use the APIs Explorer to call this API and see the API request and response. --- # Source: https://developers.google.com/youtube/v3/docs/captions/insert.md.txt # Captions: insert Uploads a caption track. This method supports media upload. Uploaded files must conform to these constraints: - **Maximum file size:** 100MB - **Accepted Media MIME types:** `text/xml`, `application/octet-stream`, `*/*` **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/determine_quota_cost) of 400 units. ## Common use cases The list below shows common use cases for this method. Hover over a use case to see its description, or click on a use case to load sample parameter values in the APIs Explorer. You can open the [fullscreen APIs Explorer](https://developers.google.com/youtube/v3/docs/captions/insert#) to see code samples that dynamically update to reflect the parameter values entered in the Explorer. The table below shows common use cases for this method. You can click on a use case name to load sample parameter values in the APIs Explorer. Or you can see code samples for a use case in the fullscreen APIs Explorer by clicking on the code icon below a use case name. In the fullscreen UI, you can update parameter and property values and the code samples will dynamically update to reflect the values you enter. This method has one common use case, which is described below. The buttons below the description populate the APIs Explorer with sample values or open the fullscreen APIs Explorer to show code samples that use those values. The code samples also dynamically update if you change the values.
## Request ### HTTP request ``` POST https://www.googleapis.com/upload/youtube/v3/captions ``` ### Authorization This request requires authorization with at least one of the following scopes. To read more about authentication and authorization, see [Implementing OAuth 2.0 authorization](https://developers.google.com/youtube/v3/guides/authentication). | Scope | |-----------------------------------------------------| | `https://www.googleapis.com/auth/youtube.force-ssl` | | `https://www.googleapis.com/auth/youtubepartner` | ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters || |--------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---| | **Required parameters** ||| | `part` | `string` The **part** parameter specifies the `caption` resource parts that the API response will include. Set the parameter value to `snippet`. The following list contains the `part` names that you can include in the parameter value: - `id` - `snippet` | | **Optional parameters** ||| | `onBehalfOfContentOwner` | `string` This parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication). **Note:** This parameter is intended exclusively for YouTube content partners. The **onBehalfOfContentOwner** parameter indicates that the request's authorization credentials identify a YouTube CMS user who is acting on behalf of the content owner specified in the parameter value. This parameter is intended for YouTube content partners that own and manage many different YouTube channels. It allows content owners to authenticate once and get access to all their video and channel data, without having to provide authentication credentials for each individual channel. The actual CMS account that the user authenticates with must be linked to the specified YouTube content owner. | | `sync` | `boolean` This parameter has been deprecated. The **sync** parameter indicates whether YouTube should automatically synchronize the caption file with the audio track of the video. If you set the value to `true`, YouTube will disregard any time codes that are in the uploaded caption file and generate new time codes for the captions. You should set the `sync` parameter to `true` if you are uploading a transcript, which has no time codes, or if you suspect the time codes in your file are incorrect and want YouTube to try to fix them. | ### Request body Provide a [caption](https://developers.google.com/youtube/v3/docs/captions#resource) resource in the request body. For that resource: You must specify a value for these properties: - `snippet.videoId` - `snippet.language` - `snippet.name` You can set values for these properties: - `snippet.videoId` - `snippet.language` - `snippet.name` - `snippet.isDraft` ## Response If successful, this method returns a [caption](https://developers.google.com/youtube/v3/docs/captions#resource) resource in the response body. ## Errors The following table identifies error messages that the API could return in response to a call to this method. For more details, see [YouTube Data API - Errors](https://developers.google.com/youtube/v3/docs/errors). | Error type | Error detail | Description | |----------------------|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `contentRequired` | The request does not contain the caption track contents. | | `conflict (409)` | `captionExists` | The specified video already has a caption track with the given `snippet.language` and `snippet.name`. A video can have multiple tracks for the same language, but each track must have a different name. There are multiple ways to address the error. You could delete the existing track and then insert a new one or change the name of the new track before inserting it. | | `forbidden (403)` | `forbidden` | The permissions associated with the request are not sufficient to upload the caption track. The request might not be properly authorized. | | `invalidValue (400)` | `invalidMetadata` | The request contains invalid metadata values, which prevent the track from being created. Confirm that the request specifies valid values for the `snippet.language`, `snippet.name`, and `snippet.videoId` properties. The `snippet.isDraft` property can also be included, but it is not required. | | `notFound (404)` | `videoNotFound` | The video identified by the `videoId` parameter couldn't be found. | | `invalidValue (400)` | `nameTooLong` | The `snippet.name` specified in the request is too long. The maximum length supported is 150 characters. | ## Try it! Use the APIs Explorer to call this API and see the API request and response. --- # Source: https://developers.google.com/youtube/v3/docs/captions/list.md.txt # Captions: list Returns a list of caption tracks that are associated with a specified video. Note that the API response does not contain the actual captions and that the [captions.download](https://developers.google.com/youtube/v3/docs/captions/download) method provides the ability to retrieve a caption track. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 50 units. ## Common use cases The list below shows common use cases for this method. Hover over a use case to see its description, or click on a use case to load sample parameter values in the APIs Explorer. You can open the [fullscreen APIs Explorer](https://developers.google.com/youtube/v3/docs/captions/list#) to see code samples that dynamically update to reflect the parameter values entered in the Explorer. The table below shows common use cases for this method. You can click on a use case name to load sample parameter values in the APIs Explorer. Or you can see code samples for a use case in the fullscreen APIs Explorer by clicking on the code icon below a use case name. In the fullscreen UI, you can update parameter and property values and the code samples will dynamically update to reflect the values you enter. This method has one common use case, which is described below. The buttons below the description populate the APIs Explorer with sample values or open the fullscreen APIs Explorer to show code samples that use those values. The code samples also dynamically update if you change the values.
## Request ### HTTP request ``` GET https://www.googleapis.com/youtube/v3/captions ``` ### Authorization This request requires authorization with at least one of the following scopes ([read more about authentication and authorization](https://developers.google.com/youtube/v3/guides/authentication)). | Scope | |-----------------------------------------------------| | `https://www.googleapis.com/auth/youtube.force-ssl` | | `https://www.googleapis.com/auth/youtubepartner` | ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters || |--------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---| | **Required parameters** ||| | `part` | `string` The **part** parameter specifies the `caption` resource parts that the API response will include. The list below contains the `part` names that you can include in the parameter value: - `id` - `snippet` | | `videoId` | `string` The **videoId** parameter specifies the YouTube video ID of the video for which the API should return caption tracks. | | **Optional parameters** ||| | `id` | `string` The **id** parameter specifies a comma-separated list of IDs that identify the `caption` resources that should be retrieved. Each ID must identify a caption track associated with the specified video. | | `onBehalfOfContentOwner` | `string` This parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication). **Note:** This parameter is intended exclusively for YouTube content partners. The **onBehalfOfContentOwner** parameter indicates that the request's authorization credentials identify a YouTube CMS user who is acting on behalf of the content owner specified in the parameter value. This parameter is intended for YouTube content partners that own and manage many different YouTube channels. It allows content owners to authenticate once and get access to all their video and channel data, without having to provide authentication credentials for each individual channel. The actual CMS account that the user authenticates with must be linked to the specified YouTube content owner. | ### Request body Do not provide a request body when calling this method. ## Response If successful, this method returns a response body with the following structure: ```objective-c { "kind": "youtube#captionListResponse", "etag": etag, "items": [ caption Resource ] } ``` ### 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#captionListResponse`. | | `etag` | `etag` The Etag of this resource. | | `items[]` | `list` A list of captions that match the request criteria. | ## Errors The following table identifies error messages that the API could return in response to a call to this method. Please see the [error message](https://developers.google.com/youtube/v3/docs/errors) documentation for more detail. | Error type | Error detail | Description | |-------------------|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `forbidden (403)` | `forbidden` | One or more caption tracks could not be retrieved because the permissions associated with the request are not sufficient to retrieve the requested resources. The request might not be properly authorized. | | `notFound (404)` | `captionNotFound` | One or more of the specified caption tracks could not be found. This error occurs if the `videoId` parameter identifies an actual video, but the `id` parameter either identifies caption track IDs that do not exist or track IDs that are associated with other videos. Check the values of the request's `id` and `videoId` parameters to ensure that they are correct. | | `notFound (404)` | `videoNotFound` | The video identified by the `videoId` parameter could not be found. | ## Try it! Use the APIs Explorer to call this API and see the API request and response. --- # Source: https://developers.google.com/youtube/v3/docs/captions/update.md.txt # Captions: update Updates a caption track. When updating a caption track, you can change the track's [draft status](https://developers.google.com/youtube/v3/docs/captions#snippet.isDraft), upload a new caption file for the track, or both. This method supports media upload. Uploaded files must conform to these constraints: - **Maximum file size:** 100MB - **Accepted Media MIME types:** `text/xml`, `application/octet-stream`, `*/*` **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 450 units. ## Common use cases The list below shows common use cases for this method. Hover over a use case to see its description, or click on a use case to load sample parameter values in the APIs Explorer. You can open the [fullscreen APIs Explorer](https://developers.google.com/youtube/v3/docs/captions/update#) to see code samples that dynamically update to reflect the parameter values entered in the Explorer. The table below shows common use cases for this method. You can click on a use case name to load sample parameter values in the APIs Explorer. Or you can see code samples for a use case in the fullscreen APIs Explorer by clicking on the code icon below a use case name. In the fullscreen UI, you can update parameter and property values and the code samples will dynamically update to reflect the values you enter. This method has one common use case, which is described below. The buttons below the description populate the APIs Explorer with sample values or open the fullscreen APIs Explorer to show code samples that use those values. The code samples also dynamically update if you change the values.
## Request ### HTTP request ``` PUT https://www.googleapis.com/upload/youtube/v3/captions ``` ### Authorization This request requires authorization with at least one of the following scopes ([read more about authentication and authorization](https://developers.google.com/youtube/v3/guides/authentication)). | Scope | |-----------------------------------------------------| | `https://www.googleapis.com/auth/youtube.force-ssl` | | `https://www.googleapis.com/auth/youtubepartner` | ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters || |--------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---| | **Required parameters** ||| | `part` | `string` The **part** parameter serves two purposes in this operation. It identifies the properties that the write operation will set as well as the properties that the API response will include. Set the property value to `snippet` if you are updating the track's [draft status](https://developers.google.com/youtube/v3/docs/captions#snippet.isDraft). Otherwise, set the property value to `id`. The following list contains the `part` names that you can include in the parameter value: - `id` - `snippet` | | **Optional parameters** ||| | `onBehalfOfContentOwner` | `string` This parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication). **Note:** This parameter is intended exclusively for YouTube content partners. The **onBehalfOfContentOwner** parameter indicates that the request's authorization credentials identify a YouTube CMS user who is acting on behalf of the content owner specified in the parameter value. This parameter is intended for YouTube content partners that own and manage many different YouTube channels. It allows content owners to authenticate once and get access to all their video and channel data, without having to provide authentication credentials for each individual channel. The actual CMS account that the user authenticates with must be linked to the specified YouTube content owner. | | `sync` | `boolean` This parameter has been deprecated. **Note:** The API server only processes the parameter value if the request contains an updated caption file. The **sync** parameter indicates whether YouTube should automatically synchronize the caption file with the audio track of the video. If you set the value to `true`, YouTube will automatically synchronize the caption track with the audio track. | ### Request body Provide a [caption resource](https://developers.google.com/youtube/v3/docs/captions#resource) in the request body. For that resource: - You must specify a value for these properties:
- `id`
- You can set values for these properties:
- `snippet.isDraft`
If you are submitting an update request, and your request does not specify a value for a property that already has a value, the property's existing value will be deleted. ## Response If successful, this method returns a [caption resource](https://developers.google.com/youtube/v3/docs/captions#resource) in the response body. ## Errors The following table identifies error messages that the API could return in response to a call to this method. Please see the [error message](https://developers.google.com/youtube/v3/docs/errors) documentation for more detail. | Error type | Error detail | Description | |--------------------|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `contentRequired` | The request did not upload an updated caption file. The actual track contents are required if the `sync` parameter is set to `true`. | | `forbidden (403)` | `forbidden` | The permissions associated with the request are not sufficient to update the caption track. The request might not be properly authorized. | | `notFound (404)` | `captionNotFound` | The specified caption track could not be found. Check the value of the request's `id` property to ensure that it is correct. | ## Try it! Use the APIs Explorer to call this API and see the API request and response. --- # Source: https://developers.google.com/youtube/v3/docs/channelBanners.md.txt # ChannelBanners A `channelBanner` resource contains the URL that you would use to set a newly uploaded image as the banner image for a channel. ## Methods The API supports the following methods for `channelBanners` resources: [insert](https://developers.google.com/youtube/v3/docs/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](https://developers.google.com/youtube/v3/docs/channelBanners/insert) method to upload the binary image data to YouTube. The image must have a 16:9 aspect ratio and be at least 2048x1152 pixels. We recommend uploading a 2560px by 1440px image. 2. Extract the `url` property's value from the response that the API returns for step 1. 3. Call the [channels.update](https://developers.google.com/youtube/v3/docs/channels/update) method to update the channel's branding settings. Set the [brandingSettings.image.bannerExternalUrl](https://developers.google.com/youtube/v3/docs/channels#brandingSettings.image.bannerExternalUrl) property's value to the URL obtained in step 2. ## Resource representation The following JSON structure shows the format of a `channelBanners` resource: ```text { "kind": "youtube#channelBannerResource", "etag": etag, "url": 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#channelBannerResource`. | | `etag` | `etag` The Etag of this resource. | | `url` | `string` The banner image's URL. After calling the [channelBanners.insert](https://developers.google.com/youtube/v3/docs/channelBanners/insert) method, extract this value from the API response. Then call the [channels.update](https://developers.google.com/youtube/v3/docs/channels/update) method, and set the URL as the value of the [brandingSettings.image.bannerExternalUrl](https://developers.google.com/youtube/v3/docs/channels#brandingSettings.image.bannerExternalUrl) property to set the banner image for a channel. | --- # Source: https://developers.google.com/youtube/v3/docs/channelBanners/insert.md.txt # 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 2048x1152 pixels. We recommend uploading a 2560px by 1440px image. 2. Extract the `url` property's value from the response that the API returns for step 1. 3. Call the [channels.update](https://developers.google.com/youtube/v3/docs/channels/update) method to update the channel's branding settings. Set the [brandingSettings.image.bannerExternalUrl](https://developers.google.com/youtube/v3/docs/channels#brandingSettings.image.bannerExternalUrl) property's value to the URL obtained in step 2.
This method supports media upload. Uploaded files must conform to these constraints: - **Maximum file size:** 6MB - **Accepted Media MIME types:** `image/jpeg`, `image/png`, `application/octet-stream` **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 50 units. ## Request ### HTTP request ``` POST https://www.googleapis.com/upload/youtube/v3/channelBanners/insert ``` ### Authorization This request requires authorization with at least one of the following scopes. To read more about authentication and authorization, see [Implementing OAuth 2.0 authorization](https://developers.google.com/youtube/v3/guides/authentication). | Scope | |-----------------------------------------------------| | `https://www.googleapis.com/auth/youtube.upload` | | `https://www.googleapis.com/auth/youtube` | | `https://www.googleapis.com/auth/youtube.force-ssl` | ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters || |--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---| | **Optional parameters** ||| | `onBehalfOfContentOwner` | `string` This parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication). **Note:** This parameter is intended exclusively for YouTube content partners. The **onBehalfOfContentOwner** parameter indicates that the request's authorization credentials identify a YouTube CMS user who is acting on behalf of the content owner specified in the parameter value. This parameter is intended for YouTube content partners that own and manage many different YouTube channels. It allows content owners to authenticate once and get access to all their video and channel data, without having to provide authentication credentials for each individual channel. The CMS account that the user authenticates with must be linked to the specified YouTube content owner. | ### Request body Do not provide a request body when calling this method. ## Response If successful, this method returns a [channelBanner](https://developers.google.com/youtube/v3/docs/channelBanners#resource) resource in the response body. ## Errors The following table identifies error messages that the API could return in response to a call to this method. For more details, see [YouTube Data API - Errors](https://developers.google.com/youtube/v3/docs/errors). | Error type | Error detail | Description | |--------------------|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `bannerAlbumFull` | Your YouTube Channel Art album has too many images. To fix this, go to [Google Photos](http://photos.google.com), then navigate to the albums page and remove some images from that album. | | `badRequest (400)` | `mediaBodyRequired` | The request does not include the image content. | ## Try it! Use the APIs Explorer to call this API and see the API request and response. --- # Source: https://developers.google.com/youtube/v3/docs/channelSections.md.txt # ChannelSections A **channelSection** resource contains information about a set of videos that a channel has chosen to feature. For example, a section could feature a channel's latest uploads, most popular uploads, or videos from one or more playlists. A channel can create a maximum of 10 shelves. ## Methods The API supports the following methods for `channelSections` resources: [list](https://developers.google.com/youtube/v3/docs/channelSections/list) : Returns a list of `channelSection` resources that match the API request criteria. [Try it now](https://developers.google.com/youtube/v3/docs/channelSections/list#usage). [insert](https://developers.google.com/youtube/v3/docs/channelSections/insert) : Adds a channel section to the authenticated user's channel. A channel can create a maximum of 10 shelves. [Try it now](https://developers.google.com/youtube/v3/docs/channelSections/insert#usage). [update](https://developers.google.com/youtube/v3/docs/channelSections/update) : Updates a channel section. [Try it now](https://developers.google.com/youtube/v3/docs/channelSections/update#usage). [delete](https://developers.google.com/youtube/v3/docs/channelSections/delete) : Deletes a channel section. [Try it now](https://developers.google.com/youtube/v3/docs/channelSections/delete#usage). ## Resource representation The following JSON structure shows the format of a `channelSections` resource: ```carbon { "https://developers.google.com/youtube/v3/docs/channelSections#kind": "youtube#channelSection", "https://developers.google.com/youtube/v3/docs/channelSections#etag": etag, "https://developers.google.com/youtube/v3/docs/channelSections#id": string, "https://developers.google.com/youtube/v3/docs/channelSections#snippet": { "https://developers.google.com/youtube/v3/docs/channelSections#snippet.type": string, "https://developers.google.com/youtube/v3/docs/channelSections#snippet.channelId": string, "https://developers.google.com/youtube/v3/docs/channelSections#snippet.title": string, "https://developers.google.com/youtube/v3/docs/channelSections#snippet.position": unsigned integer }, "https://developers.google.com/youtube/v3/docs/channelSections#contentDetails": { "https://developers.google.com/youtube/v3/docs/channelSections#contentDetails.playlists[]": [ string ], "https://developers.google.com/youtube/v3/docs/channelSections#contentDetails.channels[]": [ 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#channelSection`. | | `etag` | `etag` The Etag of this resource. | | `id` | `string` The ID that YouTube uses to uniquely identify the channel section. | | `snippet` | `object` The `snippet` object contains basic details about the channel section, such as its type and title. | | snippet.`type` | `string` The channel section's type. Valid values for this property are: - `allPlaylists` - `completedEvents` - `liveEvents` - `multipleChannels` - `multiplePlaylists` - `popularUploads` - `recentUploads` - `singlePlaylist` - `subscriptions` - `upcomingEvents` | | snippet.`channelId` | `string` The ID that YouTube uses to uniquely identify the channel that published the channel section. | | snippet.`title` | `string` The section's title. You can only set the title of a channel section that has a `snippet.type` value of either `multiplePlaylists` or `multipleChannels`, and, in fact, you must specify a title when inserting or updating either of those types of sections. If you specify a title for other types of channel sections, the value will be ignored. This property's value has a maximum length of 100 characters and may contain all valid UTF-8 characters except **\<** and **\>**. | | snippet.`position` | `unsigned integer` The section's position on the channel page. This property uses a 0-based index. A value of `0` identifies the first section that appears on the channel, a value of `1` identifies the second section, and so forth. If you do not specify a value for this property when inserting a channel section, the default behavior is to display the new section last. | | `contentDetails` | `object` The `contentDetails` object contains details about the channel section's content, such as a list of playlists or channels featured in the section. | | contentDetails.`playlists[]` | `list` A list of one or more playlist IDs that are featured in a channel section. You must specify a list of playlist IDs if the `channelSection` resource's `snippet.type` property is either `singlePlaylist` or `multiplePlaylists`, and this property should not be specified for other types of sections. If the type is `singlePlaylist`, this list must specify exactly one playlist ID. | | contentDetails.`channels[]` | `list` A list of one or more channel IDs that are featured in a channel section. You must specify a list of channel IDs if the `channelSection` resource's `snippet.type` property is `multipleChannels`, and this property should not be specified for other types of sections. You cannot include your own channel in the list. | --- # Source: https://developers.google.com/youtube/v3/docs/channelSections/delete.md.txt # ChannelSections: delete Deletes a channel section. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 50 units. ## Common use cases The list below shows common use cases for this method. Hover over a use case to see its description, or click on a use case to load sample parameter values in the APIs Explorer. You can open the [fullscreen APIs Explorer](https://developers.google.com/youtube/v3/docs/channelSections/delete#) to see code samples that dynamically update to reflect the parameter values entered in the Explorer. The table below shows common use cases for this method. You can click on a use case name to load sample parameter values in the APIs Explorer. Or you can see code samples for a use case in the fullscreen APIs Explorer by clicking on the code icon below a use case name. In the fullscreen UI, you can update parameter and property values and the code samples will dynamically update to reflect the values you enter. This method has one common use case, which is described below. The buttons below the description populate the APIs Explorer with sample values or open the fullscreen APIs Explorer to show code samples that use those values. The code samples also dynamically update if you change the values.
## Request ### HTTP request ``` DELETE https://www.googleapis.com/youtube/v3/channelSections ``` ### Authorization This request requires authorization with at least one of the following scopes ([read more about authentication and authorization](https://developers.google.com/youtube/v3/guides/authentication)). | Scope | |-----------------------------------------------------| | `https://www.googleapis.com/auth/youtubepartner` | | `https://www.googleapis.com/auth/youtube` | | `https://www.googleapis.com/auth/youtube.force-ssl` | ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters || |--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---| | **Required parameters** ||| | `id` | `string` The **id** parameter specifies the ID that uniquely identifies the channel section that is being deleted. In a `channelSection` resource, the `id` property specifies the section's ID. | | **Optional parameters** ||| | `onBehalfOfContentOwner` | `string` This parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication). **Note:** This parameter is intended exclusively for YouTube content partners. The **onBehalfOfContentOwner** parameter indicates that the request's authorization credentials identify a YouTube CMS user who is acting on behalf of the content owner specified in the parameter value. This parameter is intended for YouTube content partners that own and manage many different YouTube channels. It allows content owners to authenticate once and get access to all their video and channel data, without having to provide authentication credentials for each individual channel. The CMS account that the user authenticates with must be linked to the specified YouTube content owner. | ### Request body Do not provide a request body when calling this method. ## Response If successful, this method returns a [channelSection resource](https://developers.google.com/youtube/v3/docs/channelSections#resource) in the response body. ## Errors The following table identifies error messages that the API could return in response to a call to this method. Please see the [error message](https://developers.google.com/youtube/v3/docs/errors) documentation for more detail. | Error type | Error detail | Description | |----------------------|---------------------------|-------------------------------------------------------------------------------------------| | `badRequest (400)` | `notEditable` | This channel section cannot be deleted. | | `forbidden (403)` | `channelSectionForbidden` | The request is not properly authenticated or not supported for this channel. | | `invalidValue (400)` | `idInvalid` | The `id` property specifies an invalid channel section ID. | | `invalidValue (400)` | `idRequired` | The `id` property must specify a value that identifies the channel section being deleted. | | `notFound (404)` | `channelNotFound` | The channel is not found. | | `notFound (404)` | `channelSectionNotFound` | The channel section you are trying to update cannot be found. | ## Try it! Use the APIs Explorer to call this API and see the API request and response. --- # Source: https://developers.google.com/youtube/v3/docs/channelSections/insert.md.txt # ChannelSections: insert Adds a channel section to the authenticated user's channel. A channel can create a maximum of 10 shelves. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 50 units. ## Common use cases The list below shows common use cases for this method. Hover over a use case to see its description, or click on a use case to load sample parameter values in the APIs Explorer. You can open the [fullscreen APIs Explorer](https://developers.google.com/youtube/v3/docs/channelSections/insert#) to see code samples that dynamically update to reflect the parameter values entered in the Explorer. The table below shows common use cases for this method. You can click on a use case name to load sample parameter values in the APIs Explorer. Or you can see code samples for a use case in the fullscreen APIs Explorer by clicking on the code icon below a use case name. In the fullscreen UI, you can update parameter and property values and the code samples will dynamically update to reflect the values you enter. This method has one common use case, which is described below. The buttons below the description populate the APIs Explorer with sample values or open the fullscreen APIs Explorer to show code samples that use those values. The code samples also dynamically update if you change the values.
## Request ### HTTP request ``` POST https://www.googleapis.com/youtube/v3/channelSections ``` ### Authorization This request requires authorization with at least one of the following scopes ([read more about authentication and authorization](https://developers.google.com/youtube/v3/guides/authentication)). | Scope | |-----------------------------------------------------| | `https://www.googleapis.com/auth/youtubepartner` | | `https://www.googleapis.com/auth/youtube` | | `https://www.googleapis.com/auth/youtube.force-ssl` | ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters || |---------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---| | **Required parameters** ||| | `part` | `string` The **part** parameter serves two purposes in this operation. It identifies the properties that the write operation will set as well as the properties that the API response will include. The following list contains the `part` names that you can include in the parameter value: - `contentDetails` - `id` - `snippet` | | **Optional parameters** ||| | `onBehalfOfContentOwner` | `string` This parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication). **Note:** This parameter is intended exclusively for YouTube content partners. The **onBehalfOfContentOwner** parameter indicates that the request's authorization credentials identify a YouTube CMS user who is acting on behalf of the content owner specified in the parameter value. This parameter is intended for YouTube content partners that own and manage many different YouTube channels. It allows content owners to authenticate once and get access to all their video and channel data, without having to provide authentication credentials for each individual channel. The CMS account that the user authenticates with must be linked to the specified YouTube content owner. | | `onBehalfOfContentOwnerChannel` | `string` This parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication). **Note:** This parameter is intended exclusively for YouTube content partners. The **onBehalfOfContentOwnerChannel** parameter specifies the YouTube channel ID of the channel to which a video is being added. This parameter is required when a request specifies a value for the `onBehalfOfContentOwner` parameter, and it can only be used in conjunction with that parameter. In addition, the request must be authorized using a CMS account that is linked to the content owner that the `onBehalfOfContentOwner` parameter specifies. Finally, the channel that the `onBehalfOfContentOwnerChannel` parameter value specifies must be linked to the content owner that the `onBehalfOfContentOwner` parameter specifies. This parameter is intended for YouTube content partners that own and manage many different YouTube channels. It allows content owners to authenticate once and perform actions on behalf of the channel specified in the parameter value, without having to provide authentication credentials for each separate channel. | ### Request body Provide a [channelSection resource](https://developers.google.com/youtube/v3/docs/channelSections#resource) in the request body. For that resource: - You must specify a value for these properties:
- `snippet.type`
- You can set values for these properties:
- `snippet.type` - `snippet.title` - `snippet.position` - `contentDetails.playlists[]` - `contentDetails.channels[]`
## Response If successful, this method returns a [channelSection resource](https://developers.google.com/youtube/v3/docs/channelSections#resource) in the response body. ## Errors The following table identifies error messages that the API could return in response to a call to this method. Please see the [error message](https://developers.google.com/youtube/v3/docs/errors) documentation for more detail. | Error type | Error detail | Description | |----------------------|-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `notEditable` | This channel section cannot be created. | | `badRequest (400)` | `typeRequired` | The `channelSection` resource must specify a value for the `snippet.type` field. | | `forbidden (403)` | `channelSectionForbidden` | The request is not properly authenticated or is not supported for this channel. | | `invalidValue (400)` | `channelNotActive` | At least one of the specified channels is not active. | | `invalidValue (400)` | `channelsDuplicated` | The request failed because it specified duplicate channels. | | `invalidValue (400)` | `channelsNeeded` | If the `snippet.type` property has a value of `multipleChannels`, then the `contentDetails.channels[]` property must be specified and must specify at least one channel. | | `invalidValue (400)` | `channelsNotExpected` | The resource provided with the request specified a value for the `contentDetails.channels[]` property, but channels are not expected for this type of channel section. | | `invalidValue (400)` | `contentDetailsNeeded` | The resource you are inserting must contain a `contentDetails` object for this type of channel section. | | `invalidValue (400)` | `inValidPosition` | The `snippet.position` property contains an invalid value. | | `invalidValue (400)` | `maxChannelSectionExceeded` | The request cannot be completed because the channel already has the maximum number of channel sections. | | `invalidValue (400)` | `maxChannelsExceeded` | The request failed because it attempted to include too many channels in the channel section. | | `invalidValue (400)` | `maxPlaylistExceeded` | The request failed because it attempted to include too many playlists in the channel section. | | `invalidValue (400)` | `onePlaylistNeeded` | If the `snippet.type` property has a value of `singlePlaylist`, then the `contentDetails.playlists[]` property must specify exactly one playlist. | | `invalidValue (400)` | `ownChannelInChannels` | You cannot include your own channel in a channel section that appears on that channel. | | `invalidValue (400)` | `playlistIsPrivate` | One or more of the specified playlists are private and, therefore, cannot be included in the channel section. | | `invalidValue (400)` | `playlistsDuplicated` | The request failed because it specified duplicate playlists. | | `invalidValue (400)` | `playlistsNeeded` | If the `snippet.type` property has a value of `singlePlaylist` or `multiplePlaylists`, then the `contentDetails.playlists[]` property must be specified. | | `invalidValue (400)` | `playlistsNotExpected` | The resource provided with the request specified a value for the `contentDetails.playlists[]` property, but playlists are not expected for this type of channel section. | | `invalidValue (400)` | `snippetNeeded` | You must specify a `snippet` to create the channel section. | | `invalidValue (400)` | `titleLengthExceeded` | The value of the `snippet.title` property is too long. | | `invalidValue (400)` | `titleRequired` | If the `snippet.type` property has a value of `multiplePlaylists` or `multipleChannels`, then you must set the section's title by specifying a value for the `snippet.title` property. | | `notFound (404)` | `channelNotFound` | One or more of the specified channels cannot be found. | | `notFound (404)` | `playlistNotFound` | One or more of the specified playlists cannot be found. | ## Try it! Use the APIs Explorer to call this API and see the API request and response. --- # Source: https://developers.google.com/youtube/v3/docs/channelSections/list.md.txt # ChannelSections: list Returns a list of `channelSection` resources that match the API request criteria. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 1 unit. ## Common use cases The list below shows common use cases for this method. Hover over a use case to see its description, or click on a use case to load sample parameter values in the APIs Explorer. You can open the [fullscreen APIs Explorer](https://developers.google.com/youtube/v3/docs/channelSections/list#) to see code samples that dynamically update to reflect the parameter values entered in the Explorer. The table below shows common use cases for this method. You can click on a use case name to load sample parameter values in the APIs Explorer. Or you can see code samples for a use case in the fullscreen APIs Explorer by clicking on the code icon below a use case name. In the fullscreen UI, you can update parameter and property values and the code samples will dynamically update to reflect the values you enter. This method has one common use case, which is described below. The buttons below the description populate the APIs Explorer with sample values or open the fullscreen APIs Explorer to show code samples that use those values. The code samples also dynamically update if you change the values.
## Request ### HTTP request ``` GET https://www.googleapis.com/youtube/v3/channelSections ``` ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters || |--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---| | **Required parameters** ||| | `part` | `string` The **part** parameter specifies a comma-separated list of one or more `channelSection` resource properties that the API response will include. If the parameter identifies a property that contains child properties, the child properties will be included in the response. For example, in a `channelSection` resource, the `snippet` property contains other properties, such as a display title for the section. If you set **part=snippet**, the API response will also contain all of those nested properties. The following list contains the `part` names that you can include in the parameter value: - `contentDetails` - `id` - `snippet` | | **Filters (specify exactly one of the following parameters)** ||| | `channelId` | `string` The **channelId** parameter specifies a YouTube channel ID. If a request specifies a value for this parameter, the API will only return the specified channel's sections. | | `id` | `string` The **id** parameter specifies a comma-separated list of IDs that uniquely identify the `channelSection` resources that are being retrieved. In a `channelSection` resource, the `id` property specifies the section's ID. | | `mine` | `boolean` This parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication). Set this parameter's value to `true` to retrieve a feed of the channel sections associated with the authenticated user's YouTube channel. | | **Optional parameters** ||| | `hl` | `string` This parameter has been deprecated. The **hl** parameter provided support for retrieving localized metadata for a channel section. However, this functionality has been deprecated in YouTube Studio and in the YouTube app. | | `onBehalfOfContentOwner` | `string` This parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication). **Note:** This parameter is intended exclusively for YouTube content partners. The **onBehalfOfContentOwner** parameter indicates that the request's authorization credentials identify a YouTube CMS user who is acting on behalf of the content owner specified in the parameter value. This parameter is intended for YouTube content partners that own and manage many different YouTube channels. It allows content owners to authenticate once and get access to all their video and channel data, without having to provide authentication credentials for each individual channel. The CMS account that the user authenticates with must be linked to the specified YouTube content owner. | ### Request body Do not provide a request body when calling this method. ## Response If successful, this method returns a response body with the following structure: ```objective-c { "kind": "youtube#channelSectionListResponse", "etag": etag, "items": [ channelSection Resource ] } ``` ### 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#channelSectionListResponse`. | | `etag` | `etag` The Etag of this resource. | | `items[]` | `list` A list of ChannelSections that match the request criteria. | ## Errors The following table identifies error messages that the API could return in response to a call to this method. Please see the [error message](https://developers.google.com/youtube/v3/docs/errors) documentation for more detail. | Error type | Error detail | Description | |----------------------|---------------------------|-----------------------------------------------------------------------------| | `forbidden (403)` | `channelSectionForbidden` | The requester is not allowed to access the requested channel sections. | | `invalidValue (400)` | `idInvalid` | The request specifies an invalid channel section ID. | | `invalidValue (400)` | `invalidCriteria` | The request could not be completed because the filter criteria are invalid. | | `notFound (404)` | `channelNotFound` | The channel associated with the request cannot be found. | | `notFound (404)` | `channelSectionNotFound` | The channel section associated with the request cannot be found. | ## Try it! Use the APIs Explorer to call this API and see the API request and response. --- # Source: https://developers.google.com/youtube/v3/docs/channelSections/update.md.txt # ChannelSections: update Updates a channel section. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 50 units. ## Common use cases The list below shows common use cases for this method. Hover over a use case to see its description, or click on a use case to load sample parameter values in the APIs Explorer. You can open the [fullscreen APIs Explorer](https://developers.google.com/youtube/v3/docs/channelSections/update#) to see code samples that dynamically update to reflect the parameter values entered in the Explorer. The table below shows common use cases for this method. You can click on a use case name to load sample parameter values in the APIs Explorer. Or you can see code samples for a use case in the fullscreen APIs Explorer by clicking on the code icon below a use case name. In the fullscreen UI, you can update parameter and property values and the code samples will dynamically update to reflect the values you enter. This method has one common use case, which is described below. The buttons below the description populate the APIs Explorer with sample values or open the fullscreen APIs Explorer to show code samples that use those values. The code samples also dynamically update if you change the values.
## Request ### HTTP request ``` PUT https://www.googleapis.com/youtube/v3/channelSections ``` ### Authorization This request requires authorization with at least one of the following scopes ([read more about authentication and authorization](https://developers.google.com/youtube/v3/guides/authentication)). | Scope | |-----------------------------------------------------| | `https://www.googleapis.com/auth/youtubepartner` | | `https://www.googleapis.com/auth/youtube` | | `https://www.googleapis.com/auth/youtube.force-ssl` | ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters || |--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---| | **Required parameters** ||| | `part` | `string` The **part** parameter serves two purposes in this operation. It identifies the properties that the write operation will set as well as the properties that the API response will include. The following list contains the `part` names that you can include in the parameter value: - `contentDetails` - `id` - `snippet` | | **Optional parameters** ||| | `onBehalfOfContentOwner` | `string` This parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication). **Note:** This parameter is intended exclusively for YouTube content partners. The **onBehalfOfContentOwner** parameter indicates that the request's authorization credentials identify a YouTube CMS user who is acting on behalf of the content owner specified in the parameter value. This parameter is intended for YouTube content partners that own and manage many different YouTube channels. It allows content owners to authenticate once and get access to all their video and channel data, without having to provide authentication credentials for each individual channel. The CMS account that the user authenticates with must be linked to the specified YouTube content owner. | ### Request body Provide a [channelSection resource](https://developers.google.com/youtube/v3/docs/channelSections#resource) in the request body. For that resource: - You must specify a value for these properties:
- `snippet.type`
- You can set values for these properties:
- `snippet.type` - `snippet.title` - `snippet.position` - `contentDetails.playlists[]` - `contentDetails.channels[]`
If you are submitting an update request, and your request does not specify a value for a property that already has a value, the property's existing value will be deleted. ## Response If successful, this method returns a [channelSection resource](https://developers.google.com/youtube/v3/docs/channelSections#resource) in the response body. ## Errors The following table identifies error messages that the API could return in response to a call to this method. Please see the [error message](https://developers.google.com/youtube/v3/docs/errors) documentation for more detail. | Error type | Error detail | Description | |----------------------|---------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `notEditable` | This channel section cannot be edited. | | `badRequest (400)` | `typeRequired` | The `channelSection` resource must specify a value for the `snippet.type` field. | | `forbidden (403)` | `channelSectionForbidden` | The request is not properly authenticated or is not supported for this channel. | | `invalidValue (400)` | `channelNotActive` | At least one of the specified channels is not active. | | `invalidValue (400)` | `channelsDuplicated` | The request failed because it specified duplicate channels. | | `invalidValue (400)` | `channelsNeeded` | If the `snippet.type` property has a value of `multipleChannels`, then the `contentDetails.channels[]` property must be specified and must specify at least one channel. | | `invalidValue (400)` | `channelsNotExpected` | The resource provided with the request specified a value for the `contentDetails.channels[]` property, but channels are not expected for this type of channel section. | | `invalidValue (400)` | `contentDetailsNeeded` | The resource you are updating must contain a `contentDetails` object for this type of channel section. | | `invalidValue (400)` | `idInvalid` | The `id` property specifies an invalid channel section ID. | | `invalidValue (400)` | `idRequired` | The `id` property must specify a value that identifies the channel section being updated. | | `invalidValue (400)` | `inValidPosition` | The `snippet.position` property contains an invalid value. | | `invalidValue (400)` | `maxChannelsExceeded` | The request failed because it attempted to include too many channels in the channel section. | | `invalidValue (400)` | `maxPlaylistExceeded` | The request failed because it attempted to include too many playlists in the channel section. | | `invalidValue (400)` | `onePlaylistNeeded` | If the `snippet.type` property has a value of `singlePlaylist`, then the `contentDetails.playlists[]` property must specify exactly one playlist. | | `invalidValue (400)` | `ownChannelInChannels` | You cannot include your own channel in a channel section that appears on that channel. | | `invalidValue (400)` | `playlistIsPrivate` | One or more of the specified playlists are private and, therefore, cannot be included in the channel section. | | `invalidValue (400)` | `playlistsDuplicated` | The request failed because it specified duplicate playlists. | | `invalidValue (400)` | `playlistsNeeded` | If the `snippet.type` property has a value of `singlePlaylist` or `multiplePlaylists`, then the `contentDetails.playlists[]` property must be specified. | | `invalidValue (400)` | `playlistsNotExpected` | The resource provided with the request specified a value for the `contentDetails.playlists[]` property, but playlists are not expected for this type of channel section. | | `invalidValue (400)` | `snippetNeeded` | You must specify a `snippet` to update the channel section. | | `invalidValue (400)` | `titleLengthExceeded` | The value of the `snippet.title` property is too long. | | `invalidValue (400)` | `titleRequired` | If the `snippet.type` property has a value of `multiplePlaylists` or `multipleChannels`, then you must set the section's title by specifying a value for the `snippet.title` property. | | `notFound (404)` | `channelNotFound` | One or more of the specified channels cannot be found. | | `notFound (404)` | `channelSectionNotFound` | The channel section you are trying to update cannot be found. | | `notFound (404)` | `playlistNotFound` | One or more of the specified playlists cannot be found. | ## Try it! Use the APIs Explorer to call this API and see the API request and response. --- # Source: https://developers.google.com/youtube/v3/docs/channels.md.txt # Channels The API now supports the ability to mark your channel or [videos](https://developers.google.com/youtube/v3/docs/videos) as "made for kids." In addition, `channel` and `video` resources also now contain a property that identifies the "made for kids" status of that channel or video. The YouTube API Services Terms of Service and Developer Policies were also updated on 10 January 2020. For more information, see the revision histories for the [YouTube Data API Service](https://developers.google.com/youtube/v3/revision_history) and the [YouTube API Services Terms of Service](https://developers.google.com/youtube/terms/revision-history). A **channel** resource contains information about a YouTube channel. ## Methods The API supports the following methods for `channels` resources: [list](https://developers.google.com/youtube/v3/docs/channels/list) : Returns a collection of zero or more **channel** resources that match the request criteria. [Try it now](https://developers.google.com/youtube/v3/docs/channels/list#usage). [update](https://developers.google.com/youtube/v3/docs/channels/update) : 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. [Try it now](https://developers.google.com/youtube/v3/docs/channels/update#usage). ## Resource representation The following JSON structure shows the format of a `channels` resource: ```gdscript { "https://developers.google.com/youtube/v3/docs/channels#kind": "youtube#channel", "https://developers.google.com/youtube/v3/docs/channels#etag": etag, "https://developers.google.com/youtube/v3/docs/channels#id": string, "https://developers.google.com/youtube/v3/docs/channels#snippet": { "https://developers.google.com/youtube/v3/docs/channels#snippet.title": string, "https://developers.google.com/youtube/v3/docs/channels#snippet.description": string, "https://developers.google.com/youtube/v3/docs/channels#snippet.customUrl": string, "https://developers.google.com/youtube/v3/docs/channels#snippet.publishedAt": datetime, "https://developers.google.com/youtube/v3/docs/channels#snippet.thumbnails": { (key): { "https://developers.google.com/youtube/v3/docs/channels#snippet.thumbnails.(key).url": string, "https://developers.google.com/youtube/v3/docs/channels#snippet.thumbnails.(key).width": unsigned integer, "https://developers.google.com/youtube/v3/docs/channels#snippet.thumbnails.(key).height": unsigned integer } }, "https://developers.google.com/youtube/v3/docs/channels#snippet.defaultLanguage": string, "https://developers.google.com/youtube/v3/docs/channels#snippet.localized": { "https://developers.google.com/youtube/v3/docs/channels#snippet.localized.title": string, "https://developers.google.com/youtube/v3/docs/channels#snippet.localized.description": string }, "https://developers.google.com/youtube/v3/docs/channels#snippet.country": string }, "https://developers.google.com/youtube/v3/docs/channels#contentDetails": { "https://developers.google.com/youtube/v3/docs/channels#contentDetails.relatedPlaylists": { "https://developers.google.com/youtube/v3/docs/channels#contentDetails.relatedPlaylists.likes": string, "https://developers.google.com/youtube/v3/docs/channels#contentDetails.relatedPlaylists.favorites": string, "https://developers.google.com/youtube/v3/docs/channels#contentDetails.relatedPlaylists.uploads": string } }, "https://developers.google.com/youtube/v3/docs/channels#statistics": { "https://developers.google.com/youtube/v3/docs/channels#statistics.viewCount": unsigned long, "https://developers.google.com/youtube/v3/docs/channels#statistics.subscriberCount": unsigned long, // this value is rounded to three significant figures "https://developers.google.com/youtube/v3/docs/channels#statistics.hiddenSubscriberCount": boolean, "https://developers.google.com/youtube/v3/docs/channels#statistics.videoCount": unsigned long }, "https://developers.google.com/youtube/v3/docs/channels#topicDetails": { "https://developers.google.com/youtube/v3/docs/channels#topicDetails.topicIds[]": [ string ], "https://developers.google.com/youtube/v3/docs/channels#topicDetails.topicCategories[]": [ string ] }, "https://developers.google.com/youtube/v3/docs/channels#status": { "https://developers.google.com/youtube/v3/docs/channels#status.privacyStatus": string, "https://developers.google.com/youtube/v3/docs/channels#status.isLinked": boolean, "https://developers.google.com/youtube/v3/docs/channels#status.longUploadsStatus": string, "https://developers.google.com/youtube/v3/docs/channels#status.madeForKids": boolean, "https://developers.google.com/youtube/v3/docs/channels#status.selfDeclaredMadeForKids": boolean }, "https://developers.google.com/youtube/v3/docs/channels#brandingSettings": { "https://developers.google.com/youtube/v3/docs/channels#brandingSettings.channel": { "https://developers.google.com/youtube/v3/docs/channels#brandingSettings.channel.title": string, "https://developers.google.com/youtube/v3/docs/channels#brandingSettings.channel.description": string, "https://developers.google.com/youtube/v3/docs/channels#brandingSettings.channel.keywords": string, "https://developers.google.com/youtube/v3/docs/channels#brandingSettings.channel.trackingAnalyticsAccountId": string, "https://developers.google.com/youtube/v3/docs/channels#brandingSettings.channel.unsubscribedTrailer": string, "https://developers.google.com/youtube/v3/docs/channels#brandingSettings.channel.defaultLanguage": string, "https://developers.google.com/youtube/v3/docs/channels#brandingSettings.channel.country": string }, "https://developers.google.com/youtube/v3/docs/channels#brandingSettings.watch": { "https://developers.google.com/youtube/v3/docs/channels#brandingSettings.watch.textColor": string, "https://developers.google.com/youtube/v3/docs/channels#brandingSettings.watch.backgroundColor": string, "https://developers.google.com/youtube/v3/docs/channels#brandingSettings.watch.featuredPlaylistId": string } }, "https://developers.google.com/youtube/v3/docs/channels#auditDetails": { "https://developers.google.com/youtube/v3/docs/channels#auditDetails.overallGoodStanding": boolean, "https://developers.google.com/youtube/v3/docs/channels#auditDetails.communityGuidelinesGoodStanding": boolean, "https://developers.google.com/youtube/v3/docs/channels#auditDetails.copyrightStrikesGoodStanding": boolean, "https://developers.google.com/youtube/v3/docs/channels#auditDetails.contentIdClaimsGoodStanding": boolean }, "https://developers.google.com/youtube/v3/docs/channels#contentOwnerDetails": { "https://developers.google.com/youtube/v3/docs/channels#contentOwnerDetails.contentOwner": string, "https://developers.google.com/youtube/v3/docs/channels#contentOwnerDetails.timeLinked": datetime }, "https://developers.google.com/youtube/v3/docs/channels#localizations": { (key): { "https://developers.google.com/youtube/v3/docs/channels#localizations.(key).title": string, "https://developers.google.com/youtube/v3/docs/channels#localizations.(key).description": 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#channel`. | | `etag` | `etag` The Etag of this resource. | | `id` | `string` The ID that YouTube uses to uniquely identify the channel. | | `snippet` | `object` The `snippet` object contains basic details about the channel, such as its title, description, and thumbnail images. | | snippet.`title` | `string` The channel's title. | | snippet.`description` | `string` The channel's description. The property's value has a maximum length of 1000 characters. | | snippet.`customUrl` | `string` The channel's custom URL. The [YouTube Help Center](https://support.google.com/youtube/answer/2657968) explains eligibility requirements for getting a custom URL as well as how to set up the URL. | | snippet.`publishedAt` | `datetime` The date and time that the channel was created. The value is specified in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format. | | snippet.`thumbnails` | `object` A map of thumbnail images associated with the channel. 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. When displaying thumbnails in your application, make sure that your code uses the image URLs exactly as they are returned in API responses. For example, your application should not use the `http` domain instead of the `https` domain in a URL returned in an API response. Channel thumbnail URLs are available only in the `https` domain, which is how the URLs appear in API responses. You might see broken images in your application if it tries to load YouTube images from the `http` domain. Thumbnail images might be empty for newly created channels and might take up to one day to populate. | | 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. For additional guidelines on using thumbnail URLs in your application, see the [snippet.thumbnails](https://developers.google.com/youtube/v3/docs/channels#snippet.thumbnails) property definition. | | snippet.thumbnails.(key).`width` | `unsigned integer` The image's width. | | snippet.thumbnails.(key).`height` | `unsigned integer` The image's height. | | snippet.`defaultLanguage` | `string` The language of the text in the `channel` resource's `snippet.title` and `snippet.description` properties. | | snippet.`localized` | `object` The `snippet.localized` object contains a localized title and description for the channel or it contains the channel's title and description in the [default language](https://developers.google.com/youtube/v3/docs/channels#snippet.defaultLanguage) for the channel's metadata. - Localized text is returned in the resource snippet if the [channels.list](https://developers.google.com/youtube/v3/docs/channels/list) request used the `hl` parameter to specify a language for which localized text should be returned, the `hl` parameter value identifies a [YouTube application language](https://developers.google.com/youtube/v3/docs/i18nLanguages), and localized text is available in that language. - Metadata for the default language is returned if an `hl` parameter value is not specified *or* a value is specified but localized metadata is not available for the specified language. The property contains a read-only value. Use the [localizations](https://developers.google.com/youtube/v3/docs/channels#localizations) object to add, update, or delete localized metadata. | | snippet.localized.`title` | `string` The localized channel title. | | snippet.localized.`description` | `string` The localized channel description. | | snippet.`country` | `string` The country with which the channel is associated. To set this property's value, update the value of the [brandingSettings.channel.country](https://developers.google.com/youtube/v3/docs/channels#brandingSettings.channel.country) property. | | `contentDetails` | `object` The `contentDetails` object encapsulates information about the channel's content. | | contentDetails.`relatedPlaylists` | `object` The `relatedPlaylists` object is a map that identifies playlists associated with the channel, such as the channel's uploaded videos or liked videos. You can retrieve any of these playlists using the [playlists.list](https://developers.google.com/youtube/v3/docs/playlists/list) method. | | contentDetails.relatedPlaylists.`likes` | `string` The ID of the playlist that contains the channel's liked videos. Use the [playlistItems.insert](https://developers.google.com/youtube/v3/docs/playlistItems/insert) and [playlistItems.delete](https://developers.google.com/youtube/v3/docs/playlistItems/delete) methods to add or remove items from that list. | | contentDetails.relatedPlaylists.`favorites` | `string` This property has been deprecated. The ID of the playlist that contains the channel's favorite videos. Use the [playlistItems.insert](https://developers.google.com/youtube/v3/docs/playlistItems/insert) and [playlistItems.delete](https://developers.google.com/youtube/v3/docs/playlistItems/delete) methods to add or remove items from that list. Note that YouTube has deprecated favorite video functionality. For example, the `video` resource's `statistics.favoriteCount` property was deprecated on August 28, 2015. As a result, for historical reasons, this property value might contain a playlist ID that refers to an empty playlist and, therefore, cannot be fetched. | | contentDetails.relatedPlaylists.`uploads` | `string` The ID of the playlist that contains the channel's uploaded videos. Use the [videos.insert](https://developers.google.com/youtube/v3/docs/videos/insert) method to upload new videos and the [videos.delete](https://developers.google.com/youtube/v3/docs/videos/delete) method to delete previously uploaded videos. | | `statistics` | `object` The `statistics` object encapsulates statistics for the channel. | | statistics.`viewCount` | `unsigned long` The sum of the number of times all the videos in all formats have been viewed for a channel. Starting March 31, 2025, for Shorts on a channel, viewCount will be updated to include the number of times a Short starts to play or replay. | | statistics.`commentCount` | `unsigned long` This property has been deprecated. The number of comments for the channel. | | statistics.`subscriberCount` | `unsigned long` The number of subscribers that the channel has. This value is rounded down to three significant figures. For more details about how subscriber counts are rounded, see [Revision History](https://developers.google.com/youtube/v3/revision_history#release_notes_09_10_2019) or [YouTube Help Center](https://support.google.com/youtube/answer/6051134). | | statistics.`hiddenSubscriberCount` | `boolean` Indicates whether the channel's subscriber count is publicly visible. | | statistics.`videoCount` | `unsigned long` The number of public videos uploaded to the channel. Note that the value reflects the count of the channel's public videos only, even to owners. This behavior is consistent with counts shown on the YouTube website. | | `topicDetails` | `object` The `topicDetails` object encapsulates information about topics associated with the channel. **Important:** For more details about changes related to topic IDs, see the `topicDetails.topicIds[]` property definition and the [revision history](https://developers.google.com/youtube/v3/revision_history#november-10-2016). | | topicDetails.`topicIds[]` | `list` A list of topic IDs associated with the channel. This property has been deprecated as of November 10, 2016. It will be supported until November 10, 2017. **Important:** Due to the deprecation of Freebase and the Freebase API, topic IDs started working differently as of February 27, 2017. At that time, YouTube started returning a small set of curated topic IDs. [See topic IDs supported as of February 15, 2017](https://developers.google.com/youtube/v3/docs/channels#) | Topics || |------------|------------------------------------| | **Music topics** || | /m/04rlf | Music (parent topic) | | /m/02mscn | Christian music | | /m/0ggq0m | Classical music | | /m/01lyv | Country | | /m/02lkt | Electronic music | | /m/0glt670 | Hip hop music | | /m/05rwpb | Independent music | | /m/03_d0 | Jazz | | /m/028sqc | Music of Asia | | /m/0g293 | Music of Latin America | | /m/064t9 | Pop music | | /m/06cqb | Reggae | | /m/06j6l | Rhythm and blues | | /m/06by7 | Rock music | | /m/0gywn | Soul music | | **Gaming topics** || | /m/0bzvm2 | Gaming (parent topic) | | /m/025zzc | Action game | | /m/02ntfj | Action-adventure game | | /m/0b1vjn | Casual game | | /m/02hygl | Music video game | | /m/04q1x3q | Puzzle video game | | /m/01sjng | Racing video game | | /m/0403l3g | Role-playing video game | | /m/021bp2 | Simulation video game | | /m/022dc6 | Sports game | | /m/03hf_rm | Strategy video game | | **Sports topics** || | /m/06ntj | Sports (parent topic) | | /m/0jm_ | American football | | /m/018jz | Baseball | | /m/018w8 | Basketball | | /m/01cgz | Boxing | | /m/09xp_ | Cricket | | /m/02vx4 | Football | | /m/037hz | Golf | | /m/03tmr | Ice hockey | | /m/01h7lh | Mixed martial arts | | /m/0410tth | Motorsport | | /m/07bs0 | Tennis | | /m/07_53 | Volleyball | | **Entertainment topics** || | /m/02jjt | Entertainment (parent topic) | | /m/09kqc | Humor | | /m/02vxn | Movies | | /m/05qjc | Performing arts | | /m/066wd | Professional wrestling | | /m/0f2f9 | TV shows | | **Lifestyle topics** || | /m/019_rr | Lifestyle (parent topic) | | /m/032tl | Fashion | | /m/027x7n | Fitness | | /m/02wbm | Food | | /m/03glg | Hobby | | /m/068hy | Pets | | /m/041xxh | Physical attractiveness \[Beauty\] | | /m/07c1v | Technology | | /m/07bxq | Tourism | | /m/07yv9 | Vehicles | | **Society topics** || | /m/098wr | Society (parent topic) | | /m/09s1f | Business | | /m/0kt51 | Health | | /m/01h6rj | Military | | /m/05qt0 | Politics | | /m/06bvp | Religion | | **Other topics** || | /m/01k8wb | Knowledge | | | topicDetails.`topicCategories[]` | `list` A list of Wikipedia URLs that describe the channel's content. | | `status` | `object` The `status` object encapsulates information about the privacy status of the channel. | | status.`privacyStatus` | `string` Privacy status of the channel. Valid values for this property are: - `private` - `public` - `unlisted` | | status.`isLinked` | `boolean` Indicates whether the channel data identifies a user that is already linked to either a YouTube username or a Google+ account. A user that has one of these links already has a public YouTube identity, which is a prerequisite for several actions, such as uploading videos. | | status.`longUploadsStatus` | `string` Indicates whether the channel is eligible to upload videos that are more than 15 minutes long. This property is only returned if the channel owner authorized the API request. For more information about this feature, see [YouTube Help Center](https://support.google.com/youtube/answer/71673). Valid values for this property are: - `allowed` -- This channel can upload videos that are more than 15 minutes long. - `disallowed` -- This channel is not able or eligible to upload videos that are more than 15 minutes long. A channel is only eligible to upload long videos if it is in good standing based on [YouTube Community Guidelines](http://www.youtube.com/t/community_guidelines) and it does not have any worldwide Content ID blocks on its content. After the channel owner resolves the issues that are preventing the channel from uploading longer videos, the channel will revert to either the `allowed` or `eligible` state. - `eligible` -- This channel is eligible to upload videos that are more than 15 minutes long. However, the channel owner must first enable the ability to upload longer videos through [Phone verification](https://www.youtube.com/verify). For more details about this feature, see [YouTube Help Center](https://support.google.com/youtube/answer/71673). | | status.`madeForKids` | `boolean` This value indicates whether the channel is designated as child-directed, and it contains the current "made for kids" status of the channel. For example, the status might be determined based on the value of the `selfDeclaredMadeForKids` property. For more information about setting the audience for your channel, videos, or broadcasts, see [YouTube Help Center](https://support.google.com/youtube/answer/9527654) . | | status.`selfDeclaredMadeForKids` | `boolean` In a [channels.update](https://developers.google.com/youtube/v3/docs/channels/update) request, this property allows the channel owner to designate the channel as child-directed. The property value is only returned if the channel owner authorized the API request. | | `brandingSettings` | `object` The `brandingSettings` object encapsulates information about the branding of the channel. | | brandingSettings.`channel` | `object` The `channel` object encapsulates branding properties of the channel page. | | brandingSettings.channel.`title` | `string` The channel's title. The title has a maximum length of 30 characters. | | brandingSettings.channel.`description` | `string` The channel description, which appears in the channel information box on your channel page. The property's value has a maximum length of 1000 characters. | | brandingSettings.channel.`keywords` | `string` Keywords associated with your channel. The value is a space-separated list of strings. Channel keywords might be truncated if they exceed the maximum allowed length of 500 characters or if they contained unescaped quotation marks (`"`). Note that the 500 character limit is not a per-keyword limit but rather a limit on the total length of all keywords. | | brandingSettings.channel.`trackingAnalyticsAccountId` | `string` The ID for a [Google Analytics account](http://www.google.com/analytics/index.html) that you want to use to track and measure traffic to your channel. | | brandingSettings.channel.`unsubscribedTrailer` | `string` The video that should play in the featured video module in the channel page's browse view for unsubscribed viewers. Subscribed viewers may see a different video that highlights more recent channel activity. If specified, the property's value must be the YouTube video ID of a public or unlisted video that is owned by the channel owner. | | brandingSettings.channel.`defaultLanguage` | `string` The language of the text in the `channel` resource's `snippet.title` and `snippet.description` properties. | | brandingSettings.channel.`country` | `string` The country with which the channel is associated. Update this property to set the value of the [snippet.country](https://developers.google.com/youtube/v3/docs/channels#snippet.country) property. | | brandingSettings.`watch` | `object` **Note:** This object and all of its child properties have been deprecated. The `watch` object encapsulates branding properties of the watch pages for the channel's videos. | | brandingSettings.watch.`textColor` | `string` **Note:** This property has been deprecated. The text color for the video watch page's branded area. | | brandingSettings.watch.`backgroundColor` | `string` **Note:** This property has been deprecated. The background color for the video watch page's branded area. | | brandingSettings.watch.`featuredPlaylistId` | `string` **Note:** This property has been deprecated. The API returns an error if you attempt to set its value. | | brandingSettings.`image` | `object` This property and all of its child properties have been deprecated. The `image` object encapsulates information about images that display on the channel's channel page or video watch pages. | | brandingSettings.image.`bannerImageUrl` | `string` This property has been deprecated. The URL for the banner image shown on the channel page on the YouTube website. The image is 1060px by 175px. | | brandingSettings.image.`bannerMobileImageUrl` | `string` This property has been deprecated. The URL for the banner image shown on the channel page in mobile applications. The image is 640px by 175px. | | brandingSettings.image.`watchIconImageUrl` | `string` This property has been deprecated. The URL for the image that appears above the video player. This is a 25-pixel-high image with a flexible width that cannot exceed 170 pixels. If you do not provide this image, your channel name will appear instead of an image. | | brandingSettings.image.`trackingImageUrl` | `string` This property has been deprecated. The URL for a 1px by 1px tracking pixel that can be used to collect statistics for views of the channel or video pages. | | brandingSettings.image.`bannerTabletLowImageUrl` | `string` This property has been deprecated. The URL for a low-resolution banner image that displays on the channel page in tablet applications. The image's maximum size is 1138px by 188px. | | brandingSettings.image.`bannerTabletImageUrl` | `string` This property has been deprecated. The URL for a banner image that displays on the channel page in tablet applications. The image is 1707px by 283px. | | brandingSettings.image.`bannerTabletHdImageUrl` | `string` This property has been deprecated. The URL for a high-resolution banner image that displays on the channel page in tablet applications. The image's maximum size is 2276px by 377px. | | brandingSettings.image.`bannerTabletExtraHdImageUrl` | `string` This property has been deprecated. The URL for an extra-high-resolution banner image that displays on the channel page in tablet applications. The image's maximum size is 2560px by 424px. | | brandingSettings.image.`bannerMobileLowImageUrl` | `string` This property has been deprecated. The URL for a low-resolution banner image that displays on the channel page in mobile applications. The image's maximum size is 320px by 88px. | | brandingSettings.image.`bannerMobileMediumHdImageUrl` | `string` This property has been deprecated. The URL for a medium-resolution banner image that displays on the channel page in mobile applications. The image's maximum size is 960px by 263px. | | brandingSettings.image.`bannerMobileHdImageUrl` | `string` This property has been deprecated. The URL for a high-resolution banner image that displays on the channel page in mobile applications. The image's maximum size is 1280px by 360px. | | brandingSettings.image.`bannerMobileExtraHdImageUrl` | `string` This property has been deprecated. The URL for a very high-resolution banner image that displays on the channel page in mobile applications. The image's maximum size is 1440px by 395px. | | brandingSettings.image.`bannerTvImageUrl` | `string` This property has been deprecated. The URL for an extra-high-resolution banner image that displays on the channel page in television applications. The image's maximum size is 2120px by 1192px. | | brandingSettings.image.`bannerTvLowImageUrl` | `string` This property has been deprecated. The URL for a low-resolution banner image that displays on the channel page in television applications. The image's maximum size is 854px by 480px. | | brandingSettings.image.`bannerTvMediumImageUrl` | `string` This property has been deprecated. The URL for a medium-resolution banner image that displays on the channel page in television applications. The image's maximum size is 1280px by 720px. | | brandingSettings.image.`bannerTvHighImageUrl` | `string` This property has been deprecated. The URL for a high-resolution banner image that displays on the channel page in television applications. The image's maximum size is 1920px by 1080px. | | brandingSettings.image.`bannerExternalUrl` | `string` This property specifies the location of the banner image that YouTube uses to generate the various banner image sizes for a channel. | | brandingSettings.`hints[]` | `list` This property and all of its child properties have been deprecated. The `hints` object encapsulates additional branding properties. | | brandingSettings.hints[].`property` | `string` This property has been deprecated. A property. | | brandingSettings.hints[].`value` | `string` This property has been deprecated. The property's value. | | `auditDetails` | `object` The `auditDetails` object encapsulates channel data that a multichannel network (MCN) would evaluate while determining whether to accept or reject a particular channel. Note that any API request that retrieves this resource part must provide an authorization token that contains the `https://www.googleapis.com/auth/youtubepartner-channel-audit` scope. In addition, any token that uses that scope must be revoked when the MCN decides to accept or reject the channel or within two weeks of the date that the token was issued. | | auditDetails.`overallGoodStanding` | `boolean` This field indicates whether there are any issues with the channel. Currently, this field represents the result of the logical `AND` operation over the `communityGuidelinesGoodStanding`, `copyrightStrikesGoodStanding`, and `contentIdClaimsGoodStanding` properties, meaning that this property has a value of `true` if all of those other properties also have a value of `true`. However, this property will have a value of `false` if any of those properties has a value of `false`. Note, however, that the methodology used to set this property's value is subject to change. | | auditDetails.`communityGuidelinesGoodStanding` | `boolean` Indicates whether the channel respects YouTube's community guidelines. | | auditDetails.`copyrightStrikesGoodStanding` | `boolean` Indicates whether the channel has any copyright strikes. | | auditDetails.`contentIdClaimsGoodStanding` | `boolean` Indicates whether the channel has any unresolved claims. | | `contentOwnerDetails` | `object` The `contentOwnerDetails` object encapsulates channel data that is visible only to the YouTube Partner that has linked the channel to their Content Manager. | | contentOwnerDetails.`contentOwner` | `string` The ID of the content owner linked to the channel. | | contentOwnerDetails.`timeLinked` | `datetime` The date and time of when the channel was linked to the content owner. The value is specified in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format. | | `localizations` | `object` The `localizations` object encapsulates translations of the channel's metadata. | | localizations.`(key)` | `object` The language of the localized metadata associated with the key value. The value is a string that contains a [BCP-47](http://www.rfc-editor.org/rfc/bcp/bcp47.txt) language code. | | localizations.(key).`title` | `string` The localized channel title. | | localizations.(key).`description` | `string` The localized channel description. | --- # Source: https://developers.google.com/youtube/v3/docs/channels/list.md.txt # Channels: list **Note:** The `channel` resource's [statistics.subscriberCount](https://developers.google.com/youtube/v3/docs/channels#statistics.subscriberCount) property value has been updated to reflect a YouTube policy change that affects the way that subscriber counts are displayed. For more information, see [Revision History](https://developers.google.com/youtube/v3/revision_history#release_notes_09_10_2019) or the [YouTube Help Center](https://support.google.com/youtube/answer/6051134). Returns a collection of zero or more **channel** resources that match the request criteria. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 1 unit. ## Common use cases The list below shows common use cases for this method. Hover over a use case to see its description, or click on a use case to load sample parameter values in the APIs Explorer. You can open the [fullscreen APIs Explorer](https://developers.google.com/youtube/v3/docs/channels/list#) to see code samples that dynamically update to reflect the parameter values entered in the Explorer. The table below shows common use cases for this method. You can click on a use case name to load sample parameter values in the APIs Explorer. Or you can see code samples for a use case in the fullscreen APIs Explorer by clicking on the code icon below a use case name. In the fullscreen UI, you can update parameter and property values and the code samples will dynamically update to reflect the values you enter. This method has one common use case, which is described below. The buttons below the description populate the APIs Explorer with sample values or open the fullscreen APIs Explorer to show code samples that use those values. The code samples also dynamically update if you change the values.
## Request ### HTTP request ``` GET https://www.googleapis.com/youtube/v3/channels ``` ### Authorization A request that retrieves the `auditDetails` part for a `channel` resource must provide an authorization token that contains the `https://www.googleapis.com/auth/youtubepartner-channel-audit` scope. In addition, any token that uses that scope must be revoked when the MCN decides to accept or reject the channel or within two weeks of the date that the token was issued. ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters || |--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---| | **Required parameters** ||| | `part` | `string` The **part** parameter specifies a comma-separated list of one or more `channel` resource properties that the API response will include. If the parameter identifies a property that contains child properties, the child properties will be included in the response. For example, in a `channel` resource, the `contentDetails` property contains other properties, such as the `uploads` properties. As such, if you set **part=contentDetails**, the API response will also contain all of those nested properties. The following list contains the `part` names that you can include in the parameter value: - `auditDetails` - `brandingSettings` - `contentDetails` - `contentOwnerDetails` - `id` - `localizations` - `snippet` - `statistics` - `status` - `topicDetails` | | **Filters (specify exactly one of the following parameters)** ||| | `categoryId` | `string` This parameter has been deprecated. The **categoryId** parameter specified a [YouTube guide category](https://developers.google.com/youtube/v3/docs/guideCategories) and could be used to request YouTube channels associated with that category. | | `forHandle` | `string` The **forHandle** parameter specifies a YouTube handle, thereby requesting the channel associated with that handle. The parameter value can be prepended with an `@` symbol. For example, to retrieve the resource for the "Google for Developers" channel, set the `forHandle` parameter value to either `GoogleDevelopers` or `@GoogleDevelopers`. | | `forUsername` | `string` The **forUsername** parameter specifies a YouTube username, thereby requesting the channel associated with that username. | | `id` | `string` The **id** parameter specifies a comma-separated list of the YouTube channel ID(s) for the resource(s) that are being retrieved. In a `channel` resource, the `id` property specifies the channel's YouTube channel ID. | | `managedByMe` | `boolean` This parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication). **Note:** This parameter is intended exclusively for YouTube content partners. Set this parameter's value to `true` to instruct the API to only return channels managed by the content owner that the **onBehalfOfContentOwner** parameter specifies. The user must be authenticated as a CMS account linked to the specified content owner and **onBehalfOfContentOwner** must be provided. | | `mine` | `boolean` This parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication). Set this parameter's value to `true` to instruct the API to only return channels owned by the authenticated user. | | **Optional parameters** ||| | `hl` | `string` The **hl** parameter instructs the API to retrieve localized resource metadata for a specific [application language that the YouTube website supports](https://developers.google.com/youtube/v3/docs/i18nLanguages). The parameter value must be a language code included in the list returned by the [i18nLanguages.list](https://developers.google.com/youtube/v3/docs/i18nLanguages/list) method. If localized resource details are available in that language, the resource's `snippet.localized` object will contain the localized values. However, if localized details are not available, the `snippet.localized` object will contain resource details in the resource's [default language](https://developers.google.com/youtube/v3/docs/channels#snippet.defaultLanguage). | | `maxResults` | `unsigned integer` The **maxResults** parameter specifies the maximum number of items that should be returned in the result set. Acceptable values are `0` to `50`, inclusive. The default value is `5`. | | `onBehalfOfContentOwner` | `string` This parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication). **Note:** This parameter is intended exclusively for YouTube content partners. The **onBehalfOfContentOwner** parameter indicates that the request's authorization credentials identify a YouTube CMS user who is acting on behalf of the content owner specified in the parameter value. This parameter is intended for YouTube content partners that own and manage many different YouTube channels. It allows content owners to authenticate once and get access to all their video and channel data, without having to provide authentication credentials for each individual channel. The CMS account that the user authenticates with must be linked to the specified YouTube content owner. | | `pageToken` | `string` The **pageToken** parameter identifies a specific page in the result set that should be returned. In an API response, the `nextPageToken` and `prevPageToken` properties identify other pages that could be retrieved. | ### Request body Do not provide a request body when calling this method. ## Response If successful, this method returns a response body with the following structure: ```objective-c { "kind": "youtube#channelListResponse", "etag": etag, "nextPageToken": string, "prevPageToken": string, "pageInfo": { "totalResults": integer, "resultsPerPage": integer }, "items": [ channel Resource ] } ``` ### 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#channelListResponse`. | | `etag` | `etag` The Etag of this resource. | | `nextPageToken` | `string` The token that can be used as the value of the `pageToken` parameter to retrieve the next page in the result set. | | `prevPageToken` | `string` The token that can be used as the value of the `pageToken` parameter to retrieve the previous page in the result set. Note that this property is not included in the API response if the corresponding API request set the [managedByMe](https://developers.google.com/youtube/v3/docs/channels/list#managedByMe) parameter to `true`. | | `pageInfo` | `object` The `pageInfo` object encapsulates paging information for the result set. | | pageInfo.`totalResults` | `integer` The total number of results in the result set. | | pageInfo.`resultsPerPage` | `integer` The number of results included in the API response. | | `items[]` | `list` A list of channels that match the request criteria. | ## Errors The following table identifies error messages that the API could return in response to a call to this method. For more details, see [YouTube Data API - Errors](https://developers.google.com/youtube/v3/docs/errors). | Error type | Error detail | Description | |--------------------|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `invalidCriteria` | A maximum of one of the following filters may be specified:`id`, `categoryId`, `mine`, `managedByMe`, `forHandle`, `forUsername`. In case of content owner authentication via the `onBehalfOfContentOwner` parameter, only the `id` or `managedByMe` may be specified. | | `forbidden (403)` | `channelForbidden` | The channel specified by the `id` parameter does not support the request or the request is not properly authorized. | | `notFound (404)` | `categoryNotFound` | The category identified by the `categoryId` parameter cannot be found. Use the [guideCategories.list](https://developers.google.com/youtube/v3/docs/guideCategories/list) method to retrieve a list of valid values. | | `notFound (404)` | `channelNotFound` | The channel specified in the `id` parameter cannot be found. | ## Try it! Use the APIs Explorer to call this API and see the API request and response. --- # Source: https://developers.google.com/youtube/v3/docs/channels/update.md.txt # Channels: update The API now supports the ability to mark your [channel](https://developers.google.com/youtube/v3/docs/channels) or [videos](https://developers.google.com/youtube/v3/docs/videos) as "made for kids." In addition, `channel` and `video` resources also now contain a property that identifies the "made for kids" status of that channel or video. The YouTube API Services Terms of Service and Developer Policies were also updated on 10 January 2020. For more information, see the revision histories for the [YouTube Data API Service](https://developers.google.com/youtube/v3/revision_history) and the [YouTube API Services Terms of Service](https://developers.google.com/youtube/terms/revision-history). Updates a channel's metadata. Note that this method only supports updates to the `channel` resource's `brandingSettings`, `invideoPromotion`, and `localizations` objects and their child properties. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 50 units. ## Common use cases The list below shows common use cases for this method. Hover over a use case to see its description, or click on a use case to load sample parameter values in the APIs Explorer. You can open the [fullscreen APIs Explorer](https://developers.google.com/youtube/v3/docs/channels/update#) to see code samples that dynamically update to reflect the parameter values entered in the Explorer. The table below shows common use cases for this method. You can click on a use case name to load sample parameter values in the APIs Explorer. Or you can see code samples for a use case in the fullscreen APIs Explorer by clicking on the code icon below a use case name. In the fullscreen UI, you can update parameter and property values and the code samples will dynamically update to reflect the values you enter. This method has one common use case, which is described below. The buttons below the description populate the APIs Explorer with sample values or open the fullscreen APIs Explorer to show code samples that use those values. The code samples also dynamically update if you change the values.
## Request ### HTTP request ``` PUT https://www.googleapis.com/youtube/v3/channels ``` ### Authorization This request requires authorization with at least one of the following scopes. To read more about authentication and authorization, see [Implementing OAuth 2.0 authorization](https://developers.google.com/youtube/v3/guides/authentication). | Scope | |-----------------------------------------------------| | `https://www.googleapis.com/auth/youtubepartner` | | `https://www.googleapis.com/auth/youtube` | | `https://www.googleapis.com/auth/youtube.force-ssl` | ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters || |--------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---| | **Required parameters** ||| | `part` | `string` The **part** parameter serves two purposes in this operation. It identifies the properties that the write operation will set as well as the properties that the API response will include. The API only allows the parameter value to be set to either `brandingSettings`, `invideoPromotion`, or `localizations`. (You can only update any one of those parts with a single request.) Note that this method overrides the existing values for all of the mutable properties that are contained in the part that the parameter value specifies. | | **Optional parameters** ||| | `onBehalfOfContentOwner` | `string` This parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication). The **onBehalfOfContentOwner** parameter indicates that the authenticated user is acting on behalf of the content owner specified in the parameter value. This parameter is intended for YouTube content partners that own and manage many different YouTube channels. It allows content owners to authenticate once and get access to all their video and channel data, without having to provide authentication credentials for each individual channel. The actual CMS account that the user authenticates with needs to be linked to the specified YouTube content owner. | ### Request body Provide a [channel](https://developers.google.com/youtube/v3/docs/channels#resource) resource in the request body. For that resource: - You must specify a value for these properties: - `id` - You can set values for these properties: - `brandingSettings.channel.country` - `brandingSettings.channel.description` - `brandingSettings.channel.defaultLanguage` - `brandingSettings.channel.keywords` - `brandingSettings.channel.trackingAnalyticsAccountId` - `brandingSettings.channel.unsubscribedTrailer` - `localizations.(key)` - `localizations.(key).title` - `localizations.(key).description` - `status.selfDeclaredMadeForKids` If you are submitting an update request, and your request does not specify a value for a property that already has a value, the property's existing value will be deleted. ## Response If successful, this method returns a [channel](https://developers.google.com/youtube/v3/docs/channels#resource) resource in the response body. ## Errors The following table identifies error messages that the API could return in response to a call to this method. Fore more details, see [YouTube Data API - Errors](https://developers.google.com/youtube/v3/docs/errors). | Error type | Error detail | Description | |--------------------|-------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `brandingValidationError` | One of the values in the `brandingSettings` object failed validation. Use the [channels.list](https://developers.google.com/youtube/v3/docs/channels/list) method to retrieve the existing settings for the channel, and update the property values following the guidelines in the [channels](https://developers.google.com/youtube/v3/docs/channels#resource) resource documentation. | | `badRequest (400)` | `channelTitleUpdateForbidden` | When updating a channel's `brandingSettings part`, you must set the `brandingSettings.channel.title` property's value to the channel's current title or omit the property. The API returns an error if you change the property's value. | | `badRequest (400)` | `defaultLanguageNotSetError` | The `defaultLanguage` must be set to update `localizations`. | | `badRequest (400)` | `invalidBrandingOption` | One of the branding settings that you specified does not exist. Use the [channels.list](https://developers.google.com/youtube/v3/docs/channels/list) method to retrieve valid values and make sure to update them following the guidelines in the [channels](https://developers.google.com/youtube/v3/docs/channels#resource) resource documentation. | | `badRequest (400)` | `invalidCustomMessage` | The request metadata specifies an invalid custom message. Check the value of the [invideoPromotion.items[].customMessage](https://developers.google.com/youtube/v3/docs/channels#invideoPromotion.items[].customMessage) property in the resource that the request sent. | | `badRequest (400)` | `invalidDuration` | The request metadata specifies an invalid duration in the invideoPromotion part. | | `badRequest (400)` | `invalidDuration` | The request metadata specifies an invalid position type for determining how the promoted item is positioned in the video player. Check the value of the [invideoPromotion.position.type](https://developers.google.com/youtube/v3/docs/channels#invideoPromotion.position.type) property in the resource that the request sent. | | `badRequest (400)` | `invalidRecentlyUploadedBy` | The request metadata specifies an invalid channel ID. Check the value of the [invideoPromotion.items[].id.recentlyUploadedBy](https://developers.google.com/youtube/v3/docs/channels#invideoPromotion.items[].id.recentlyUploadedBy) property in the resource that the request sent. | | `badRequest (400)` | `invalidTimingOffset` | The request metadata specifies an invalid timing offset in the invideoPromotion part. | | `badRequest (400)` | `invalidTimingOffset` | The request metadata specifies an invalid timing offset for determining when the promoted item should be displayed in the video player. Check the value of the [invideoPromotion.timing.offsetMs](https://developers.google.com/youtube/v3/docs/channels#invideoPromotion.timing.offsetMs) property in the resource that the request sent. | | `badRequest (400)` | `invalidTimingType` | The request metadata specifies an invalid timing method for determining when the promoted item should be displayed in the video player. Check the value of the [invideoPromotion.timing.type](https://developers.google.com/youtube/v3/docs/channels#invideoPromotion.timing.type) property in the resource that the request sent. | | `badRequest (400)` | `localizationValidationError` | One of the values in the localizations object failed validation. Use the [channels.list](https://developers.google.com/youtube/v3/docs/channels/list) method to retrieve valid values and make sure to update them following the guidelines in [the channels resource documentation.](https://developers.google.com/youtube/v3/docs/channels#resource) | | `badRequest (400)` | `tooManyPromotedItems` | Number of allowed promoted items exceeded in the invideoPromotion part. | | `forbidden (403)` | `channelForbidden` | The channel specified in the `id` parameter does not support the request or the request is not properly authorized. | | `forbidden (403)` | `promotedVideoNotAllowed` | The channel that the API request is attempting to update cannot be found. Check the value of the `id` property in the `channel` resource that the request sent to ensure that the channel ID is correct. | | `forbidden (403)` | `websiteLinkNotAllowed` | The specified website URL is not allowed. | | `notFound (404)` | `channelNotFound` | The channel specified in the `id` parameter cannot be found. | | `notFound (404)` | `channelNotFound` | The channel specified by the `id` parameter cannot be found or does not have branding options. | | `notFound (404)` | `unknownChannelId` | The specified channel ID was not found. | | `notFound (404)` | `unknownChannelId` | The specified recentlyUploadedBy channel ID was not found. | | `notFound (404)` | `unknownVideoId` | The [video ID](https://developers.google.com/youtube/v3/docs/channels#invideoPromotion.items[].videoId) specified as a promoted item cannot be found. | | `required (400)` | `requiredItemIdType` | The request metadata must specify an item type in the invideoPromotion part. | | `required (400)` | `requiredItemId` | The request metadata must specify an item id the invideoPromotion part. | | `required (400)` | `requiredTimingOffset` | The request metadata must specify a default timing offset so that YouTube can determine when to display the promoted item. Set the value of the [invideoPromotion.defaultTiming.offsetMs](https://developers.google.com/youtube/v3/docs/channels#invideoPromotion.defaultTiming.offsetMs) property in the resource that the request sends. | | `required (400)` | `requiredTimingOffset` | The request metadata must specify a timing offset so that YouTube can determine when to display the promoted item. Set the value of the [invideoPromotion.timing.offsetMs](https://developers.google.com/youtube/v3/docs/channels#invideoPromotion.timing.offsetMs) property in the resource that the request sends. | | `required (400)` | `requiredTimingType` | The request metadata must specify a timing method so that YouTube can determine when to display the promoted item. Set the value of the [invideoPromotion.defaultTiming.type](https://developers.google.com/youtube/v3/docs/channels#invideoPromotion.defaultTiming.type) property in the resource that the request sends. | | `required (400)` | `requiredTimingType` | The request metadata must specify a timing method so that YouTube can determine when to display the promoted item. Set the value of the [invideoPromotion.timing.type](https://developers.google.com/youtube/v3/docs/channels#invideoPromotion.timing.type) property in the resource that the request sends. | | `required (400)` | `requiredTiming` | The request metadata must specify a timing for each item in the `invideoPromotion` part. | | `required (400)` | `requiredVideoId` | The request metadata must specify a [video ID](https://developers.google.com/youtube/v3/docs/channels#invideoPromotion.items[].videoId) to identify the promoted item. | | `required (400)` | `requiredWebsiteUrl` | The request metadata must specify a website URL in the invideoPromotion part. Set the value of the [invideoPromotion.items[].id.websiteUrl](https://developers.google.com/youtube/v3/docs/channels#invideoPromotion.items[].id.websiteUrl) property in the resource that the request sends. | ## Try it! Use the APIs Explorer to call this API and see the API request and response. --- # Source: https://developers.google.com/youtube/v3/docs/commentThreads.md.txt # CommentThreads A **commentThread** resource contains information about a YouTube comment thread, which comprises a top-level comment and replies, if any exist, to that comment. A `commentThread` resource represents comments on a video. Both the top-level comment and the replies are actually [comment](https://developers.google.com/youtube/v3/docs/comments) resources nested inside the `commentThread` resource. The `commentThread` resource does not necessarily contain all replies to a comment, and you need to use the [comments.list](https://developers.google.com/youtube/v3/docs/comments/list) method if you want to retrieve all replies for a particular comment. Some comments don't have replies. ## Methods The API supports the following methods for `commentThreads` resources: [list](https://developers.google.com/youtube/v3/docs/commentThreads/list) : Returns a list of comment threads that match the API request parameters. [Try it now](https://developers.google.com/youtube/v3/docs/commentThreads/list#usage). [insert](https://developers.google.com/youtube/v3/docs/commentThreads/insert) : Creates a new top-level comment. To add a reply to an existing comment, use the [comments.insert](https://developers.google.com/youtube/v3/docs/comments/insert) method instead. [Try it now](https://developers.google.com/youtube/v3/docs/commentThreads/insert#usage). ## Resource representation The JSON structure shows the format of a `commentThreads` resource: ```objective-c { "https://developers.google.com/youtube/v3/docs/commentThreads#kind": "youtube#commentThread", "https://developers.google.com/youtube/v3/docs/commentThreads#etag": etag, "https://developers.google.com/youtube/v3/docs/commentThreads#id": string, "https://developers.google.com/youtube/v3/docs/commentThreads#snippet": { "https://developers.google.com/youtube/v3/docs/commentThreads#snippet.channelId": string, "https://developers.google.com/youtube/v3/docs/commentThreads#snippet.videoId": string, "https://developers.google.com/youtube/v3/docs/commentThreads#snippet.topLevelComment": comments Resource, "https://developers.google.com/youtube/v3/docs/commentThreads#snippet.canReply": boolean, "https://developers.google.com/youtube/v3/docs/commentThreads#snippet.totalReplyCount": unsigned integer, "https://developers.google.com/youtube/v3/docs/commentThreads#snippet.isPublic": boolean }, "https://developers.google.com/youtube/v3/docs/commentThreads#replies": { "https://developers.google.com/youtube/v3/docs/commentThreads#replies.comments[]": [ comments Resource ] } } ``` ### 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#commentThread`. | | `etag` | `etag` The Etag of this resource. | | `id` | `string` The ID that YouTube uses to uniquely identify the comment thread. | | `snippet` | `object` The `snippet` object contains basic details about the comment thread. It also contains the thread's top-level comment, which is a [comment](https://developers.google.com/youtube/v3/docs/comments) resource. | | snippet.`channelId` | `string` The YouTube channel that is associated with the comments in the thread. The `snippet.videoId` property identifies the video. | | snippet.`videoId` | `string` The ID of the video to which the comments refer. | | snippet.`topLevelComment` | `object` The thread's top-level comment. The property's value is a [comment](https://developers.google.com/youtube/v3/docs/comments#resource) resource. | | snippet.`canReply` | `boolean` This setting indicates whether the current viewer can reply to the thread. | | snippet.`totalReplyCount` | `unsigned integer` The total number of replies that have been submitted in response to the top-level comment. | | snippet.`isPublic` | `boolean` This setting indicates whether the thread, including all of its comments and comment replies, is visible to all YouTube users. | | `replies` | `object` The `replies` object is a container that contains a list of replies to the comment, if any exist. The `replies.comments` property represents the list of comments itself. | | replies.`comments[]` | `list` A list of one or more replies to the top-level comment. Each item in the list is a [comment](https://developers.google.com/youtube/v3/docs/comments#resource) resource. The list contains a limited number of replies, and unless the number of items in the list equals the value of the [snippet.totalReplyCount](https://developers.google.com/youtube/v3/docs/commentThreads#snippet.totalReplyCount) property, the list of replies is only a subset of the total number of replies available for the top-level comment. To retrieve all of the replies for the top-level comment, you need to call the [comments.list](https://developers.google.com/youtube/v3/docs/comments/list) method and use the `parentId` request parameter to identify the comment for which you want to retrieve replies. | --- # Source: https://developers.google.com/youtube/v3/docs/commentThreads/insert.md.txt # CommentThreads: insert Creates a new top-level comment. To add a reply to an existing comment, use the [comments.insert](https://developers.google.com/youtube/v3/docs/comments/insert) method instead. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 50 units. ## Common use cases The list below shows common use cases for this method. Hover over a use case to see its description, or click on a use case to load sample parameter values in the APIs Explorer. You can open the [fullscreen APIs Explorer](https://developers.google.com/youtube/v3/docs/commentThreads/insert#) to see code samples that dynamically update to reflect the parameter values entered in the Explorer. The table below shows common use cases for this method. You can click on a use case name to load sample parameter values in the APIs Explorer. Or you can see code samples for a use case in the fullscreen APIs Explorer by clicking on the code icon below a use case name. In the fullscreen UI, you can update parameter and property values and the code samples will dynamically update to reflect the values you enter. This method has one common use case, which is described below. The buttons below the description populate the APIs Explorer with sample values or open the fullscreen APIs Explorer to show code samples that use those values. The code samples also dynamically update if you change the values.
## Request ### HTTP request ``` POST https://www.googleapis.com/youtube/v3/commentThreads ``` ### Authorization This request requires authorization with at least one of the following scopes ([read more about authentication and authorization](https://developers.google.com/youtube/v3/guides/authentication)). | Scope | |-----------------------------------------------------| | `https://www.googleapis.com/auth/youtube.force-ssl` | ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters || |--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---| | **Required parameters** ||| | `part` | `string` The **part** parameter identifies the properties that the API response will include. Set the parameter value to `snippet`. The `snippet` part has a quota cost of 2 units. The following list contains the `part` names that you can include in the parameter value: - `id` - `replies` - `snippet` | ### Request body Provide a [commentThread resource](https://developers.google.com/youtube/v3/docs/commentThreads#resource) in the request body. For that resource, you must specify a value for the following properties: - `snippet.channelId` - `snippet.videoId` - `snippet.topLevelComment.snippet.textOriginal` ## Response If successful, this method returns a [commentThread resource](https://developers.google.com/youtube/v3/docs/commentThreads#resource) in the response body. ## Errors The following table identifies error messages that the API could return in response to a call to this method. For more details, see the [error message](https://developers.google.com/youtube/v3/docs/errors) documentation. | Error type | Error detail | Description | |--------------------|--------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `channelOrVideoIdMissing` | Each comment thread must be linked to a video. Make sure the resource specifies values for the [snippet.channelId](https://developers.google.com/youtube/v3/docs/commentThreads#snippet.channelId) and the [snippet.videoId](https://developers.google.com/youtube/v3/docs/commentThreads#snippet.videoId) properties. A comment on a video appears on the video's watch page. | | `badRequest (400)` | `commentTextRequired` | The `comment` resource that is being inserted must specify a value for the `snippet.topLevelComment.snippet.textOriginal` property. Comments cannot be empty. | | `badRequest (400)` | `commentTextTooLong` | The `comment` resource that is being inserted contains too many characters in the `snippet.topLevelComment.snippet.textOriginal` property. | | `badRequest (400)` | `invalidCommentThreadMetadata` | The request metadata is invalid. | | `badRequest (400)` | `processingFailure` | The API server failed to successfully process the request. While this can be a transient error, it usually indicates that the request's input is invalid. Check the structure of the `commentThread` resource in the request body to ensure that it is valid. | | `forbidden (403)` | `forbidden` | The comment thread couldn't be created due to insufficient permissions. The request might not be properly authorized. | | `forbidden (403)` | `ineligibleAccount` | The YouTube account used to authorize the API request must be merged with the user's Google Account to insert a comment or comment thread. | | `notFound (404)` | `channelNotFound` | The specified channel couldn't be found. Check the value of the [snippet.channelId](https://developers.google.com/youtube/v3/docs/commentThreads#snippet.channelId) property to ensure it is correct. | | `notFound (404)` | `videoNotFound` | The specified video couldn't be found. Check the value of the [snippet.videoId](https://developers.google.com/youtube/v3/docs/commentThreads#snippet.videoId) property to ensure it is correct. | ## Try it! Use the APIs Explorer to call this API and see the API request and response. --- # Source: https://developers.google.com/youtube/v3/docs/commentThreads/list.md.txt # CommentThreads: list Returns a list of comment threads that match the API request parameters. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 1 unit. ## Common use cases The list below shows common use cases for this method. Hover over a use case to see its description, or click on a use case to load sample parameter values in the APIs Explorer. You can open the [fullscreen APIs Explorer](https://developers.google.com/youtube/v3/docs/commentThreads/list#) to see code samples that dynamically update to reflect the parameter values entered in the Explorer. The table below shows common use cases for this method. You can click on a use case name to load sample parameter values in the APIs Explorer. Or you can see code samples for a use case in the fullscreen APIs Explorer by clicking on the code icon below a use case name. In the fullscreen UI, you can update parameter and property values and the code samples will dynamically update to reflect the values you enter. This method has one common use case, which is described below. The buttons below the description populate the APIs Explorer with sample values or open the fullscreen APIs Explorer to show code samples that use those values. The code samples also dynamically update if you change the values.
## Request ### HTTP request ``` GET https://www.googleapis.com/youtube/v3/commentThreads ``` ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters || |--------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---| | **Required parameters** ||| | `part` | `string` The **part** parameter specifies a comma-separated list of one or more `commentThread` resource properties that the API response will include. The following list contains the `part` names that you can include in the parameter value: - `id` - `replies` - `snippet` | | **Filters (specify exactly one of the following parameters)** ||| | `allThreadsRelatedToChannelId` | `string` The **allThreadsRelatedToChannelId** parameter instructs the API to return all comment threads associated with the specified channel. | | `id` | `string` The **id** parameter specifies a comma-separated list of comment thread IDs for the resources that should be retrieved. | | `videoId` | `string` The **videoId** parameter instructs the API to return comment threads associated with the specified video ID. | | **Optional parameters** ||| | `maxResults` | `unsigned integer` The **maxResults** parameter specifies the maximum number of items that should be returned in the result set. **Note:** This parameter is not supported for use in conjunction with the [id](https://developers.google.com/youtube/v3/docs/commentThreads/list#id) parameter. Acceptable values are `1` to `100`, inclusive. The default value is `20`. | | `moderationStatus` | `string` This parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication). Set this parameter to limit the returned comment threads to a particular moderation state. **Note:** This parameter is not supported for use in conjunction with the [id](https://developers.google.com/youtube/v3/docs/commentThreads/list#id) parameter. The default value is `published`. Acceptable values are: - **heldForReview** -- Retrieve comment threads that are awaiting review by a moderator. A comment thread can be included in the response if the top-level comment or at least one of the replies to that comment are awaiting review. - **likelySpam** -- Retrieve comment threads classified as likely to be spam. A comment thread can be included in the response if the top-level comment or at least one of the replies to that comment is considered likely to be spam. - **published** -- Retrieve threads of published comments. This is the default value. A comment thread can be included in the response if its top-level comment has been published. | | `order` | `string` The **order** parameter specifies the order in which the API response should list comment threads. Valid values are: - `time` - Comment threads are ordered by time. This is the default behavior. - `relevance` - Comment threads are ordered by relevance. **Note:** This parameter is not supported for use in conjunction with the [id](https://developers.google.com/youtube/v3/docs/commentThreads/list#id) parameter. | | `pageToken` | `string` The **pageToken** parameter identifies a specific page in the result set that should be returned. In an API response, the `nextPageToken` property identifies the next page of the result that can be retrieved. **Note:** This parameter is not supported for use in conjunction with the [id](https://developers.google.com/youtube/v3/docs/commentThreads/list#id) parameter. | | `searchTerms` | `string` The **searchTerms** parameter instructs the API to limit the API response to only contain comments that contain the specified search terms. **Note:** This parameter is not supported for use in conjunction with the [id](https://developers.google.com/youtube/v3/docs/commentThreads/list#id) parameter. | | `textFormat` | `string` Set this parameter's value to `html` or `plainText` to instruct the API to return the comments left by users in html formatted or in plain text. The default value is `html`. Acceptable values are: - **html** -- Returns the comments in HTML format. This is the default value. - **plainText** -- Returns the comments in plain text format. | ### Request body Don't provide a request body when calling this method. ## Response If successful, this method returns a response body with the following structure: ```objective-c { "kind": "youtube#commentThreadListResponse", "etag": etag, "nextPageToken": string, "pageInfo": { "totalResults": integer, "resultsPerPage": integer }, "items": [ commentThread Resource ] } ``` ### 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#commentThreadListResponse`. | | `etag` | `etag` The Etag of this resource. | | `nextPageToken` | `string` The token that can be used as the value of the `pageToken` parameter to retrieve the next page in the result set. | | `pageInfo` | `object` The `pageInfo` object encapsulates paging information for the result set. | | pageInfo.`totalResults` | `integer` The total number of results in the result set. | | pageInfo.`resultsPerPage` | `integer` The number of results included in the API response. | | `items[]` | `list` A list of comment threads that match the request criteria. | ## Errors The following table identifies error messages that the API could return in response to a call to this method. For more details, see the [error message](https://developers.google.com/youtube/v3/docs/errors) documentation. | Error type | Error detail | Description | |--------------------|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `operationNotSupported` | The `id` filter is only compatible with comments based on Google+. | | `badRequest (400)` | `processingFailure` | The API server failed to successfully process the request. While this can be a transient error, it usually indicates that the request's input is invalid. Check the structure of the `commentThread` resource in the request body to ensure that it is valid. | | `forbidden (403)` | `commentsDisabled` | The video identified by the [videoId](https://developers.google.com/youtube/v3/docs/commentThreads/list#videoId) parameter has disabled comments. | | `forbidden (403)` | `forbidden` | One or more of the requested comment threads cannot be retrieved due to insufficient permissions. The request might not be properly authorized. | | `notFound (404)` | `channelNotFound` | The channel identified by the [allThreadsRelatedToChannelId](https://developers.google.com/youtube/v3/docs/commentThreads/list#allThreadsRelatedToChannelId) parameter couldn't be found. | | `notFound (404)` | `commentThreadNotFound` | One or more of the specified comment threads cannot be found. Check the values of the request's [id](https://developers.google.com/youtube/v3/docs/commentThreads/list#id) parameter to ensure that it is correct. | | `notFound (404)` | `videoNotFound` | The video identified by the [videoId](https://developers.google.com/youtube/v3/docs/commentThreads/list#videoId) parameter couldn't be found. | ## Try it! Use the APIs Explorer to call this API and see the API request and response. --- # Source: https://developers.google.com/youtube/v3/docs/comments.md.txt A **comment** resource contains information about a single YouTube comment. A `comment` resource can represent a comment about either a video or a channel. In addition, the comment could be a top-level comment or a reply to a top-level comment. ## Methods The API supports the following methods for `comments` resources: [list](https://developers.google.com/youtube/v3/docs/comments/list) : Returns a list of comments that match the API request parameters. [Try it now](https://developers.google.com/youtube/v3/docs/comments/list#usage). [insert](https://developers.google.com/youtube/v3/docs/comments/insert) : Creates a reply to an existing comment. **Note:** To create a top-level comment, use the [commentThreads.insert](https://developers.google.com/youtube/v3/docs/commentThreads/insert) method. [Try it now](https://developers.google.com/youtube/v3/docs/comments/insert#usage). [update](https://developers.google.com/youtube/v3/docs/comments/update) : Modifies a comment. [Try it now](https://developers.google.com/youtube/v3/docs/comments/update#usage). [delete](https://developers.google.com/youtube/v3/docs/comments/delete) : Deletes a comment. [Try it now](https://developers.google.com/youtube/v3/docs/comments/delete#usage). [setModerationStatus](https://developers.google.com/youtube/v3/docs/comments/setModerationStatus) : Sets the moderation status of one or more comments. The API request must be authorized by the owner of the channel or video associated with the comments. [Try it now](https://developers.google.com/youtube/v3/docs/comments/setModerationStatus#usage). ## Resource representation The following JSON structure shows the format of a `comments` resource: ```text { "kind": "youtube#comment", "etag": etag, "id": string, "snippet": { "authorDisplayName": string, "authorProfileImageUrl": string, "authorChannelUrl": string, "authorChannelId": { "value": string }, "channelId": string, "textDisplay": string, "textOriginal": string, "parentId": string, "canRate": boolean, "viewerRating": string, "likeCount": unsigned integer, "moderationStatus": string, "publishedAt": datetime, "updatedAt": datetime } } ``` ### 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#comment`. | | `etag` | `etag` The Etag of this resource. | | `id` | `string` The ID that YouTube uses to uniquely identify the comment. | | `snippet` | `object` The `snippet` object contains basic details about the comment. | | snippet.`authorDisplayName` | `string` The display name of the user who posted the comment. | | snippet.`authorProfileImageUrl` | `string` The URL for the avatar of the user who posted the comment. | | snippet.`authorChannelUrl` | `string` The URL of the comment author's YouTube channel, if available. | | snippet.`authorChannelId` | `object` This object encapsulates information about the comment author's YouTube channel, if available. | | snippet.authorChannelId.`value` | `string` The ID of the comment author's YouTube channel, if available. | | snippet.`channelId` | `string` The ID of the YouTube channel associated with the comment. | | snippet.`textDisplay` | `string` The comment's text. The text can be retrieved in either plain text or HTML. (The `comments.list` and `commentThreads.list` methods both support a `textFormat` parameter, which specifies the chosen text format.) Even the plain text may differ from the original comment text. For example, it may replace video links with video titles. | | snippet.`textOriginal` | `string` The original, raw text of the comment as it was initially posted or last updated. The original text is only returned to the authenticated user if they are the comment's author. | | snippet.`parentId` | `string` The unique ID of the parent comment. This property is only set if the comment was submitted as a reply to another comment. | | snippet.`canRate` | `boolean` This setting indicates whether the current viewer can rate the comment. | | snippet.`viewerRating` | `string` The rating the viewer has given to this comment. This property doesn't identify `dislike` ratings, though this behavior is subject to change. In the meantime, the property value is `like` if the viewer has rated the comment positively. The value is `none` in all other cases, including the user having given the comment a negative rating or not having rated the comment. Valid values for this property are: - `like` - `none` | | snippet.`likeCount` | `unsigned integer` The total number of likes (positive ratings) the comment has received. | | snippet.`moderationStatus` | `string` The comment's moderation status. This property is only returned if the API request was authorized by the owner of the channel or the video on which the requested comments were made. Also, this property isn't set if the API request used the [id](https://developers.google.com/youtube/v3/docs/comments/list#id) filter parameter. Valid values for this property are: - `heldForReview` - `likelySpam` - `published` - `rejected` | | snippet.`publishedAt` | `datetime` The date and time when the comment was orignally published. The value is specified in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format. | | snippet.`updatedAt` | `datetime` The date and time when the comment was last updated. The value is specified in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format. | --- # Source: https://developers.google.com/youtube/v3/docs/comments/delete.md.txt # Comments: delete Deletes a comment. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 50 units. ## Common use cases The list below shows common use cases for this method. Hover over a use case to see its description, or click on a use case to load sample parameter values in the APIs Explorer. You can open the [fullscreen APIs Explorer](https://developers.google.com/youtube/v3/docs/comments/delete#) to see code samples that dynamically update to reflect the parameter values entered in the Explorer. The table below shows common use cases for this method. You can click on a use case name to load sample parameter values in the APIs Explorer. Or you can see code samples for a use case in the fullscreen APIs Explorer by clicking on the code icon below a use case name. In the fullscreen UI, you can update parameter and property values and the code samples will dynamically update to reflect the values you enter. This method has one common use case, which is described below. The buttons below the description populate the APIs Explorer with sample values or open the fullscreen APIs Explorer to show code samples that use those values. The code samples also dynamically update if you change the values.
## Request ### HTTP request ``` DELETE https://www.googleapis.com/youtube/v3/comments ``` ### Authorization This request requires authorization with at least one of the following scopes ([read more about authentication and authorization](https://developers.google.com/youtube/v3/guides/authentication)). | Scope | |-----------------------------------------------------| | `https://www.googleapis.com/auth/youtube.force-ssl` | ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters || |------|------------------------------------------------------------------------------------------------|---| | **Required parameters** ||| | `id` | `string` The **id** parameter specifies the comment ID for the resource that is being deleted. | ### Request body Do not provide a request body when calling this method. ## Response If successful, this method returns an HTTP `204` response code (`No Content`). ## Errors The following table identifies error messages that the API could return in response to a call to this method. Please see the [error message](https://developers.google.com/youtube/v3/docs/errors) documentation for more detail. | Error type | Error detail | Description | |--------------------|---------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `processingFailure` | The API server failed to successfully process the request. While this can be a transient error, it usually indicates that the request's input is invalid. | | `forbidden (403)` | `forbidden` | The comment could not be deleted because of insufficient permissions. The request might not be properly authorized. | | `notFound (404)` | `commentNotFound` | The specified comment could not be found. Check the value of the request's [id](https://developers.google.com/youtube/v3/docs/comments/delete#id) parameter to ensure that it is correct. | ## Try it! Use the APIs Explorer to call this API and see the API request and response. --- # Source: https://developers.google.com/youtube/v3/docs/comments/insert.md.txt # Comments: insert Creates a reply to an existing comment. **Note:** To create a top-level comment, use the [commentThreads.insert](https://developers.google.com/youtube/v3/docs/commentThreads/insert) method. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 50 units. ## Common use cases The list below shows common use cases for this method. Hover over a use case to see its description, or click on a use case to load sample parameter values in the APIs Explorer. You can open the [fullscreen APIs Explorer](https://developers.google.com/youtube/v3/docs/comments/insert#) to see code samples that dynamically update to reflect the parameter values entered in the Explorer. The table below shows common use cases for this method. You can click on a use case name to load sample parameter values in the APIs Explorer. Or you can see code samples for a use case in the fullscreen APIs Explorer by clicking on the code icon below a use case name. In the fullscreen UI, you can update parameter and property values and the code samples will dynamically update to reflect the values you enter. This method has one common use case, which is described below. The buttons below the description populate the APIs Explorer with sample values or open the fullscreen APIs Explorer to show code samples that use those values. The code samples also dynamically update if you change the values.
## Request ### HTTP request ``` POST https://www.googleapis.com/youtube/v3/comments ``` ### Authorization This request requires authorization with at least one of the following scopes ([read more about authentication and authorization](https://developers.google.com/youtube/v3/guides/authentication)). | Scope | |-----------------------------------------------------| | `https://www.googleapis.com/auth/youtube.force-ssl` | ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters || |--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---| | **Required parameters** ||| | `part` | `string` The **part** parameter identifies the properties that the API response will include. Set the parameter value to `snippet`. The `snippet` part has a quota cost of 2 units. The following list contains the `part` names that you can include in the parameter value: - `id` - `snippet` | ### Request body Provide a [comment resource](https://developers.google.com/youtube/v3/docs/comments#resource) in the request body. For that resource: - You must specify a value for these properties:
- `snippet.textOriginal` - `snippet.parentId`
- You can set values for these properties:
- `snippet.textOriginal`
## Response If successful, this method returns a [comment resource](https://developers.google.com/youtube/v3/docs/comments#resource) in the response body. ## Errors The following table identifies error messages that the API could return in response to a call to this method. Please see the [error message](https://developers.google.com/youtube/v3/docs/errors) documentation for more detail. | Error type | Error detail | Description | |--------------------|--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `commentTextRequired` | The `comment` resource that is being inserted must specify a value for the `snippet.textOriginal` property. Comments cannot be empty. | | `badRequest (400)` | `commentTextTooLong` | The `comment` resource that is being inserted contains too many characters in the `snippet.textOriginal` property. | | `badRequest (400)` | `invalidCustomEmoji` | The `comment` resource that is being inserted contains invalid custom emoji. | | `badRequest (400)` | `invalidCommentMetadata` | The request metadata is invalid. | | `badRequest (400)` | `operationNotSupported` | The API user is not able to insert a comment in reply to the top-level comment identified by the `snippet.parentId` property. In a `commentThread` resource, the [snippet.canReply](https://developers.google.com/youtube/v3/docs/commentThreads#snippet.canReply) property indicates whether the current viewer can reply to the thread. | | `badRequest (400)` | `parentCommentIsPrivate` | The specified parent comment is private. The API does not support replies to private comments. | | `badRequest (400)` | `parentIdMissing` | The comment that is being inserted must be linked to a parent comment. However, the `comment` resource in the body of the API request did not specify a value for the [snippet.parentId](https://developers.google.com/youtube/v3/docs/comments#snippet.parentId) property. | | `badRequest (400)` | `processingFailure` | The API server failed to successfully process the request. While this can be a transient error, it usually indicates that the request's input is invalid. Check the structure of the `comment` resource in the request body to ensure that it is valid. | | `forbidden (403)` | `forbidden` | The comment cannot be created due to insufficient permissions. The request might not be properly authorized. | | `forbidden (403)` | `ineligibleAccount` | The YouTube account used to authorize the API request must be merged with the user's Google account to insert a comment or comment thread. | | `notFound (404)` | `parentCommentNotFound` | The specified parent comment could not be found. Check the value of the [snippet.parentId](https://developers.google.com/youtube/v3/docs/comments#snippet.parentId) property in the request body to ensure that it is correct. | ## Try it! Use the APIs Explorer to call this API and see the API request and response. --- # Source: https://developers.google.com/youtube/v3/docs/comments/list.md.txt # Comments: list Returns a list of comments that match the API request parameters. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 1 unit. ## Common use cases The list below shows common use cases for this method. Hover over a use case to see its description, or click on a use case to load sample parameter values in the APIs Explorer. You can open the [fullscreen APIs Explorer](https://developers.google.com/youtube/v3/docs/comments/list#) to see code samples that dynamically update to reflect the parameter values entered in the Explorer. The table below shows common use cases for this method. You can click on a use case name to load sample parameter values in the APIs Explorer. Or you can see code samples for a use case in the fullscreen APIs Explorer by clicking on the code icon below a use case name. In the fullscreen UI, you can update parameter and property values and the code samples will dynamically update to reflect the values you enter. This method has one common use case, which is described below. The buttons below the description populate the APIs Explorer with sample values or open the fullscreen APIs Explorer to show code samples that use those values. The code samples also dynamically update if you change the values.
## Request ### HTTP request ``` GET https://www.googleapis.com/youtube/v3/comments ``` ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters || |--------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---| | **Required parameters** ||| | `part` | `string` The **part** parameter specifies a comma-separated list of one or more `comment` resource properties that the API response will include. The following list contains the `part` names that you can include in the parameter value: - `id` - `snippet` | | **Filters (specify exactly one of the following parameters)** ||| | `id` | `string` The **id** parameter specifies a comma-separated list of comment IDs for the resources that are being retrieved. In a `comment` resource, the `id` property specifies the comment's ID. | | `parentId` | `string` The **parentId** parameter specifies the ID of the comment for which replies should be retrieved. **Note:** YouTube currently supports replies only for top-level comments. However, replies to replies may be supported in the future. | | **Optional parameters** ||| | `maxResults` | `unsigned integer` The **maxResults** parameter specifies the maximum number of items that should be returned in the result set. **Note:** This parameter is not supported for use in conjunction with the [id](https://developers.google.com/youtube/v3/docs/comments/list#id) parameter. Acceptable values are `1` to `100`, inclusive. The default value is `20`. | | `pageToken` | `string` The **pageToken** parameter identifies a specific page in the result set that should be returned. In an API response, the `nextPageToken` property identifies the next page of the result that can be retrieved. **Note:** This parameter is not supported for use in conjunction with the [id](https://developers.google.com/youtube/v3/docs/comments/list#id) parameter. | | `textFormat` | `string` This parameter indicates whether the API should return comments formatted as HTML or as plain text. The default value is `html`. Acceptable values are: - **html** -- Returns the comments in HTML format. This is the default value. - **plainText** -- Returns the comments in plain text format. | ### Request body Do not provide a request body when calling this method. ## Response If successful, this method returns a response body with the following structure: ```objective-c { "kind": "youtube#commentListResponse", "etag": etag, "nextPageToken": string, "pageInfo": { "totalResults": integer, "resultsPerPage": integer }, "items": [ comment Resource ] } ``` ### 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#commentListResponse`. | | `etag` | `etag` The Etag of this resource. | | `nextPageToken` | `string` The token that can be used as the value of the `pageToken` parameter to retrieve the next page in the result set. | | `pageInfo` | `object` The `pageInfo` object encapsulates paging information for the result set. | | pageInfo.`totalResults` | `integer` The total number of results in the result set. | | pageInfo.`resultsPerPage` | `integer` The number of results included in the API response. | | `items[]` | `list` A list of comments that match the request criteria. | ## Errors The following table identifies error messages that the API could return in response to a call to this method. Please see the [error message](https://developers.google.com/youtube/v3/docs/errors) documentation for more detail. | Error type | Error detail | Description | |--------------------|-------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `operationNotSupported` | The id filter is only compatible with comments based on Google+. | | `forbidden (403)` | `forbidden` | One or more of the requested comments cannot be retrieved due to insufficient permissions. The request might not be properly authorized. | | `notFound (404)` | `commentNotFound` | One or more of the specified comments cannot be found. Check the values of the request's [id](https://developers.google.com/youtube/v3/docs/comments/list#id) and [parentId](https://developers.google.com/youtube/v3/docs/comments/list#parentId) parameters to ensure that they are correct. | ## Try it! Use the APIs Explorer to call this API and see the API request and response. --- # Source: https://developers.google.com/youtube/v3/docs/comments/markAsSpam.md.txt # Comments: markAsSpam **This method has been deprecated and is no longer supported.** Expresses the caller's opinion that one or more comments should be flagged as spam. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 50 units. ## Common use cases The list below shows common use cases for this method. Hover over a use case to see its description, or click on a use case to load sample parameter values in the APIs Explorer. You can open the [fullscreen APIs Explorer](https://developers.google.com/youtube/v3/docs/comments/markAsSpam#) to see code samples that dynamically update to reflect the parameter values entered in the Explorer. The table below shows common use cases for this method. You can click on a use case name to load sample parameter values in the APIs Explorer. Or you can see code samples for a use case in the fullscreen APIs Explorer by clicking on the code icon below a use case name. In the fullscreen UI, you can update parameter and property values and the code samples will dynamically update to reflect the values you enter. This method has one common use case, which is described below. The buttons below the description populate the APIs Explorer with sample values or open the fullscreen APIs Explorer to show code samples that use those values. The code samples also dynamically update if you change the values.
## Request ### HTTP request ``` POST https://www.googleapis.com/youtube/v3/comments/markAsSpam ``` ### Authorization This request requires authorization with at least one of the following scopes ([read more about authentication and authorization](https://developers.google.com/youtube/v3/guides/authentication)). | Scope | |-----------------------------------------------------| | `https://www.googleapis.com/auth/youtube.force-ssl` | ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters || |------|------------------------------------------------------------------------------------------------------------------------------------------|---| | **Required parameters** ||| | `id` | `string` The **id** parameter specifies a comma-separated list of IDs of comments that the caller believes should be classified as spam. | ### Request body Do not provide a request body when calling this method. ## Response If successful, this method returns an HTTP `204` response code (`No Content`). ## Errors The following table identifies error messages that the API could return in response to a call to this method. Please see the [error message](https://developers.google.com/youtube/v3/docs/errors) documentation for more detail. | Error type | Error detail | Description | |--------------------|-------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `operationNotSupported` | Comments not based on Google+ cannot be marked as spam. | | `badRequest (400)` | `processingFailure` | The API server failed to successfully process the request. While this can be a transient error, it usually indicates that the request's input is invalid. | | `forbidden (403)` | `forbidden` | One or more comments could not be marked as spam because of insufficient permissions. The request might not be properly authorized. | | `notFound (404)` | `commentNotFound` | One or more of the comments that the request is trying to update cannot be found. Check the values in the request's [id](https://developers.google.com/youtube/v3/docs/comments/markAsSpam#id) parameter to ensure that they are correct. | ## Try it! Use the APIs Explorer to call this API and see the API request and response. --- # Source: https://developers.google.com/youtube/v3/docs/comments/setModerationStatus.md.txt # Comments: setModerationStatus Sets the moderation status of one or more comments. The API request must be authorized by the owner of the channel or video associated with the comments. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 50 units. ## Common use cases The list below shows common use cases for this method. Hover over a use case to see its description, or click on a use case to load sample parameter values in the APIs Explorer. You can open the [fullscreen APIs Explorer](https://developers.google.com/youtube/v3/docs/comments/setModerationStatus#) to see code samples that dynamically update to reflect the parameter values entered in the Explorer. The table below shows common use cases for this method. You can click on a use case name to load sample parameter values in the APIs Explorer. Or you can see code samples for a use case in the fullscreen APIs Explorer by clicking on the code icon below a use case name. In the fullscreen UI, you can update parameter and property values and the code samples will dynamically update to reflect the values you enter. This method has one common use case, which is described below. The buttons below the description populate the APIs Explorer with sample values or open the fullscreen APIs Explorer to show code samples that use those values. The code samples also dynamically update if you change the values.
## Request ### HTTP request ``` POST https://www.googleapis.com/youtube/v3/comments/setModerationStatus ``` ### Authorization This request requires authorization with at least one of the following scopes ([read more about authentication and authorization](https://developers.google.com/youtube/v3/guides/authentication)). | Scope | |-----------------------------------------------------| | `https://www.googleapis.com/auth/youtube.force-ssl` | ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters || |--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---| | **Required parameters** ||| | `id` | `string` The **id** parameter specifies a comma-separated list of IDs that identify the comments for which you are updating the moderation status. | | `moderationStatus` | `string` Identifies the new moderation status of the specified comments. Acceptable values are: - **heldForReview** -- Marks a comment as awaiting review by a moderator. - **published** -- Clears a comment for public display. - **rejected** -- Rejects a comment as being unfit for display. This action also effectively hides all replies to the rejected comment. | | **Optional parameters** ||| | `banAuthor` | `boolean` The **banAuthor** parameter lets you indicate that you want to automatically reject any additional comments written by the comment's author. Set the parameter value to `true` to ban the author. **Note:** This parameter is only valid if the [moderationStatus](https://developers.google.com/youtube/v3/docs/comments/setModerationStatus#moderationStatus) parameter is also set to `rejected`. | ### Request body Do not provide a request body when calling this method. ## Response If successful, this method returns an HTTP `204` response code (`No Content`). ## Errors The following table identifies error messages that the API could return in response to a call to this method. Please see the [error message](https://developers.google.com/youtube/v3/docs/errors) documentation for more detail. | Error type | Error detail | Description | |--------------------|-------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `banWithoutReject` | The `banAuthor` parameter can only be used if the `moderationStatus` parameter value is `rejected`. | | `badRequest (400)` | `operationNotSupported` | Comments not based on Google+ offer only limited moderation functionality. | | `badRequest (400)` | `processingFailure` | The API server failed to successfully process the request. While this can be a transient error, it usually indicates that the request's input is invalid. | | `forbidden (403)` | `forbidden` | The moderation status of one or more comments cannot be set due to insufficient permissions. The request might not be properly authorized. | | `notFound (404)` | `commentNotFound` | One or more of the comments that the request is trying to update cannot be found. Check the values of the request's [id](https://developers.google.com/youtube/v3/docs/comments/setModerationStatus#id) parameter to ensure that they are correct. | ## Try it! Use the APIs Explorer to call this API and see the API request and response. --- # Source: https://developers.google.com/youtube/v3/docs/comments/update.md.txt # Comments: update Modifies a comment. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 50 units. ## Common use cases The list below shows common use cases for this method. Hover over a use case to see its description, or click on a use case to load sample parameter values in the APIs Explorer. You can open the [fullscreen APIs Explorer](https://developers.google.com/youtube/v3/docs/comments/update#) to see code samples that dynamically update to reflect the parameter values entered in the Explorer. The table below shows common use cases for this method. You can click on a use case name to load sample parameter values in the APIs Explorer. Or you can see code samples for a use case in the fullscreen APIs Explorer by clicking on the code icon below a use case name. In the fullscreen UI, you can update parameter and property values and the code samples will dynamically update to reflect the values you enter. This method has one common use case, which is described below. The buttons below the description populate the APIs Explorer with sample values or open the fullscreen APIs Explorer to show code samples that use those values. The code samples also dynamically update if you change the values.
## Request ### HTTP request ``` PUT https://www.googleapis.com/youtube/v3/comments ``` ### Authorization This request requires authorization with at least one of the following scopes ([read more about authentication and authorization](https://developers.google.com/youtube/v3/guides/authentication)). | Scope | |-----------------------------------------------------| | `https://www.googleapis.com/auth/youtube.force-ssl` | ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters || |--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---| | **Required parameters** ||| | `part` | `string` The **part** parameter identifies the properties that the API response will include. You must at least include the `snippet` part in the parameter value since that part contains all of the properties that the API request can update. The following list contains the `part` names that you can include in the parameter value: - `id` - `snippet` | ### Request body Provide a [comment resource](https://developers.google.com/youtube/v3/docs/comments#resource) in the request body. For that resource: - You can set values for these properties:
- `snippet.textOriginal`
## Response If successful, this method returns a [comment resource](https://developers.google.com/youtube/v3/docs/comments#resource) in the response body. ## Errors The following table identifies error messages that the API could return in response to a call to this method. Please see the [error message](https://developers.google.com/youtube/v3/docs/errors) documentation for more detail. | Error type | Error detail | Description | |--------------------|--------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `commentTextTooLong` | The `comment` resource that is being updated contains too many characters in the `snippet.textOriginal` property. | | `badRequest (400)` | `invalidCommentMetadata` | The request metadata is invalid. | | `badRequest (400)` | `operationNotSupported` | Only Google+ based comments can be updated. | | `badRequest (400)` | `processingFailure` | The API server failed to successfully process the request. While this can be a transient error, it usually indicates that the request's input is invalid. Check the structure of the `comment` resource in the request body to ensure that it is valid. | | `forbidden (403)` | `forbidden` | The comment could not be updated due to insufficient permissions. The request might not be properly authorized. | | `forbidden (403)` | `ineligibleAccount` | The YouTube account used to authorize the API request must be merged with the user's Google account to update a comment or comment thread. | | `notFound (404)` | `commentNotFound` | The specified comment could not be found. Check the value of the [id](https://developers.google.com/youtube/v3/docs/comments#id) property in the request body to ensure that it is correct. | ## Try it! Use the APIs Explorer to call this API and see the API request and response. --- # Source: https://developers.google.com/youtube/v3/docs/core_errors.md.txt # Google APIs - Global domain errors This document identifies some of the error codes and messages that Google APIs return. Specifically, the errors listed here are in the global, or default, domain for Google APIs. Many APIs also define their own domains, which identify API-specific errors that are not in the global domain. For those errors, the value of the `domain` property in the JSON response will be an API-specific value, such as `youtube.parameter`. This page lists errors by their HTTP status codes as defined in [RFC 7231](https://tools.ietf.org/html/rfc7231#section-6). The sample JSON response below demonstrates how a global error is communicated: ```transact-sql { "error": { "errors": [ { "domain": "global", "reason": "invalidParameter", "message": "Invalid string value: 'asdf'. Allowed values: [mostpopular]", "locationType": "parameter", "location": "chart" } ], "code": 400, "message": "Invalid string value: 'asdf'. Allowed values: [mostpopular]" } } ``` ## Errors 1. [MOVED_PERMANENTLY (301)](https://developers.google.com/youtube/v3/docs/core_errors#MOVED_PERMANENTLY) 2. [SEE_OTHER (303)](https://developers.google.com/youtube/v3/docs/core_errors#SEE_OTHER) 3. [NOT_MODIFIED (304)](https://developers.google.com/youtube/v3/docs/core_errors#NOT_MODIFIED) 4. [TEMPORARY_REDIRECT (307)](https://developers.google.com/youtube/v3/docs/core_errors#TEMPORARY_REDIRECT) 5. [BAD_REQUEST (400)](https://developers.google.com/youtube/v3/docs/core_errors#BAD_REQUEST) 6. [UNAUTHORIZED (401)](https://developers.google.com/youtube/v3/docs/core_errors#UNAUTHORIZED) 7. [PAYMENT_REQUIRED (402)](https://developers.google.com/youtube/v3/docs/core_errors#PAYMENT_REQUIRED) 8. [FORBIDDEN (403)](https://developers.google.com/youtube/v3/docs/core_errors#FORBIDDEN) 9. [NOT_FOUND (404)](https://developers.google.com/youtube/v3/docs/core_errors#NOT_FOUND) 10. [METHOD_NOT_ALLOWED (405)](https://developers.google.com/youtube/v3/docs/core_errors#METHOD_NOT_ALLOWED) 11. [CONFLICT (409)](https://developers.google.com/youtube/v3/docs/core_errors#CONFLICT) 12. [GONE (410)](https://developers.google.com/youtube/v3/docs/core_errors#GONE) 13. [PRECONDITION_FAILED (412)](https://developers.google.com/youtube/v3/docs/core_errors#PRECONDITION_FAILED) 14. [REQUEST_ENTITY_TOO_LARGE (413)](https://developers.google.com/youtube/v3/docs/core_errors#REQUEST_ENTITY_TOO_LARGE) 15. [REQUESTED_RANGE_NOT_SATISFIABLE (416)](https://developers.google.com/youtube/v3/docs/core_errors#REQUESTED_RANGE_NOT_SATISFIABLE) 16. [EXPECTATION_FAILED (417)](https://developers.google.com/youtube/v3/docs/core_errors#EXPECTATION_FAILED) 17. [PRECONDITION_REQUIRED (428)](https://developers.google.com/youtube/v3/docs/core_errors#PRECONDITION_REQUIRED) 18. [TOO_MANY_REQUESTS (429)](https://developers.google.com/youtube/v3/docs/core_errors#TOO_MANY_REQUESTS) 19. [INTERNAL_SERVER_ERROR (500)](https://developers.google.com/youtube/v3/docs/core_errors#INTERNAL_SERVER_ERROR) 20. [NOT_IMPLEMENTED (501)](https://developers.google.com/youtube/v3/docs/core_errors#NOT_IMPLEMENTED) 21. [SERVICE_UNAVAILABLE (503)](https://developers.google.com/youtube/v3/docs/core_errors#SERVICE_UNAVAILABLE) ### MOVED_PERMANENTLY (301) | Error code | Description | |--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `movedPermanently` | This request and future requests for the same operation have to be sent to the URL specified in the `Location` header of this response instead of to the URL to which this request was sent. | ### SEE_OTHER (303) | Error code | Description | |-------------------------|---------------------------------------------------------------------------------------------------------------------------------------| | `seeOther` | Your request was processed successfully. To obtain your response, send a `GET` request to the URL specified in the `Location` header. | | `mediaDownloadRedirect` | Your request was processed successfully. To obtain your response, send a `GET` request to the URL specified in the `Location` header. | ### NOT_MODIFIED (304) | Error code | Description | |---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `notModified` | The condition set for an If-None-Match header was not met. This response indicates that the requested document has not been modified and that a cached response should be retrieved. Check the value of the `If-None-Match` HTTP request header. | ### TEMPORARY_REDIRECT (307) | Error code | Description | |---------------------|-----------------------------------------------------------------------------------------------------------| | `temporaryRedirect` | To have your request processed, resend it to the URL specified in the `Location` header of this response. | ### BAD_REQUEST (400) | Error code | Description | |-------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest` | The API request is invalid or improperly formed. Consequently, the API server could not understand the request. | | `badBinaryDomainRequest` | The binary domain request is invalid. | | `badContent` | The content type of the request data or the content type of a part of a multipart request is not supported. | | `badLockedDomainRequest` | The locked domain request is invalid. | | `corsRequestWithXOrigin` | The CORS request contains an XD3 X-Origin header, which is indicative of a bad CORS request. | | `endpointConstraintMismatch` | The request failed because it did not match the specified API. Check the value of the URL path to make sure it is correct. | | `invalid` | The request failed because it contained an invalid value. The value could be a parameter value, a header value, or a property value. | | `invalidAltValue` | The `alt` parameter value specifies an unknown output format. | | `invalidHeader` | The request failed because it contained an invalid header. | | `invalidParameter` | The request failed because it contained an invalid parameter or parameter value. Review the API documentation to determine which parameters are valid for your request. | | `invalidQuery` | The request is invalid. Check the API documentation to determine what parameters are supported for the request and to see if the request contains an invalid combination of parameters or an invalid parameter value. Check the value of the `q` request parameter. | | `keyExpired` | The API key provided in the request expired, which means the API server is unable to check the quota limit for the application making the request. Check the [Google Developers Console](https://console.developers.google.com) for more information or to obtain a new key. | | `keyInvalid` | The API key provided in the request is invalid, which means the API server is unable to check the quota limit for the application making the request. Use the [Google Developers Console](https://console.developers.google.com) to find your API key or to obtain one. | | `lockedDomainCreationFailure` | The OAuth token was received in the query string, which this API forbids for response formats other than JSON or XML. If possible, try sending the OAuth token in the Authorization header instead. | | `notDownload` | Only media downloads requests can be sent to `/download/*` URL paths. Resend the request to the same path, but without the `/download` prefix. | | `notUpload` | The request failed because it is not an upload request, and only upload requests can be sent to `/upload/*` URIs. Try resending the request to the same path, but without the `/upload` prefix. | | `parseError` | The API server cannot parse the request body. | | `required` | The API request is missing required information. The required information could be a parameter or resource property. | | `tooManyParts` | The multipart request failed because it contains too many parts | | `unknownApi` | The API that the request is calling is not recognized. | | `unsupportedMediaProtocol` | The client is using an unsupported media protocol. | | `unsupportedOutputFormat` | The `alt` parameter value specifies an output format that is not supported for this service. Check the value of the `alt` request parameter. | | `wrongUrlForUpload` | The request is an upload request, but it failed because it was not sent to the proper URI. Upload requests must be sent to URIs that contain the `/upload/*` prefix. Try resending the request to the same path, but with the `/upload` prefix. | ### UNAUTHORIZED (401) | Error code | Description | |-----------------------|---------------------------------------------------------------------------------------------------------------------------------| | `unauthorized` | The user is not authorized to make the request. | | `authError` | The authorization credentials provided for the request are invalid. Check the value of the `Authorization` HTTP request header. | | `expired` | Session Expired. Check the value of the `Authorization` HTTP request header. | | `lockedDomainExpired` | The request failed because a previously valid locked domain has expired. | | `required` | The user must be logged in to make this API request. Check the value of the `Authorization` HTTP request header. | ### PAYMENT_REQUIRED (402) | Error code | Description | |-------------------------|-----------------------------------------------------------------------------------------------------------------------| | `dailyLimitExceeded402` | A daily budget limit set by the developer has been reached. | | `quotaExceeded402` | The requested operation requires more resources than the quota allows. Payment is required to complete the operation. | | `user402` | The requested operation requires some kind of payment from the authenticated user. | ### FORBIDDEN (403) | Error code | Description | |------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `forbidden` | The requested operation is forbidden and cannot be completed. | | `accessNotConfigured` | Your project is not configured to access this API. Please use the [Google Developers Console](https://console.developers.google.com) to activate the API for your project. | | `accessNotConfigured` | The project has been blocked due to abuse. See . | | `accessNotConfigured` | The project has been marked for deletion. | | `accountDeleted` | The user account associated with the request's authorization credentials has been deleted. Check the value of the `Authorization` HTTP request header. | | `accountDisabled` | The user account associated with the request's authorization credentials has been disabled. Check the value of the `Authorization` HTTP request header. | | `accountUnverified` | The email address for the user making the request has not been verified. Check the value of the `Authorization` HTTP request header. | | `concurrentLimitExceeded` | The request failed because a concurrent usage limit has been reached. | | `dailyLimitExceeded` | A daily quota limit for the API has been reached. | | `dailyLimitExceeded` | The daily quota limit has been reached, and the project has been blocked due to abuse. See the [Google APIs compliance support form](http://support.google.com/code/go/developer_compliance) to help resolve the issue. | | `dailyLimitExceededUnreg` | The request failed because a daily limit for unauthenticated API use has been hit. Continued use of the API requires signup through the [Google Developers Console](https://console.developers.google.com). | | `downloadServiceForbidden` | The API does not support a download service. | | `insufficientAudience` | The request cannot be completed for this audience. | | `insufficientAuthorizedParty` | The request cannot be completed for this application. | | `insufficientPermissions` | The authenticated user does not have sufficient permissions to execute this request. | | `limitExceeded` | The request cannot be completed due to access or rate limitations. | | `lockedDomainForbidden` | This API does not support locked domains. | | `quotaExceeded` | The requested operation requires more resources than the quota allows. | | `rateLimitExceeded` | Too many requests have been sent within a given time span. | | `rateLimitExceededUnreg` | A rate limit has been exceeded and you must register your application to be able to continue calling the API. Please sign up using the [Google Developers Console](https://console.developers.google.com). | | `responseTooLarge` | The requested resource is too large to return. | | `servingLimitExceeded` | The overall rate limit specified for the API has already been reached. | | `sslRequired` | SSL is required to perform this operation. | | `unknownAuth` | The API server does not recognize the authorization scheme used for the request. Check the value of the `Authorization` HTTP request header. | | `userRateLimitExceeded` | The request failed because a per-user rate limit has been reached. | | `userRateLimitExceededUnreg` | The request failed because a per-user rate limit has been reached, and the client developer was not identified in the request. Please use the Google Developer Console (https://console.developers.google.com) to create a project for your application. | | `variableTermExpiredDailyExceeded` | The request failed because a variable term quota expired and a daily limit was reached. | | `variableTermLimitExceeded` | The request failed because a variable term quota limit was reached. | ### NOT_FOUND (404) | Error code | Description | |-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `notFound` | The requested operation failed because a resource associated with the request could not be found. | | `notFound` | A resource associated with the request could not be found. If you have not used this API in the last two weeks, please re-deploy the App Engine app and try calling it again. | | `unsupportedProtocol` | The protocol used in the request is not supported. | ### METHOD_NOT_ALLOWED (405) | Error code | Description | |------------------------|---------------------------------------------------------------| | `httpMethodNotAllowed` | The HTTP method associated with the request is not supported. | ### CONFLICT (409) | Error code | Description | |-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `conflict` | The API request cannot be completed because the requested operation would conflict with an existing item. For example, a request that tries to create a duplicate item would create a conflict, though duplicate items are typically identified with more specific errors. | | `duplicate` | The requested operation failed because it tried to create a resource that already exists. | ### GONE (410) | Error code | Description | |------------|--------------------------------------------------------------------------------------| | `deleted` | The request failed because the resource associated with the request has been deleted | ### PRECONDITION_FAILED (412) | Error code | Description | |-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `conditionNotMet` | The condition set in the request's `If-Match` or `If-None-Match` HTTP request header was not met. See the [ETag](https://tools.ietf.org/html/rfc7232#section-2.3) section of the HTTP specification for details. Check the value of the `If-Match` HTTP request header. | ### REQUEST_ENTITY_TOO_LARGE (413) | Error code | Description | |--------------------------|-----------------------------------------------------------------------| | `backendRequestTooLarge` | The request is too large. | | `batchSizeTooLarge` | The batch request contains too many elements. | | `uploadTooLarge` | The request failed because the data sent in the request is too large. | ### REQUESTED_RANGE_NOT_SATISFIABLE (416) | Error code | Description | |--------------------------------|---------------------------------------------------------| | `requestedRangeNotSatisfiable` | The request specified a range that cannot be satisfied. | ### EXPECTATION_FAILED (417) | Error code | Description | |---------------------|---------------------------------------------------| | `expectationFailed` | A client expectation cannot be met by the server. | ### PRECONDITION_REQUIRED (428) | Error code | Description | |------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `preconditionRequired` | The request requires a precondition that is not provided. For this request to succeed, you need to provide either an `If-Match` or `If-None-Match` header with the request. | ### TOO_MANY_REQUESTS (429) | Error code | Description | |---------------------|------------------------------------------------------------| | `rateLimitExceeded` | Too many requests have been sent within a given time span. | ### INTERNAL_SERVER_ERROR (500) | Error code | Description | |-----------------|----------------------------------------------| | `internalError` | The request failed due to an internal error. | ### NOT_IMPLEMENTED (501) | Error code | Description | |---------------------|------------------------------------------------------------------------------------| | `notImplemented` | The requested operation has not been implemented. | | `unsupportedMethod` | The request failed because it is trying to execute an unknown method or operation. | ### SERVICE_UNAVAILABLE (503) | Error code | Description | |-----------------------|-------------------------------------------------| | `backendError` | A backend error occurred. | | `backendNotConnected` | The request failed due to a connection error. | | `notReady` | The API server is not ready to accept requests. | --- # Source: https://developers.google.com/youtube/v3/docs/errors.md.txt This document identifies the different types of errors that YouTube Data API operations can return. You can also find a list of errors for any individual method in the reference documentation for that method. ## General errors The following tables identify API error messages that are not specific to a particular API method. ### `Core API errors` | Error type | Error detail | Description | |-----------------------|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------| | `forbidden (403)` | `forbidden` | Access forbidden. The request may not be properly authorized. | | `quotaExceeded (403)` | `quotaExceeded` | The request cannot be completed because you have exceeded your [quota](https://developers.google.com/youtube/v3/getting-started#quota). | ### `Common request errors` | Error type | Error detail | Description | |--------------------|-------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `incompatibleParameters` | The request specifies two or more parameters that cannot be used in the same request. | | `badRequest (400)` | `invalidFilters` | The request specifies an invalid filter parameter. | | `badRequest (400)` | `invalidPageToken` | The request specifies an invalid page token. | | `badRequest (400)` | `missingRequiredParameter` | The request is missing a required parameter. | | `badRequest (400)` | `unexpectedParameter` | The request specifies an unexpected parameter. | | `forbidden (403)` | `accountDelegationForbidden` | The authenticated user cannot act on behalf of the specified Google Account. | | `forbidden (403)` | `authenticatedUserAccountClosed` | The YouTube account of the authenticated user is closed. In case the authenticated user is acting on behalf of another Google Account, then this error refers to the latter. | | `forbidden (403)` | `authenticatedUserAccountSuspended` | The YouTube account of the authenticated user is suspended. In case the authenticated user is acting on behalf of another Google Account, then this error refers to the latter. | | `forbidden (403)` | `authenticatedUserNotChannel` | For this request the authenticated user must resolve to a channel, but does not. If your request is authenticated and uses the `onBehalfOfContentOwner` delegation parameter, then you should also set the `onBehalfOfContentOwnerChannel` parameter. | | `forbidden (403)` | `channelClosed` | The channel identified in the request has been closed. | | `forbidden (403)` | `channelNotFound` | The channel identified in the request cannot be found. | | `forbidden (403)` | `channelSuspended` | The channel identified in the request has been suspended. | | `forbidden (403)` | `cmsUserAccountNotFound` | The CMS user is not allowed to act on behalf of the specified content owner. | | `forbidden (403)` | `insufficientCapabilities` | The CMS user has insufficient capabilities. | | `forbidden (403)` | `insufficientPermissions` | The OAuth 2.0 token provided for the request specifies scopes that are insufficient for accessing the requested data. | | `notFound (404)` | `contentOwnerAccountNotFound` | The specified content owner account was not found. | ### `Request context errors` | Error type | Error detail | Description | |----------------------|---------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `invalidLanguage` | The `hl` parameter value does not specify a valid language code. | | `badRequest (400)` | `invalidMine` | The request's use of the `mine` parameter is not supported. | | `badRequest (400)` | `invalidMine` | The `mine` parameter cannot be used in requests where the authenticated user is a YouTube partner. You should either remove the `mine` parameter, authenticate as a YouTube user by removing the `onBehalfOfContentOwner` parameter, or act as one of the partner's channels by providing the `onBehalfOfContentOwnerChannel` parameter if available for the called method. | | `badRequest (400)` | `invalidPart` | The request's `part` parameter specifies some parts that cannot be written at the same time. | | `badRequest (400)` | `invalidRegionCode` | The `regionCode` parameter specifies an invalid region code. | | `badRequest (400)` | `unexpectedPart` | The request's `part` parameter specifies an unexpected value. | | `badRequest (400)` | `unknownPart` | The request's `part` parameter specifies an unknown value. | | `badRequest (400)` | `unsupportedLanguageCode` | The `hl` parameter value does not specify a supported language code. | | `badRequest (400)` | `unsupportedRegionCode` | The `regionCode` parameter specifies an unsupported region code. | | `unauthorized (401)` | `authorizationRequired` | The request uses the `mine` parameter but is not properly authorized. | | `unauthorized (401)` | `youtubeSignupRequired` | This error indicates that the user has an unlinked Google Account, which means that the user has a [Google Account](http://www.google.com/support/accounts/bin/answer.py?answer=27439) but does not have a YouTube channel. Such users can access many features that are dependent on user authorization, such as rating videos or adding videos to a `watch_later` playlist. However, as an example, the user would need a YouTube channel to be able to upload a video. A user who has a Gmail account or an Android device is certain to have a Google Account but may not have already linked that Google Account to a YouTube channel. This error is commonly seen if you try to use the OAuth 2.0 Service Account flow. YouTube does not support Service Accounts, and if you attempt to authenticate using a Service Account, you will get this error. The [YouTube API blog post](http://apiblog.youtube.com/2011/10/introducing-google-account-support-and.html) introducing Google Account support also discusses the `youtubeSignupRequired` error in more detail. Although the blog post explains the error for API version 2.1, the meaning of the error is still applicable. | ## activities The following tables identify error messages that the API returns in response to calls related to `activities` resources. These methods could also return errors listed in the [Common request errors](https://developers.google.com/youtube/v3/docs/errors#youtube.api.CommonRequestError) section. ### `activities.list` | Error type | Error detail | Description | |----------------------|---------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `forbidden (403)` | `homeParameterDeprecated` | The user's home page activity data is not available through this API. This error might occur if you set the `home` parameter to `true` in an unauthorized request. | | `forbidden (403)` | `forbidden` | The request is not properly authorized. | | `notFound (404)` | `channelNotFound` | The channel ID identified by the request's `channelId` parameter cannot be found. | | `notFound (404)` | `homeChannelNotFound` | A YouTube home page feed cannot be found for the currently-authenticated user. | | `unauthorized (401)` | `authorizationRequired` | The request uses the `home` parameter but is not properly authorized. | ## captions The following tables identify error messages that the API returns in response to calls related to `captions` resources. These methods could also return errors listed in the [Common request errors](https://developers.google.com/youtube/v3/docs/errors#youtube.api.CommonRequestError) section. ### `captions.delete` | Error type | Error detail | Description | |-------------------|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------| | `forbidden (403)` | `forbidden` | The permissions associated with the request are not sufficient to delete the caption track. The request might not be properly authorized. | | `notFound (404)` | `captionNotFound` | The caption track couldn't be found. Check the value of the request's `id` parameter to ensure that it is correct. | ### `captions.download` | Error type | Error detail | Description | |----------------------|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `forbidden (403)` | `forbidden` | The permissions associated with the request are not sufficient to download the caption track. The request might not be properly authorized. | | `invalidValue (400)` | `couldNotConvert` | The caption track data couldn't be converted to the requested language and/or format. Ensure that the requested `tfmt` and `tlang` values are valid, and that the `snippet.status` of the requested caption track is not `failed`. | | `notFound (404)` | `captionNotFound` | The caption track couldn't be found. Check the value of the request's `id` parameter to ensure that it is correct. | ### `captions.insert` | Error type | Error detail | Description | |----------------------|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `contentRequired` | The request does not contain the caption track contents. | | `conflict (409)` | `captionExists` | The specified video already has a caption track with the given `snippet.language` and `snippet.name`. A video can have multiple tracks for the same language, but each track must have a different name. There are multiple ways to address the error. You could delete the existing track and then insert a new one or change the name of the new track before inserting it. | | `forbidden (403)` | `forbidden` | The permissions associated with the request are not sufficient to upload the caption track. The request might not be properly authorized. | | `invalidValue (400)` | `invalidMetadata` | The request contains invalid metadata values, which prevent the track from being created. Confirm that the request specifies valid values for the `snippet.language`, `snippet.name`, and `snippet.videoId` properties. The `snippet.isDraft` property can also be included, but it is not required. | | `notFound (404)` | `videoNotFound` | The video identified by the `videoId` parameter couldn't be found. | | `invalidValue (400)` | `nameTooLong` | The `snippet.name` specified in the request is too long. The maximum length supported is 150 characters. | ### `captions.list` | Error type | Error detail | Description | |-------------------|-------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `forbidden (403)` | `forbidden` | One or more caption tracks couldn't be retrieved because the permissions associated with the request are not sufficient to retrieve the requested resources. The request might not be properly authorized. | | `notFound (404)` | `captionNotFound` | One or more of the specified caption tracks couldn't be found. This error occurs if the `videoId` parameter identifies an actual video, but the `id` parameter either identifies caption track IDs that don't exist or track IDs that are associated with other videos. Check the values of the request's `id` and `videoId` parameters to ensure that they are correct. | | `notFound (404)` | `videoNotFound` | The video identified by the `videoId` parameter couldn't be found. | ### `captions.update` | Error type | Error detail | Description | |--------------------|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `contentRequired` | The request did not upload an updated caption file. The actual track contents are required if the `sync` parameter is set to `true`. | | `forbidden (403)` | `forbidden` | The permissions associated with the request are not sufficient to update the caption track. The request might not be properly authorized. | | `notFound (404)` | `captionNotFound` | The specified caption track couldn't be found. Check the value of the request's `id` parameter to ensure that it is correct. | ## channelBanners The following tables identify error messages that the API returns in response to calls related to `channelBanners` resources. These methods could also return errors listed in the [Common request errors](https://developers.google.com/youtube/v3/docs/errors#youtube.api.CommonRequestError) section. ### `channelBanners.insert` | Error type | Error detail | Description | |--------------------|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `bannerAlbumFull` | Your YouTube Channel Art album has too many images. Please go to , navigate to the albums page, and remove some from images from that album. | | `badRequest (400)` | `mediaBodyRequired` | The request does not include the image content. | ## channelSections The following tables identify error messages that the API returns in response to calls related to `channelSections` resources. These methods could also return errors listed in the [Common request errors](https://developers.google.com/youtube/v3/docs/errors#youtube.api.CommonRequestError) section. ### `channelSections.delete` | Error type | Error detail | Description | |----------------------|---------------------------|-------------------------------------------------------------------------------------------| | `badRequest (400)` | `notEditable` | This channel section cannot be deleted. | | `forbidden (403)` | `channelSectionForbidden` | The request is not properly authenticated or not supported for this channel. | | `invalidValue (400)` | `idInvalid` | The `id` property specifies an invalid channel section ID. | | `invalidValue (400)` | `idRequired` | The `id` property must specify a value that identifies the channel section being deleted. | | `notFound (404)` | `channelNotFound` | The channel is not found. | | `notFound (404)` | `channelSectionNotFound` | The channel section you are trying to update cannot be found. | ### `channelSections.insert` | Error type | Error detail | Description | |----------------------|------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `defaultLanguageNotSetError` | The `channelSection` resource's `snippet.defaultLanguage` property must be set to successfully insert or update the `localizations` object for that resource. | | `badRequest (400)` | `invalidLanguage` | One of the language keys of the `localizations` object failed validation. Use the [channelSections.list](https://developers.google.com/youtube/v3/docs/channelSections/list) method to retrieve valid values and update them following the guidelines in the `a href="/youtube/v3/docs/channelSections#resource">channelSections` resource documentation. | | `badRequest (400)` | `notEditable` | This channel section cannot be created. | | `badRequest (400)` | `styleRequired` | The `channelSection` resource must specify a value for the `snippet.style` field. | | `badRequest (400)` | `targetInvalidCountry` | One of the values in the `targeting.countries` list failed validation. Use the [channelSections.list](https://developers.google.com/youtube/v3/docs/channelSections/list) method to retrieve valid values and update them following the guidelines in the `a href="/youtube/v3/docs/channelSections#resource">channelSections` resource documentation. | | `badRequest (400)` | `targetInvalidLanguage` | One of the values in the `targeting.languages` list failed validation. Use the [channelSections.list](https://developers.google.com/youtube/v3/docs/channelSections/list) method to retrieve valid values and update them following the guidelines in the `a href="/youtube/v3/docs/channelSections#resource">channelSections` resource documentation. | | `badRequest (400)` | `targetInvalidRegion` | One of the values in the `targeting.regions` list failed validation. Use the [channelSections.list](https://developers.google.com/youtube/v3/docs/channelSections/list) method to retrieve valid values and update them following the guidelines in the `a href="/youtube/v3/docs/channelSections#resource">channelSections` resource documentation. | | `badRequest (400)` | `typeRequired` | The `channelSection` resource must specify a value for the `snippet.type` field. | | `forbidden (403)` | `channelSectionForbidden` | The request is not properly authenticated or is not supported for this channel. | | `invalidValue (400)` | `channelNotActive` | At least one of the specified channels is not active. | | `invalidValue (400)` | `channelsDuplicated` | The request failed because it specified duplicate channels. | | `invalidValue (400)` | `channelsNeeded` | If the `snippet.type` property has a value of `multipleChannels`, then the `contentDetails.channels[]` property must be specified and must specify at least one channel. | | `invalidValue (400)` | `channelsNotExpected` | The resource provided with the request specified a value for the `contentDetails.channels[]` property, but channels are not expected for this type of channel section. | | `invalidValue (400)` | `contentDetailsNeeded` | The resource you are inserting must contain a `contentDetails` object for this type of channel section. | | `invalidValue (400)` | `inValidPosition` | The `snippet.position` property contains an invalid value. | | `invalidValue (400)` | `maxChannelSectionExceeded` | The request cannot be completed because the channel already has the maximum number of channel sections. | | `invalidValue (400)` | `maxChannelsExceeded` | The request failed because it attempted to include too many channels in the channel section. | | `invalidValue (400)` | `maxPlaylistExceeded` | The request failed because it attempted to include too many playlists in the channel section. | | `invalidValue (400)` | `onePlaylistNeeded` | If the `snippet.type` property has a value of `singlePlaylist`, then the `contentDetails.playlists[]` property must specify exactly one playlist. | | `invalidValue (400)` | `ownChannelInChannels` | You cannot include your own channel in a channel section that appears on that channel. | | `invalidValue (400)` | `playlistIsPrivate` | One or more of the specified playlists are private and, therefore, cannot be included in the channel section. | | `invalidValue (400)` | `playlistsDuplicated` | The request failed because it specified duplicate playlists. | | `invalidValue (400)` | `playlistsNeeded` | If the `snippet.type` property has a value of `singlePlaylist` or `multiplePlaylists`, then the `contentDetails.playlists[]` property must be specified. | | `invalidValue (400)` | `playlistsNotExpected` | The resource provided with the request specified a value for the `contentDetails.playlists[]` property, but playlists are not expected for this type of channel section. | | `invalidValue (400)` | `snippetNeeded` | You must specify a `snippet` to create the channel section. | | `invalidValue (400)` | `titleLengthExceeded` | The value of the `snippet.title` property is too long. | | `invalidValue (400)` | `titleRequired` | If the `snippet.type` property has a value of `multiplePlaylists` or `multipleChannels`, then you must set the section's title by specifying a value for the `snippet.title` property. | | `notFound (404)` | `channelNotFound` | One or more of the specified channels cannot be found. | | `notFound (404)` | `playlistNotFound` | One or more of the specified playlists cannot be found. | ### `channelSections.list` | Error type | Error detail | Description | |----------------------|---------------------------|----------------------------------------------------------------------------| | `forbidden (403)` | `channelSectionForbidden` | The requester is not allowed to access the requested channel sections. | | `invalidValue (400)` | `idInvalid` | The request specifies an invalid channel section ID. | | `invalidValue (400)` | `invalidCriteria` | The request couldn't be completed because the filter criteria are invalid. | | `notFound (404)` | `channelNotFound` | The channel associated with the request cannot be found. | | `notFound (404)` | `channelSectionNotFound` | The channel section associated with the request cannot be found. | ### `channelSections.update` | Error type | Error detail | Description | |----------------------|------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `defaultLanguageNotSetError` | The `channelSection` resource's `snippet.defaultLanguage` property must be set to successfully insert or update the `localizations` object for that resource. | | `badRequest (400)` | `invalidLanguage` | One of the language keys of the `localizations` object failed validation. Use the [channelSections.list](https://developers.google.com/youtube/v3/docs/channelSections/list) method to retrieve valid values and update them following the guidelines in the `a href="/youtube/v3/docs/channelSections#resource">channelSections` resource documentation. | | `badRequest (400)` | `notEditable` | This channel section cannot be edited. | | `badRequest (400)` | `styleRequired` | The `channelSection` resource must specify a value for the `snippet.style` field. | | `badRequest (400)` | `targetInvalidCountry` | One of the values in the `targeting.countries` list failed validation. Use the [channelSections.list](https://developers.google.com/youtube/v3/docs/channelSections/list) method to retrieve valid values and update them following the guidelines in the `a href="/youtube/v3/docs/channelSections#resource">channelSections` resource documentation. | | `badRequest (400)` | `targetInvalidLanguage` | One of the values in the `targeting.languages` list failed validation. Use the [channelSections.list](https://developers.google.com/youtube/v3/docs/channelSections/list) method to retrieve valid values and update them following the guidelines in the `a href="/youtube/v3/docs/channelSections#resource">channelSections` resource documentation. | | `badRequest (400)` | `targetInvalidRegion` | One of the values in the `targeting.regions` list failed validation. Use the [channelSections.list](https://developers.google.com/youtube/v3/docs/channelSections/list) method to retrieve valid values and update them following the guidelines in the `a href="/youtube/v3/docs/channelSections#resource">channelSections` resource documentation. | | `badRequest (400)` | `typeRequired` | The `channelSection` resource must specify a value for the `snippet.type` field. | | `forbidden (403)` | `channelSectionForbidden` | The request is not properly authenticated or is not supported for this channel. | | `invalidValue (400)` | `channelNotActive` | At least one of the specified channels is not active. | | `invalidValue (400)` | `channelsDuplicated` | The request failed because it specified duplicate channels. | | `invalidValue (400)` | `channelsNeeded` | If the `snippet.type` property has a value of `multipleChannels`, then the `contentDetails.channels[]` property must be specified and must specify at least one channel. | | `invalidValue (400)` | `channelsNotExpected` | The resource provided with the request specified a value for the `contentDetails.channels[]` property, but channels are not expected for this type of channel section. | | `invalidValue (400)` | `contentDetailsNeeded` | The resource you are updating must contain a `contentDetails` object for this type of channel section. | | `invalidValue (400)` | `idInvalid` | The `id` property specifies an invalid channel section ID. | | `invalidValue (400)` | `idRequired` | The `id` property must specify a value that identifies the channel section being updated. | | `invalidValue (400)` | `inValidPosition` | The `snippet.position` property contains an invalid value. | | `invalidValue (400)` | `maxChannelsExceeded` | The request failed because it attempted to include too many channels in the channel section. | | `invalidValue (400)` | `maxPlaylistExceeded` | The request failed because it attempted to include too many playlists in the channel section. | | `invalidValue (400)` | `onePlaylistNeeded` | If the `snippet.type` property has a value of `singlePlaylist`, then the `contentDetails.playlists[]` property must specify exactly one playlist. | | `invalidValue (400)` | `ownChannelInChannels` | You cannot include your own channel in a channel section that appears on that channel. | | `invalidValue (400)` | `playlistIsPrivate` | One or more of the specified playlists are private and, therefore, cannot be included in the channel section. | | `invalidValue (400)` | `playlistsDuplicated` | The request failed because it specified duplicate playlists. | | `invalidValue (400)` | `playlistsNeeded` | If the `snippet.type` property has a value of `singlePlaylist` or `multiplePlaylists`, then the `contentDetails.playlists[]` property must be specified. | | `invalidValue (400)` | `playlistsNotExpected` | The resource provided with the request specified a value for the `contentDetails.playlists[]` property, but playlists are not expected for this type of channel section. | | `invalidValue (400)` | `snippetNeeded` | You must specify a `snippet` to update the channel section. | | `invalidValue (400)` | `titleLengthExceeded` | The value of the `snippet.title` property is too long. | | `invalidValue (400)` | `titleRequired` | If the `snippet.type` property has a value of `multiplePlaylists` or `multipleChannels`, then you must set the section's title by specifying a value for the `snippet.title` property. | | `notFound (404)` | `channelNotFound` | One or more of the specified channels cannot be found. | | `notFound (404)` | `channelSectionNotFound` | The channel section you are trying to update cannot be found. | | `notFound (404)` | `playlistNotFound` | One or more of the specified playlists cannot be found. | ## channels The following tables identify error messages that the API returns in response to calls related to `channels` resources. These methods could also return errors listed in the [Common request errors](https://developers.google.com/youtube/v3/docs/errors#youtube.api.CommonRequestError) section. ### `channels.list` | Error type | Error detail | Description | |--------------------|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `invalidCriteria` | A maximum of one of the following filters may be specified:`id`, `mySubscribers`, `categoryId`, `mine`, `managedByMe`, `forUsername`. In case of content owner authentication using the `onBehalfOfContentOwner` parameter, only the `id` or `managedByMe` may be specified. | | `forbidden (403)` | `channelForbidden` | The channel specified by the `id` parameter does not support the request or the request is not properly authorized. | | `notFound (404)` | `categoryNotFound` | The category identified by the `categoryId` parameter cannot be found. | | `notFound (404)` | `channelNotFound` | The channel specified in the `id` parameter cannot be found. | ### `channels.update` | Error type | Error detail | Description | |--------------------|-------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `brandingValidationError` | One of the values in the `brandingSettings` object failed validation. Use the [channels.list](https://developers.google.com/youtube/v3/docs/channels/list) method to retrieve the existing settings for the channel, and update the property values following the guidelines in the [channels](https://developers.google.com/youtube/v3/docs/channels#resource) resource documentation. | | `badRequest (400)` | `channelTitleUpdateForbidden` | When updating a channel's `brandingSettings part`, you must set the `brandingSettings.channel.title` property's value to the channel's current title or omit the property. The API returns an error if you change the property's value. | | `badRequest (400)` | `defaultLanguageNotSetError` | The `defaultLanguage` must be set to update `localizations`. | | `badRequest (400)` | `invalidBrandingOption` | One of the branding settings that you specified does not exist. Use the [channels.list](https://developers.google.com/youtube/v3/docs/channels/list) method to retrieve valid values and make sure to update them following the guidelines in the [channels](https://developers.google.com/youtube/v3/docs/channels#resource) resource documentation. | | `badRequest (400)` | `invalidCustomMessage` | The request metadata specifies an invalid custom message. Check the value of the [invideoPromotion.items[].customMessage](https://developers.google.com/youtube/v3/docs/channels#invideoPromotion.items[].customMessage) property in the resource that the request sent. | | `badRequest (400)` | `invalidDuration` | The request metadata specifies an invalid duration in the invideoPromotion part. | | `badRequest (400)` | `invalidDuration` | The request metadata specifies an invalid position type for determining how the promoted item is positioned in the video player. Check the value of the [invideoPromotion.position.type](https://developers.google.com/youtube/v3/docs/channels#invideoPromotion.position.type) property in the resource that the request sent. | | `badRequest (400)` | `invalidRecentlyUploadedBy` | The request metadata specifies an invalid channel ID. Check the value of the [invideoPromotion.items[].id.recentlyUploadedBy](https://developers.google.com/youtube/v3/docs/channels#invideoPromotion.items[].id.recentlyUploadedBy) property in the resource that the request sent. | | `badRequest (400)` | `invalidTimingOffset` | The request metadata specifies an invalid timing offset in the invideoPromotion part. | | `badRequest (400)` | `invalidTimingOffset` | The request metadata specifies an invalid timing offset for determining when the promoted item should be displayed in the video player. Check the value of the [invideoPromotion.timing.offsetMs](https://developers.google.com/youtube/v3/docs/channels#invideoPromotion.timing.offsetMs) property in the resource that the request sent. | | `badRequest (400)` | `invalidTimingType` | The request metadata specifies an invalid timing method for determining when the promoted item should be displayed in the video player. Check the value of the [invideoPromotion.timing.type](https://developers.google.com/youtube/v3/docs/channels#invideoPromotion.timing.type) property in the resource that the request sent. | | `badRequest (400)` | `localizationValidationError` | One of the values in the localizations object failed validation. Use the [channels.list](https://developers.google.com/youtube/v3/docs/channels/list) method to retrieve valid values and make sure to update them following the guidelines in [the channels resource documentation.](https://developers.google.com/youtube/v3/docs/channels#resource) | | `badRequest (400)` | `tooManyPromotedItems` | Number of allowed promoted items exceeded in the invideoPromotion part. | | `forbidden (403)` | `channelForbidden` | The channel specified in the `id` parameter does not support the request or the request is not properly authorized. | | `forbidden (403)` | `promotedVideoNotAllowed` | The channel that the API request is attempting to update cannot be found. Check the value of the `id` property in the `channel` resource that the request sent to ensure that the channel ID is correct. | | `forbidden (403)` | `websiteLinkNotAllowed` | The specified website URL is not allowed. | | `notFound (404)` | `channelNotFound` | The channel specified by the `id` parameter cannot be found or does not have branding options. | | `notFound (404)` | `channelNotFound` | The channel specified in the `id` parameter cannot be found. | | `notFound (404)` | `unknownChannelId` | The specified channel ID was not found. | | `notFound (404)` | `unknownChannelId` | The specified recentlyUploadedBy channel ID was not found. | | `notFound (404)` | `unknownVideoId` | The [video ID](https://developers.google.com/youtube/v3/docs/channels#invideoPromotion.items[].videoId) specified as a promoted item cannot be found. | | `required (400)` | `requiredItemIdType` | The request metadata must specify an item type in the invideoPromotion part. | | `required (400)` | `requiredItemId` | The request metadata must specify an item in the invideoPromotion part. | | `required (400)` | `requiredTimingOffset` | The request metadata must specify a default timing offset so that YouTube can determine when to display the promoted item. Set the value of the [invideoPromotion.defaultTiming.offsetMs](https://developers.google.com/youtube/v3/docs/channels#invideoPromotion.defaultTiming.offsetMs) property in the resource that the request sends. | | `required (400)` | `requiredTimingOffset` | The request metadata must specify a timing offset so that YouTube can determine when to display the promoted item. Set the value of the [invideoPromotion.timing.offsetMs](https://developers.google.com/youtube/v3/docs/channels#invideoPromotion.timing.offsetMs) property in the resource that the request sends. | | `required (400)` | `requiredTimingType` | The request metadata must specify a timing method so that YouTube can determine when to display the promoted item. Set the value of the [invideoPromotion.defaultTiming.type](https://developers.google.com/youtube/v3/docs/channels#invideoPromotion.defaultTiming.type) property in the resource that the request sends. | | `required (400)` | `requiredTimingType` | The request metadata must specify a timing method so that YouTube can determine when to display the promoted item. Set the value of the [invideoPromotion.timing.type](https://developers.google.com/youtube/v3/docs/channels#invideoPromotion.timing.type) property in the resource that the request sends. | | `required (400)` | `requiredTiming` | The request metadata must specify a timing for each item in the `invideoPromotion` part. | | `required (400)` | `requiredVideoId` | The request metadata must specify a [video ID](https://developers.google.com/youtube/v3/docs/channels#invideoPromotion.items[].videoId) to identify the promoted item. | | `required (400)` | `requiredWebsiteUrl` | The request metadata must specify a website URL in the invideoPromotion part. Set the value of the [invideoPromotion.items[].id.websiteUrl](https://developers.google.com/youtube/v3/docs/channels#invideoPromotion.items[].id.websiteUrl) property in the resource that the request sends. | ## commentThreads The following tables identify error messages that the API returns in response to calls related to `commentThreads` resources. These methods could also return errors listed in the [Common request errors](https://developers.google.com/youtube/v3/docs/errors#youtube.api.CommonRequestError) section. ### `commentThreads.list` | Error type | Error detail | Description | |--------------------|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `operationNotSupported` | The API request is invalid or improperly formed. Consequently, the API server couldn't understand the request. | | `badRequest (400)` | `processingFailure` | The API server failed to successfully process the request. While this can be a transient error, it usually indicates that the request's input is invalid. Check the structure of the `commentThread` resource in the request body to ensure that it is valid. | | `forbidden (403)` | `commentsDisabled` | The video identified by the [videoId](https://developers.google.com/youtube/v3/docs/commentThreads/list#videoId) parameter has disabled comments. | | `forbidden (403)` | `forbidden` | One or more of the requested comment threads cannot be retrieved due to insufficient permissions. The request might not be properly authorized. | | `notFound (404)` | `channelNotFound` | The channel identified by the [allThreadsRelatedToChannelId](https://developers.google.com/youtube/v3/docs/commentThreads/list#allThreadsRelatedToChannelId) parameter couldn't be found. | | `notFound (404)` | `commentThreadNotFound` | One or more of the specified comment threads cannot be found. Check the values of the request's [id](https://developers.google.com/youtube/v3/docs/commentThreads/list#id) parameter to ensure that it is correct. | | `notFound (404)` | `videoNotFound` | The video identified by the [videoId](https://developers.google.com/youtube/v3/docs/commentThreads/list#videoId) parameter couldn't be found. | ### `commentThreads.insert` | Error type | Error detail | Description | |--------------------|--------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `channelOrVideoIdMissing` | Each comment thread must be linked to a channel or video. Make sure the resource specifies values for both the [snippet.channelId](https://developers.google.com/youtube/v3/docs/commentThreads#snippet.channelId) and [snippet.videoId](https://developers.google.com/youtube/v3/docs/commentThreads#snippet.videoId) properties. A comment on a video appears on the video watch page. | | `badRequest (400)` | `commentTextRequired` | The `comment` resource that is being inserted must specify a value for the `snippet.topLevelComment.snippet.textOriginal` property. Comments cannot be empty. | | `badRequest (400)` | `commentTextTooLong` | The `comment` resource that is being inserted contains too many characters in the `snippet.topLevelComment.snippet.textOriginal` property. | | `badRequest (400)` | `invalidCommentThreadMetadata` | The request metadata is invalid. | | `badRequest (400)` | `processingFailure` | The API server failed to successfully process the request. While this can be a transient error, it usually indicates that the request's input is invalid. Check the structure of the `commentThread` resource in the request body to ensure that it is valid. | | `forbidden (403)` | `forbidden` | The comment thread could be created due to insufficient permissions. The request might not be properly authorized. | | `forbidden (403)` | `ineligibleAccount` | The YouTube account used to authorize the API request must be merged with the user's Google Account to insert a comment or comment thread. | | `notFound (404)` | `channelNotFound` | The specified channel couldn't be found. Check the value of the [snippet.channelId](https://developers.google.com/youtube/v3/docs/commentThreads#snippet.channelId) property to ensure it is correct. | | `notFound (404)` | `videoNotFound` | The specified video couldn't be found. Check the value of the [snippet.videoId](https://developers.google.com/youtube/v3/docs/commentThreads#snippet.videoId) property to ensure it is correct. | ## comments The following tables identify error messages that the API returns in response to calls related to `comments` resources. These methods could also return errors listed in the [Common request errors](https://developers.google.com/youtube/v3/docs/errors#youtube.api.CommonRequestError) section. ### `comments.list` | Error type | Error detail | Description | |--------------------|-------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `operationNotSupported` | The API request is invalid or improperly formed. Consequently, the API server couldn't understand the request. | | `forbidden (403)` | `forbidden` | One or more of the requested comments cannot be retrieved due to insufficient permissions. The request might not be properly authorized. | | `notFound (404)` | `commentNotFound` | One or more of the specified comments cannot be found. Check the values of the request's [id](https://developers.google.com/youtube/v3/docs/comments/list#id) and [parentId](https://developers.google.com/youtube/v3/docs/comments/list#parentId) parameters to ensure that they are correct. | ### `comments.setModerationStatus` | Error type | Error detail | Description | |--------------------|-------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `banWithoutReject` | The `banAuthor` parameter can only be used if the `moderationStatus` parameter value is `rejected`. | | `badRequest (400)` | `operationNotSupported` | The API request is invalid or improperly formed. Consequently, the API server couldn't understand the request. | | `badRequest (400)` | `processingFailure` | The API server failed to successfully process the request. While this can be a transient error, it usually indicates that the request's input is invalid. | | `forbidden (403)` | `forbidden` | The moderation status of one or more comments cannot be set due to insufficient permissions. The request might not be properly authorized. | | `notFound (404)` | `commentNotFound` | One or more of the comments that the request is trying to update cannot be found. Check the values of the request's [id](https://developers.google.com/youtube/v3/docs/comments/setModerationStatus#id) parameter to ensure that they are correct. | ### `comments.insert` | Error type | Error detail | Description | |--------------------|--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `commentTextRequired` | The `comment` resource that is being inserted must specify a value for the `snippet.textOriginal` property. Comments cannot be empty. | | `badRequest (400)` | `commentTextTooLong` | The `comment` resource that is being inserted contains too many characters in the `snippet.textOriginal` property. | | `badRequest (400)` | `invalidCommentMetadata` | The request metadata is invalid. | | `badRequest (400)` | `operationNotSupported` | The API user is not able to insert a comment in reply to the top-level comment identified by the `snippet.parentId` property. In a `commentThread` resource, the [snippet.canReply](https://developers.google.com/youtube/v3/docs/commentThreads#snippet.canReply) property indicates whether the current viewer can reply to the thread. | | `badRequest (400)` | `parentCommentIsPrivate` | The specified parent comment is private. The API does not support replies to private comments. | | `badRequest (400)` | `parentIdMissing` | The comment that is being inserted must be linked to a parent comment. However, the `comment` resource in the body of the API request did not specify a value for the [snippet.parentId](https://developers.google.com/youtube/v3/docs/comments#snippet.parentId) property. | | `badRequest (400)` | `processingFailure` | The API server failed to successfully process the request. While this can be a transient error, it usually indicates that the request's input is invalid. Check the structure of the `comment` resource in the request body to ensure that it is valid. | | `forbidden (403)` | `forbidden` | The comment cannot be created due to insufficient permissions. The request might not be properly authorized. | | `forbidden (403)` | `ineligibleAccount` | The YouTube account used to authorize the API request must be merged with the user's Google Account to insert a comment or comment thread. | | `notFound (404)` | `parentCommentNotFound` | The specified parent comment couldn't be found. Check the value of the [snippet.parentId](https://developers.google.com/youtube/v3/docs/comments#snippet.parentId) property in the request body to ensure that it is correct. | ### `comments.delete` | Error type | Error detail | Description | |--------------------|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `processingFailure` | The API server failed to successfully process the request. While this can be a transient error, it usually indicates that the request's input is invalid. | | `forbidden (403)` | `forbidden` | The comment couldn't be deleted because of insufficient permissions. The request might not be properly authorized. | | `notFound (404)` | `commentNotFound` | The specified comment couldn't be found. Check the value of the request's [id](https://developers.google.com/youtube/v3/docs/comments/delete#id) parameter to ensure that it is correct. | ### `comments.update` | Error type | Error detail | Description | |--------------------|--------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `commentTextTooLong` | The `comment` resource that is being updated contains too many characters in the `snippet.textOriginal` property. | | `badRequest (400)` | `invalidCommentMetadata` | The request metadata is invalid. | | `badRequest (400)` | `operationNotSupported` | The API request is invalid or improperly formed. Consequently, the API server couldn't understand the request. | | `badRequest (400)` | `processingFailure` | The API server failed to successfully process the request. While this can be a transient error, it usually indicates that the request's input is invalid. Check the structure of the `comment` resource in the request body to ensure that it is valid. | | `forbidden (403)` | `forbidden` | The comment couldn't be updated due to insufficient permissions. The request might not be properly authorized. | | `forbidden (403)` | `ineligibleAccount` | The YouTube account used to authorize the API request must be merged with the user's Google Account to update a comment or comment thread. | | `notFound (404)` | `commentNotFound` | The specified comment couldn't be found. Check the value of the [id](https://developers.google.com/youtube/v3/docs/comments#id) property in the request body to ensure that it is correct. | ## members The following tables identify error messages that the API returns in response to calls related to `members` resources. These methods could also return errors listed in the [Common request errors](https://developers.google.com/youtube/v3/docs/errors#youtube.api.CommonRequestError) section. ### `members.list` | Error type | Error detail | Description | |--------------------|----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `channelMembershipsNotEnabled` | The creator channel authorizing the request does not have channel memberships enabled. | | `badRequest (400)` | `invalidMode` | The [mode](https://developers.google.com/youtube/v3/docs/errors#mode) parameter value is invalid. This error might occur if the [pageToken](https://developers.google.com/youtube/v3/docs/errors#pageToken) parameter specifies a token that was retrieved using a different mode than the one specified. | | `badRequest (400)` | `invalidPageToken` | The [pageToken](https://developers.google.com/youtube/v3/docs/errors#pageToken) parameter value is invalid. This error occurs if the page token used in the request has expired. | | `badRequest (400)` | `invalidHasAccessToLevel` | The [hasAccessToLevel](https://developers.google.com/youtube/v3/docs/errors#hasAccessToLevel) parameter value is invalid. There is no level with the specified [id](https://developers.google.com/youtube/v3/docs/membershipsLevels#id). | | `badRequest (400)` | `invalidFilterByMemberChannelId` | The [filterByMemberChannelId](https://developers.google.com/youtube/v3/docs/errors#filterByMemberChannelId) parameter value is invalid. This error occurs if the [filterByMemberChannelId](https://developers.google.com/youtube/v3/docs/errors#filterByMemberChannelId) parameter value specifies more than 100 channels. | ## membershipsLevels The following tables identify error messages that the API returns in response to calls related to `members` resources. These methods could also return errors listed in the [Common request errors](https://developers.google.com/youtube/v3/docs/errors#youtube.api.CommonRequestError) section. ### `membershipsLevels.list` | Error type | Error detail | Description | |--------------------|--------------------------------|----------------------------------------------------------------------------------------| | `badRequest (400)` | `channelMembershipsNotEnabled` | The creator channel authorizing the request does not have channel memberships enabled. | ## playlistItems The following tables identify error messages that the API returns in response to calls related to `playlistItems` resources. These methods could also return errors listed in the [Common request errors](https://developers.google.com/youtube/v3/docs/errors#youtube.api.CommonRequestError) section. ### `playlistItems.delete` | Error type | Error detail | Description | |----------------------|--------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| | `forbidden (403)` | `playlistItemsNotAccessible` | The request is not properly authorized to delete the specified playlist item. | | `notFound (404)` | `playlistItemNotFound` | The playlist item identified with the request's `id` parameter cannot be found. | | `invalidValue (400)` | `playlistOperationUnsupported` | The API does not support the ability to delete videos from the specified playlist. For example, you can't delete a video from your uploaded videos playlist. | ### `playlistItems.insert` | Error type | Error detail | Description | |----------------------|-----------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `duplicate` | `videoAlreadyInPlaylist` | The video that you are trying to add to the playlist is already in the playlist. | | `forbidden (403)` | `playlistContainsMaximumNumberOfVideos` | The playlist already contains the maximum allowed number of items. | | `forbidden (403)` | `playlistItemsNotAccessible` | The request is not properly authorized to insert the specified playlist item. | | `invalidValue (400)` | `invalidContentDetails` | The `contentDetails` property in the request is not valid. A possible reason is that `contentDetails.note` field is longer than 280 characters. | | `invalidValue (400)` | `invalidPlaylistItemPosition` | The request attempts to set the playlist item's position to an invalid or unsupported value. Check the value of the `position` property in the resource's `snippet`. | | `invalidValue (400)` | `invalidResourceType` | The `type` specified for the resource ID is not supported for this operation. The resource ID identifies the item being added to the playlist -- such as `youtube#video`. | | `invalidValue (400)` | `manualSortRequired` | The request attempts to set the playlist item's position, but the playlist does not use manual sorting. (For example, playlist items might be sorted by date or popularity.) You can address the error by removing the `snippet.position` element from the resource that the request is inserting. If you want the playlist item to have a particular position in the list, you need to first update the playlist's **Ordering** option to **Manual** in the playlist's settings. This settings can be adjusted in the [YouTube Video Manager](https://www.youtube.com/view_all_playlists). | | `invalidValue (400)` | `videoAlreadyInAnotherSeriesPlaylist` | The video that you are trying to add to the playlist is already in another series playlist. | | `invalidValue (400)` | `playlistOperationUnsupported` | The API does not support the ability to insert videos into the specified playlist. For example, you can't insert a video into your uploaded videos playlist. | | `notFound (404)` | `playlistNotFound` | The playlist identified with the request's `playlistId` parameter cannot be found. | | `notFound (404)` | `videoNotFound` | The video that you are trying to add to the playlist cannot be found. Check the value of the `videoId` property to ensure that it is correct. | | `required (400)` | `channelIdRequired` | The request does not specify a value for the required `channelId` property. | | `required (400)` | `playlistIdRequired` | The request does not specify a value for the required `playlistId` property. | | `required (400)` | `resourceIdRequired` | The request must contain a resource in which the `snippet` object specifies a `resourceId`. | ### `playlistItems.list` | Error type | Error detail | Description | |----------------------|--------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------| | `forbidden (403)` | `playlistItemsNotAccessible` | The request is not properly authorized to retrieve the specified playlist. | | `notFound (404)` | `playlistNotFound` | The playlist identified with the request's `playlistId` parameter cannot be found. | | `notFound (404)` | `videoNotFound` | The video identified with the request's `videoId` parameter cannot be found. | | `required (400)` | `playlistIdRequired` | The subscribe request does not specify a value for the required `playlistId` property. | | `invalidValue (400)` | `playlistOperationUnsupported` | The API does not support the ability to list videos in the specified playlist. For example, you can't list a video in your watch later playlist. | ### `playlistItems.update` | Error type | Error detail | Description | |----------------------|--------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `forbidden (403)` | `playlistItemsNotAccessible` | The request is not properly authorized to update the specified playlist item. | | `invalidValue (400)` | `invalidPlaylistItemPosition` | The request attempts to set the playlist item's position to an invalid or unsupported value. Check the value of the `position` property in the resource's `snippet`. | | `invalidValue (400)` | `invalidResourceType` | The `type` specified for the resource ID is not supported for this operation. The resource ID identifies the item being added to the playlist -- such as `youtube#video`. | | `invalidValue (400)` | `invalidSnippet` | The request does not specify a valid `snippet` property. | | `invalidValue (400)` | `manualSortRequired` | The request attempts to set the playlist item's position, but the playlist does not use manual sorting. (For example, playlist items might be sorted by date or popularity.) You can address the error by removing the `snippet.position` element from the resource that the request is inserting. If you want the playlist item to have a particular position in the list, you need to first update the playlist's **Ordering** option to **Manual** in the playlist's settings. This settings can be adjusted in the [YouTube Video Manager](https://www.youtube.com/view_all_playlists). | | `invalidValue (400)` | `playlistOperationUnsupported` | The API does not support the ability to update videos in the specified playlist. For example, you can't update a video in your uploaded videos playlist. | | `notFound (404)` | `playlistItemNotFound` | The playlist item identified with the request's `id` property cannot be found. | | `notFound (404)` | `playlistNotFound` | The playlist identified with the request's `playlistId` parameter cannot be found. | | `required (400)` | `channelIdRequired` | The request does not specify a value for the required `channelId` property. | | `required (400)` | `playlistIdRequired` | The request does not specify a value for the required `playlistId` property. | | `required (400)` | `playlistItemIdRequired` | The playlist item resource specified in the request must use the `id` property to identify the playlist item that is being updated. | ## playlists The following tables identify error messages that the API returns in response to calls related to `playlists` resources. These methods could also return errors listed in the [Common request errors](https://developers.google.com/youtube/v3/docs/errors#youtube.api.CommonRequestError) section. ### `playlists.delete` | Error type | Error detail | Description | |----------------------|--------------------------------|-------------------------------------------------------------------------------------------------------------------------------------| | `forbidden (403)` | `playlistForbidden` | This operation is forbidden or the request is not properly authorized. | | `notFound (404)` | `playlistNotFound` | The playlist identified with the request's `id` parameter cannot be found. | | `invalidValue (400)` | `playlistOperationUnsupported` | The API does not support the ability to delete the specified playlist. For example, you can't delete your uploaded videos playlist. | ### `playlists.list` | Error type | Error detail | Description | |----------------------|--------------------------------|-----------------------------------------------------------------------------------------------------------------------------------| | `forbidden (403)` | `channelClosed` | The channel specified in the `channelId` parameter has been closed. | | `forbidden (403)` | `channelSuspended` | The channel specified in the `channelId` parameter has been suspended. | | `forbidden (403)` | `playlistForbidden` | The playlist identified with the request's `id` parameter does not support the request or the request is not properly authorized. | | `notFound (404)` | `channelNotFound` | The channel specified in the `channelId` parameter cannot be found. | | `notFound (404)` | `playlistNotFound` | The playlist identified with the request's `id` parameter cannot be found. | | `invalidValue (400)` | `playlistOperationUnsupported` | The API does not support the ability to list the specified playlist. For example, you can't list your watch later playlist. | ### `playlists.insert` | Error type | Error detail | Description | |----------------------|-------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `defaultLanguageNotSetError` | The `defaultLanguage` must be set to update `localizations`. | | `badRequest (400)` | `localizationValidationError` | One of the values in the localizations object failed validation. Use the [playlists.list](https://developers.google.com/youtube/v3/docs/playlist/list) method to retrieve valid values and make sure to update them following the guidelines in [the playlists resource documentation.](https://developers.google.com/youtube/v3/docs/playlists#resource) | | `badRequest (400)` | `maxPlaylistExceeded` | The playlist cannot be created because the channel already has the maximum number of playlists allowed. | | `forbidden (403)` | `playlistForbidden` | This operation is forbidden or the request is not properly authorized. | | `invalidValue (400)` | `invalidPlaylistSnippet` | The request provides an invalid playlist snippet. | | `required (400)` | `playlistTitleRequired` | The request must specify a playlist title. | ### `playlists.update` | Error type | Error detail | Description | |----------------------|--------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `defaultLanguageNotSetError` | The `defaultLanguage` must be set to update `localizations`. | | `badRequest (400)` | `localizationValidationError` | One of the values in the localizations object failed validation. Use the [playlists.list](https://developers.google.com/youtube/v3/docs/playlist/list) method to retrieve valid values and make sure to update them following the guidelines in [the playlists resource documentation.](https://developers.google.com/youtube/v3/docs/playlists#resource) | | `forbidden (403)` | `playlistForbidden` | This operation is forbidden or the request is not properly authorized. | | `invalidValue (400)` | `invalidPlaylistSnippet` | The request provides an invalid playlist snippet. | | `invalidValue (400)` | `playlistOperationUnsupported` | The API does not support the ability to update the specified playlist. For example, you can't update the properties of your uploaded videos playlist. | | `notFound (404)` | `playlistNotFound` | The playlist identified with the request's `id` parameter cannot be found. | | `required (400)` | `playlistTitleRequired` | The request must specify a playlist title. | ## search The following tables identify error messages that the API returns in response to calls related to `search` resources. These methods could also return errors listed in the [Common request errors](https://developers.google.com/youtube/v3/docs/errors#youtube.api.CommonRequestError) section. ### `search.list` | Error type | Error detail | Description | |--------------------|----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `invalidChannelId` | The `channelId` parameter specified an invalid channel ID. | | `badRequest (400)` | `invalidLocation` | The `location` and/or `locationRadius` parameter value was formatted incorrectly. | | `badRequest (400)` | `invalidRelevanceLanguage` | The `relevanceLanguage` parameter value was formatted incorrectly. | | `badRequest (400)` | `invalidSearchFilter` | The request contains an invalid combination of search filters and/or restrictions. You must set the `type` parameter to `video` if you set a value for the `eventType`, `videoCaption`, `videoCategoryId`, `videoDefinition`, `videoDimension`, `videoDuration`, `videoEmbeddable`, `videoLicense`, `videoSyndicated`, or `videoType` parameters. | ## subscriptions The following tables identify error messages that the API returns in response to calls related to `subscriptions` resources. These methods could also return errors listed in the [Common request errors](https://developers.google.com/youtube/v3/docs/errors#youtube.api.CommonRequestError) section. ### `subscriptions.delete` | Error type | Error detail | Description | |-------------------|-------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------| | `forbidden (403)` | `subscriptionForbidden` | The request is not properly authenticated or not supported for this channel. | | `notFound (404)` | `subscriptionNotFound` | The subscription that you are trying to delete cannot be found. Check the value of the request's `id` parameter to ensure that it is correct. | ### `subscriptions.insert` | Error type | Error detail | Description | |--------------------|-------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `subscriptionDuplicate` | The subscription that you are trying to create already exists. | | `badRequest (400)` | `subscriptionForbidden` | You have reached your maximum number of subscriptions. | | `badRequest (400)` | `subscriptionForbidden` | Too many recent subscriptions. Please try again in a few hours. | | `badRequest (400)` | `subscriptionForbidden` | Subscribing to your own channel is not supported. | | `forbidden (403)` | `subscriptionForbidden` | The request is not properly authenticated or not supported for this channel. | | `notFound (404)` | `publisherNotFound` | The resource specified by the request's `snippet.resourceId` property cannot be found. | | `notFound (404)` | `subscriberNotFound` | The subscriber identified with the request cannot be found. | | `required (400)` | `publisherRequired` | The subscription resource specified in the request must use the `snippet.resourceId` property to identify the channel that is being subscribed to. | ### `subscriptions.list` | Error type | Error detail | Description | |-------------------|-------------------------|------------------------------------------------------------------------------------| | `forbidden (403)` | `accountClosed` | Subscriptions couldn't be retrieved because the subscriber's account is closed. | | `forbidden (403)` | `accountSuspended` | Subscriptions couldn't be retrieved because the subscriber's account is suspended. | | `forbidden (403)` | `subscriptionForbidden` | The requester isn't allowed to access the requested subscriptions. | | `notFound (404)` | `subscriberNotFound` | The subscriber identified with the request cannot be found. | ## thumbnails The following tables identify error messages that the API returns in response to calls related to `thumbnails` resources. These methods could also return errors listed in the [Common request errors](https://developers.google.com/youtube/v3/docs/errors#youtube.api.CommonRequestError) section. ### `thumbnails.set` | Error type | Error detail | Description | |-------------------------|---------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `invalidImage` | The provided image content is invalid. | | `badRequest (400)` | `mediaBodyRequired` | The request does not include the image content. | | `forbidden (403)` | `forbidden` | The thumbnail can't be set for the specified video. The request might not be properly authorized. | | `forbidden (403)` | `forbidden` | The authenticated user doesn't have permissions to upload and set custom video thumbnails. | | `notFound (404)` | `videoNotFound` | The video that you are trying to insert a thumbnail image for cannot be found. Check the value of the request's `videoId` parameter to ensure that it is correct. | | `tooManyRequests (429)` | `uploadRateLimitExceeded` | The channel has uploaded too many thumbnails recently. Please try the request again later. | ## videoAbuseReportReasons The following tables identify error messages that the API returns in response to calls related to `videoAbuseReportReasons` resources. These methods could also return errors listed in the [Common request errors](https://developers.google.com/youtube/v3/docs/errors#youtube.api.CommonRequestError) section. ### `videoAbuseReportReasons.list` | Error type | Error detail | Description | |-------------------|--------------|---------------------------------------------------------------| | `forbidden (403)` | `forbidden` | Access forbidden. The request may not be properly authorized. | ## videoCategories The following tables identify error messages that the API returns in response to calls related to `videoCategories` resources. These methods could also return errors listed in the [Common request errors](https://developers.google.com/youtube/v3/docs/errors#youtube.api.CommonRequestError) section. ### `videoCategories.list` | Error type | Error detail | Description | |------------------|-------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `notFound (404)` | `videoCategoryNotFound` | The video category identified by the `id` parameter cannot be found. Use the [videoCategories.list](https://developers.google.com/youtube/v3/docs/videoCategories/list) method to retrieve a list of valid values. | ## videos The following tables identify error messages that the API returns in response to calls related to `videos` resources. These methods could also return errors listed in the [Common request errors](https://developers.google.com/youtube/v3/docs/errors#youtube.api.CommonRequestError) section. ### `videos.insert` | Error type | Error detail | Description | |--------------------|---------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `defaultLanguageNotSet` | The request is trying to add localized video details without specifying the default language of the video details. | | `badRequest (400)` | `invalidCategoryId` | The `snippet.categoryId` property specifies an invalid category ID. Use the [videoCategories.list](https://developers.google.com/youtube/v3/docs/videoCategories/list) method to retrieve supported categories. | | `badRequest (400)` | `invalidDescription` | The request metadata specifies an invalid video description. | | `badRequest (400)` | `invalidFilename` | The video filename specified in the `Slug` header is invalid. | | `badRequest (400)` | `invalidPublishAt` | The request metadata specifies an invalid scheduled publishing time. | | `badRequest (400)` | `invalidRecordingDetails` | The `recordingDetails` object in the request metadata specifies invalid recording details. | | `badRequest (400)` | `invalidTags` | The request metadata specifies invalid video keywords. | | `badRequest (400)` | `invalidTitle` | The request metadata specifies an invalid or empty video title. | | `badRequest (400)` | `invalidVideoGameRating` | The request metadata specifies an invalid video game rating. | | `badRequest (400)` | `invalidVideoMetadata` | The request metadata is invalid. This error occurs if the request updates the [snippet](https://developers.google.com/youtube/v3/docs/videos#snippet) part of a `video` resource but does not set a value for both the `snippet.title` and `snippet.categoryId` properties. | | `badRequest (400)` | `mediaBodyRequired` | The request does not include the video content. | | `badRequest (400)` | `uploadLimitExceeded` | The user has exceeded the number of videos they may upload. | | `forbidden (403)` | `forbidden` | | | `forbidden (403)` | `forbiddenLicenseSetting` | The request attempts to set an invalid license for the video. | | `forbidden (403)` | `forbiddenPrivacySetting` | The request attempts to set an invalid privacy setting for the video. | ### `videos.list` | Error type | Error detail | Description | |--------------------|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `videoChartNotFound` | The requested video chart is not supported or is not available. | | `forbidden (403)` | `forbidden` | The request is not properly authorized to access video file or processing information. The `fileDetails`, `processingDetails`, and `suggestions` parts are only available to that video's owner. | | `forbidden (403)` | `forbidden` | The request cannot access user rating information. This error may occur because the request is not properly authorized to use the `myRating` parameter. | | `notFound (404)` | `videoNotFound` | The video that you are trying to retrieve cannot be found. Check the value of the request's `id` parameter to ensure that it is correct. | ### `videos.delete` | Error type | Error detail | Description | |-------------------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------| | `forbidden (403)` | `forbidden` | The video that you are trying to delete cannot be deleted. The request might not be properly authorized. | | `notFound (404)` | `videoNotFound` | The video that you are trying to delete cannot be found. Check the value of the request's `id` parameter to ensure that it is correct. | ### `videos.update` | Error type | Error detail | Description | |--------------------|-----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `defaultLanguageNotSet` | The API request is trying to add localized video details without specifying the default language of the video details. | | `badRequest (400)` | `invalidCategoryId` | The `snippet.categoryId` property specifies an invalid category ID. Use the [videoCategories.list](https://developers.google.com/youtube/v3/docs/videoCategories/list) method to retrieve supported categories. | | `badRequest (400)` | `invalidDefaultBroadcastPrivacySetting` | The request attempts to set an invalid privacy setting for the default broadcast. | | `badRequest (400)` | `invalidDescription` | The request metadata specifies an invalid video description. | | `badRequest (400)` | `invalidPublishAt` | The request metadata specifies an invalid scheduled publishing time. | | `badRequest (400)` | `invalidRecordingDetails` | The `recordingDetails` object in the request metadata specifies invalid recording details. | | `badRequest (400)` | `invalidTags` | The request metadata specifies invalid video keywords. | | `badRequest (400)` | `invalidTitle` | The request metadata specifies an invalid or empty video title. | | `badRequest (400)` | `invalidVideoMetadata` | The request metadata is invalid. This error occurs if the request updates the [snippet](https://developers.google.com/youtube/v3/docs/videos#snippet) part of a `video` resource but does not set a value for both the `snippet.title` and `snippet.categoryId` properties. | | `forbidden (403)` | `forbidden` | Access forbidden. The request may not be properly authorized. | | `forbidden (403)` | `forbiddenEmbedSetting` | The request attempts to set an invalid embed setting for the video. Some channels might not have permission to offer embedded players for live streams. See the [YouTube Help Center](https://support.google.com/youtube/answer/2474026) for more information. | | `forbidden (403)` | `forbiddenLicenseSetting` | The request attempts to set an invalid license for the video. | | `forbidden (403)` | `forbiddenPrivacySetting` | The request attempts to set an invalid privacy setting for the video. | | `notFound (404)` | `videoNotFound` | The video that you are trying to update cannot be found. Check the value of the `id` field in the request body to ensure that it is correct. | ### `videos.rate` | Error type | Error detail | Description | |--------------------|-------------------------|--------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `emailNotVerified` | The user must verify their email address prior to rating. | | `badRequest (400)` | `invalidRating` | The request contained an unexpected value for the `rating` parameter. | | `badRequest (400)` | `videoPurchaseRequired` | Rental videos can only be rated by users who rented them. | | `forbidden (403)` | `forbidden` | The video that you are trying to rate cannot be rated. The request might not be properly authorized. | | `forbidden (403)` | `videoRatingDisabled` | The owner of the video that you are trying to rate has disabled ratings for that video. | | `notFound (404)` | `videoNotFound` | The video that you are trying to rate cannot be found. Check the value of the request's `id` parameter to ensure that it is correct. | ### `videos.reportAbuse` | Error type | Error detail | Description | |--------------------|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `invalidAbuseReason` | The request contained an unexpected value for the `reason_id` field, or a combination of the `reason_id` and `secondary_reason_id` fields. | | `badRequest (400)` | `rateLimitExceeded` | The user has sent too many requests in a given timeframe. | | `forbidden (403)` | `forbidden` | | | `notFound (404)` | `videoNotFound` | The video that you are trying to report abuse for cannot be found. | ## watermarks The following tables identify error messages that the API returns in response to calls related to `watermarks` resources. These methods could also return errors listed in the [Common request errors](https://developers.google.com/youtube/v3/docs/errors#youtube.api.CommonRequestError) section. ### `watermarks.set` | Error type | Error detail | Description | |--------------------|--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `imageFormatUnsupported` | The image you provided is in an unsupported format. | | `badRequest (400)` | `imageTooTall` | The image you provided is too tall. | | `badRequest (400)` | `imageTooWide` | The image you provided is too wide. | | `badRequest (400)` | `mediaBodyRequired` | The request does not include the image content. | | `forbidden (403)` | `forbidden` | The watermark can't be set for the specified channel. The request may not be properly authorized, or the `channelId` parameter is set to an invalid value. | ### `watermarks.unset` | Error type | Error detail | Description | |-------------------|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| | `forbidden (403)` | `forbidden` | The watermark can't be unset for the specified channel. The request may not be properly authorized, or the `channelId` parameter is set to an invalid value. | --- # Source: https://developers.google.com/youtube/v3/docs/guideCategories.md.txt # GuideCategories **Note:** This is a deprecation announcement. The `guideCategories` resource and the `guideCategories.list` method have both been deprecated as of September 9, 2020. 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](https://developers.google.com/youtube/v3/docs/videoCategories), with the difference being that a video's uploader can assign a video category but only YouTube can assign a channel category. ## Methods The API supports the following methods for `guideCategories` resources: [list](https://developers.google.com/youtube/v3/docs/guideCategories/list) : Returns a list of categories that can be associated with YouTube channels. [Try it now](https://developers.google.com/youtube/v3/docs/guideCategories/list#try-it). ## Resource representation The JSON structure below shows the format of a `guideCategories` resource: ```text { "kind": "youtube#guideCategory", "etag": etag, "id": string, "snippet": { "channelId": "UCBR8-60-B28hp2BmDPdntcQ", "title": 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#guideCategory`. | | `etag` | `etag` The Etag of this resource. | | `id` | `string` The ID that YouTube uses to uniquely identify the guide category. | | `snippet` | `object` The `snippet` object contains basic details about the category, such as its title. | | snippet.`channelId` | `string` The ID that YouTube uses to uniquely identify the channel publishing the guide category. | | snippet.`title` | `string` The category's title. | --- # Source: https://developers.google.com/youtube/v3/docs/guideCategories/list.md.txt # GuideCategories: list **Note:** This is a deprecation announcement. The `guideCategories` resource and the `guideCategories.list` method have both been deprecated as of September 9, 2020. Returns a list of categories that can be associated with YouTube channels. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 1 unit. ## Request ### HTTP request ``` GET https://www.googleapis.com/youtube/v3/guideCategories ``` ### Parameters The table below lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters || |--------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---| | **Required parameters** ||| | `part` | `string` The **part** parameter specifies the `guideCategory` resource properties that the API response will include. Set the parameter value to `snippet`. | | **Filters (specify exactly one of the following parameters)** ||| | `id` | `string` The **id** parameter specifies a comma-separated list of the YouTube channel category ID(s) for the resource(s) that are being retrieved. In a `guideCategory` resource, the `id` property specifies the YouTube channel category ID. | | `regionCode` | `string` The **regionCode** parameter instructs the API to return the list of guide categories available in the specified country. The parameter value is an [ISO 3166-1 alpha-2](http://www.iso.org/iso/country_codes/iso_3166_code_lists/country_names_and_code_elements.htm) country code. | | **Optional parameters** ||| | `hl` | `string` The **hl** parameter specifies the language that will be used for text values in the API response. The default value is `en-US`. | ### Request body Do not provide a request body when calling this method. ## Response If successful, this method returns a response body with the following structure: ```objective-c { "kind": "youtube#guideCategoryListResponse", "etag": etag, "nextPageToken": string, "prevPageToken": string, "pageInfo": { "totalResults": integer, "resultsPerPage": integer }, "items": [ guideCategory resource ] } ``` ### 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#guideCategoryListResponse`. | | `etag` | `etag` The Etag of this resource. | | `nextPageToken` | `string` The token that can be used as the value of the `pageToken` parameter to retrieve the next page in the result set. | | `prevPageToken` | `string` The token that can be used as the value of the `pageToken` parameter to retrieve the previous page in the result set. | | `pageInfo` | `object` The `pageInfo` object encapsulates paging information for the result set. | | pageInfo.`totalResults` | `integer` The total number of results in the result set. | | pageInfo.`resultsPerPage` | `integer` The number of results included in the API response. | | `items[]` | `list` A list of categories that can be associated with YouTube channels. In this map, the category ID is the map key, and its value is the corresponding `guideCategory` resource. | ## Errors The table below identifies error messages that the API could return in response to a call to this method. Please see the [error message](https://developers.google.com/youtube/v3/docs/errors) documentation for more detail. | Error type | Error detail | Description | |------------------|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `notFound (404)` | `notFound` | The guide category identified by the `id` parameter cannot be found. Use the [guideCategories.list](https://developers.google.com/youtube/v3/docs/guideCategories/list) method to retrieve a list of valid values. | ## Try it! Use the APIs Explorer to call this API and see the API request and response. --- # Source: https://developers.google.com/youtube/v3/docs/i18nLanguages.md.txt # I18nLanguages An **i18nLanguage** resource identifies an application language that the YouTube website supports. The application language can also be referred to as a UI language. For the YouTube website, an application language could be automatically selected based on Google Account settings, browser language, or IP location. A user could also manually select the desired UI language from the YouTube site footer. Each `i18nLanguage` resource identifies a language code and a name. The language code can be used as the value of the `hl` parameter when calling API methods like `videoCategories.list` and `guideCategories.list`. ## Methods The API supports the following methods for `i18nLanguages` resources: [list](https://developers.google.com/youtube/v3/docs/i18nLanguages/list) : Returns a list of application languages that the YouTube website supports. [Try it now](https://developers.google.com/youtube/v3/docs/i18nLanguages/list#usage). ## Resource representation The following JSON structure shows the format of a `i18nLanguages` resource: ```text { "kind": "youtube#i18nLanguage", "etag": etag, "id": string, "snippet": { "hl": string, "name": 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#i18nLanguage`. | | `etag` | `etag` The Etag of this resource. | | `id` | `string` The ID that YouTube uses to uniquely identify the i18n language. | | `snippet` | `object` The `snippet` object contains basic details about the i18n language, such as its language code and name. | | snippet.`hl` | `string` A BCP-47 code that uniquely identifies a language. | | snippet.`name` | `string` The name of the language as it is written in the language specified using the `i18nLanguage.list` method's [hl](https://developers.google.com/youtube/v3/docs/i18nLanguages/list#hl) parameter. | --- # Source: https://developers.google.com/youtube/v3/docs/i18nLanguages/list.md.txt # I18nLanguages: list Returns a list of application languages that the YouTube website supports. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 1 unit. ## Common use cases The list below shows common use cases for this method. Hover over a use case to see its description, or click on a use case to load sample parameter values in the APIs Explorer. You can open the [fullscreen APIs Explorer](https://developers.google.com/youtube/v3/docs/i18nLanguages/list#) to see code samples that dynamically update to reflect the parameter values entered in the Explorer. The table below shows common use cases for this method. You can click on a use case name to load sample parameter values in the APIs Explorer. Or you can see code samples for a use case in the fullscreen APIs Explorer by clicking on the code icon below a use case name. In the fullscreen UI, you can update parameter and property values and the code samples will dynamically update to reflect the values you enter. This method has one common use case, which is described below. The buttons below the description populate the APIs Explorer with sample values or open the fullscreen APIs Explorer to show code samples that use those values. The code samples also dynamically update if you change the values.
## Request ### HTTP request ``` GET https://www.googleapis.com/youtube/v3/i18nLanguages ``` ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters || |--------|------------------------------------------------------------------------------------------------------------------------------------------------------------|---| | **Required parameters** ||| | `part` | `string` The **part** parameter specifies the `i18nLanguage` resource properties that the API response will include. Set the parameter value to `snippet`. | | **Optional parameters** ||| | `hl` | `string` The **hl** parameter specifies the language that should be used for text values in the API response. The default value is `en_US`. | ### Request body Do not provide a request body when calling this method. ## Response If successful, this method returns a response body with the following structure: ```objective-c { "kind": "youtube#i18nLanguageListResponse", "etag": etag, "items": [ i18nLanguage resource ] } ``` ### 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#i18nLanguageListResponse`. | | `etag` | `etag` The Etag of this resource. | | `items[]` | `list` A list of supported i18n languages. In this map, the i18n language ID is the map key, and its value is the corresponding `i18nLanguage` resource. | ## Errors The API does not define any error messages that are unique to this API method. However, this method could still return general API errors listed in the [error message](https://developers.google.com/youtube/v3/docs/errors#general) documentation. ## Try it! Use the APIs Explorer to call this API and see the API request and response. --- # Source: https://developers.google.com/youtube/v3/docs/i18nRegions.md.txt # I18nRegions An **i18nRegion** resource identifies a geographic area that a YouTube user can select as the preferred content region. The content region can also be referred to as a content locale. For the YouTube website, a content region could be automatically selected based on heuristics like the YouTube domain or the user's IP location. A user could also manually select the desired content region from the YouTube site footer. Each `i18nRegion` resource identifies a region code and a name. The region code can be used as the value of the `regionCode` parameter when calling API methods like `search.list`, `videos.list`, `activities.list`, and `videoCategories.list`. ## Methods The API supports the following methods for `i18nRegions` resources: [list](https://developers.google.com/youtube/v3/docs/i18nRegions/list) : Returns a list of content regions that the YouTube website supports. [Try it now](https://developers.google.com/youtube/v3/docs/i18nRegions/list#usage). ## Resource representation The following JSON structure shows the format of a `i18nRegions` resource: ```text { "kind": "youtube#i18nRegion", "etag": etag, "id": string, "snippet": { "gl": string, "name": 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#i18nRegion`. | | `etag` | `etag` The Etag of this resource. | | `id` | `string` The ID that YouTube uses to uniquely identify the i18n region. | | `snippet` | `object` The `snippet` object contains basic details about the i18n region, such as its region code and name. | | snippet.`gl` | `string` The two-letter ISO country code that identifies the region. | | snippet.`name` | `string` The name of the region. | --- # Source: https://developers.google.com/youtube/v3/docs/i18nRegions/list.md.txt # I18nRegions: list Returns a list of content regions that the YouTube website supports. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 1 unit. ## Common use cases The list below shows common use cases for this method. Hover over a use case to see its description, or click on a use case to load sample parameter values in the APIs Explorer. You can open the [fullscreen APIs Explorer](https://developers.google.com/youtube/v3/docs/i18nRegions/list#) to see code samples that dynamically update to reflect the parameter values entered in the Explorer. The table below shows common use cases for this method. You can click on a use case name to load sample parameter values in the APIs Explorer. Or you can see code samples for a use case in the fullscreen APIs Explorer by clicking on the code icon below a use case name. In the fullscreen UI, you can update parameter and property values and the code samples will dynamically update to reflect the values you enter. This method has one common use case, which is described below. The buttons below the description populate the APIs Explorer with sample values or open the fullscreen APIs Explorer to show code samples that use those values. The code samples also dynamically update if you change the values.
## Request ### HTTP request ``` GET https://www.googleapis.com/youtube/v3/i18nRegions ``` ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters || |--------|----------------------------------------------------------------------------------------------------------------------------------------------------------|---| | **Required parameters** ||| | `part` | `string` The **part** parameter specifies the `i18nRegion` resource properties that the API response will include. Set the parameter value to `snippet`. | | **Optional parameters** ||| | `hl` | `string` The **hl** parameter specifies the language that should be used for text values in the API response. The default value is `en_US`. | ### Request body Do not provide a request body when calling this method. ## Response If successful, this method returns a response body with the following structure: ```objective-c { "kind": "youtube#i18nRegionListResponse", "etag": etag, "items": [ i18nRegion resource ] } ``` ### 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#i18nRegionListResponse`. | | `etag` | `etag` The Etag of this resource. | | `items[]` | `list` A list of regions where YouTube is available. In this map, the i18n region ID is the map key, and its value is the corresponding `i18nRegion` resource. | ## Errors The API does not define any error messages that are unique to this API method. However, this method could still return general API errors listed in the [error message](https://developers.google.com/youtube/v3/docs/errors#general) documentation. ## Try it! Use the APIs Explorer to call this API and see the API request and response. --- # Source: https://developers.google.com/youtube/v3/docs/members.md.txt # Members Note: As of March 31, 2020, the `members` endpoint replaces the `sponsors` endpoint, which is now deprecated and will no longer be supported on or after September 30, 2020. API clients should update calls to the `sponsors.list` method to use the `members.list` method instead. This endpoint can only be used by individual creators to make requests for their own, channel-memberships-enabled YouTube channel. Reach out to your Google or YouTube representative to request access. A **member** resource represents a channel member for a YouTube channel. A member provides recurring monetary support to a creator and receives special benefits. For example, members are able to chat when the creator turns on members-only mode for a chat. ## Methods The API supports the following methods for `member` resources: [list](https://developers.google.com/youtube/v3/docs/members/list) : Lists members (formerly known as "sponsors") for a channel. The API request must be authorized by the channel owner. ## Resource representation The following JSON structure shows the format of a `member` resource: ```text { "kind": "youtube#member", "etag": etag, "snippet": { "creatorChannelId": string, "memberDetails": { "channelId": string, "channelUrl": string, "displayName": string, "profileImageUrl": string }, "membershipsDetails": { "highestAccessibleLevel": string, "highestAccessibleLevelDisplayName": string, "accessibleLevels": [ string ], "membershipsDuration": { "memberSince": datetime, "memberTotalDurationMonths": integer, }, "membershipsDurationAtLevel": [ { "level": string, "memberSince": datetime, "memberTotalDurationMonths": integer, } ] } } } ``` ### 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#member`. | | `etag` | `etag` The Etag of this resource. | | `snippet` | `object` The `snippet` object contains details about the member. | | snippet.`creatorChannelId` | `string` The YouTube channel ID of the creator that offers memberships. | | snippet.`memberDetails` | `object` This object contains profile data about the YouTube channel that is paying for the membership.
Note that a channel can have members with unavailable profile data. For example, this occurs with members who have deleted their channels but are still paying for memberships. Note that these members can still access their membership benefits.
API responses include resources for those members to ensure accurate counts even though the profile details inside the `memberDetails` object are not set. The [membershipsDetails](https://developers.google.com/youtube/v3/docs/members#snippet.membershipsDetails) are still provided for such members. | | snippet.memberDetails.`channelId` | `string` The YouTube channel ID of the member channel. If it is set, the channel ID can also be treated as a unique identifier for the member. If it is not set, the member cannot be uniquely identified, but the resource still conveys membership details such as the levels that the member can access and the duration of their membership. | | snippet.memberDetails.`channelUrl` | `string` The channel's URL. | | snippet.memberDetails.`displayName` | `string` The channel's display name. | | snippet.memberDetails.`profileImageUrl` | `string` The channel's avatar URL. | | snippet.`membershipsDetails` | `object` This object contains membership details for the member channel. | | snippet.membershipsDetails.`highestAccessibleLevel` | `string` The ID of the highest membership level that the member channel can currently access. The value corresponds to the [id](https://developers.google.com/youtube/v3/docs/membershipsLevels#id) property value in a `membershipsLevel` resource. | | snippet.membershipsDetails.`highestAccessibleLevelDisplayName` | `string` The name of the highest membership level that the member channel can currently access. The value corresponds to the [displayName](https://developers.google.com/youtube/v3/docs/membershipsLevels#snippet.levelDetails.displayName) property value in a `membershipsLevel` resource. | | snippet.membershipsDetails.`accessibleLevels[]` | `list (of strings)` A list of IDs for all membership levels that the user can currently access. The list includes the currently active level and all levels below it. | | snippet.`membershipsDuration` | `object` This object contains information about the overall duration of the current member's membership without regard to pricing levels. The [snippet.membershipsDetails.membershipsDurationAtLevel[]](https://developers.google.com/youtube/v3/docs/members#snippet.membershipsDetails.membershipsDurationAtLevel[]) property then contains a list of objects that contain details about a period of the membership during which the member had access to a particular membership level.
The following example shows how these properties work: A member purchases a new membership in January at membership level 1 and has that membership until March. In April and May, the member does not have a membership. In June, the member restarts their membership, again at level 1. Then, in August, the member upgrades their membership to level 2. So, if an API call is made in October, the `member` resource would contain the following: ``` "membershipsDetails": { "membershipsDuration": { "memberSince": "2020-06-01T12:00:00", "memberTotalDurationMonths": 7, }, "membershipsDurationAtLevel": [ { "level": "level_1_ID", "memberSince": "2020-06-01T12:00:00", "memberTotalDurationMonths": 7 }, { "level": "level_2_ID", "memberSince": "2020-08-01T12:00:00", "memberTotalDurationMonths": 2 }, ] } ``` | | snippet.membershipsDuration.`memberSince` | `datetime` The date and time that the member's current membership started. In other words, the member has continuously had a membership since this date and time. Note that different periods of the membership might have been spent at different membership levels. | | snippet.membershipsDuration.`memberTotalDurationMonths` | `integer` The number of months, rounded down to the nearest integer, that the user has been a member. The value reflects the number of complete months that the member has had a membership, but the number does not imply that the member has continuously had a membership for that many months. | | snippet.memberDetails.membershipsDetails.`membershipsDurationAtLevel[]` | `list (of objects)` A list of objects, in which each object contains details about a period of the membership during which the member had access to a particular membership level. The list includes one object for each membership level that the member can currently access. | | snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel.`level` | `string` The membership level ID. The value corresponds to the [id](https://developers.google.com/youtube/v3/docs/membershipsLevels#id) property value in a `membershipsLevel` resource. | | snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel.`memberSince` | `datetime` The date and time from which the member has had access to the specified membership level. In other words, the member has continuously had access to the level since this date and time. Note that different periods of the membership might have been spent at higher membership levels. | | snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel.`memberTotalDurationMonths` | `integer` The number of months, rounded down to the nearest integer, that the user has had access to the specified level. The value reflects the number of complete months that the member has had access to the level, but the number does not imply that the member has continuously had a membership for that many months. | --- # Source: https://developers.google.com/youtube/v3/docs/members/list.md.txt # Members: list Note: This endpoint can only be used by individual creators to make requests for their own, channel-memberships-enabled YouTube channel. Reach out to your Google or YouTube representative to request access. Lists members (formerly known as "sponsors") for a channel. The API request must be authorized by the channel owner. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 2 units. ## Request ### HTTP request ``` GET https://www.googleapis.com/youtube/v3/members ``` ### Authorization This request requires authorization with the following scope: | Scope | |-----------------------------------------------------------------------| | `https://www.googleapis.com/auth/youtube.channel-memberships.creator` | ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters || |---------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---| | **Required parameters** ||| | `part` | `string` The **part** parameter specifies the `member` resource properties that the API response will include. Set the parameter value to `snippet`. | | **Optional parameters** ||| | `mode` | `string` The **mode** parameter indicates which members will be included in the API response. Set the parameter value to one of the following values: - `all_current` (default) - List current members, from newest to oldest. When this value is used, the end of the list is reached when the API response does not contain a [nextPageToken](https://developers.google.com/youtube/v3/docs/members/list#nextPageToken). - `updates` - List only members that joined or upgraded since the previous API call. Note that the first call starts a new stream of updates but does not actually return any members. To start retrieving the membership updates, you need to poll the endpoint using the `nextPageToken` at your desired frequency. Note that when this value is used, the API response always contains a [nextPageToken](https://developers.google.com/youtube/v3/docs/members/list#nextPageToken). | | `maxResults` | `unsigned integer` The **maxResults** parameter specifies the maximum number of items that should be returned in the result set. Acceptable values are `0` to `1000`, inclusive. The default value is `5`. | | `pageToken` | `string` The **pageToken** parameter identifies a specific page in the result set that should be returned. The token is specific to the [mode](https://developers.google.com/youtube/v3/docs/members/list#mode) used with the original API request, so you cannot use a page token retrieved with one mode to subsequently switch to a different mode. | | `hasAccessToLevel` | `string` The **hasAccessToLevel** parameter value is a level ID that specifies the minimum level that members in the result set should have. | | `filterByMemberChannelId` | `string` The **filterByMemberChannelId** parameter specifies a comma-separated list of channel IDs that can be used to check the membership status of specific users. For example, `UC_1,UC_2,UC_3`. A maximum of 100 channels can be specified per call. | ### Request body Do not provide a request body when calling this method. ## Response If successful, this method returns a response body with the following structure: ```objective-c { "https://developers.google.com/youtube/v3/docs/members/list#kind": "youtube#memberListResponse", "https://developers.google.com/youtube/v3/docs/members/list#etag": etag, "https://developers.google.com/youtube/v3/docs/members/list#nextPageToken": string, "https://developers.google.com/youtube/v3/docs/members/list#pageInfo": { "https://developers.google.com/youtube/v3/docs/members/list#totalResults": integer, "https://developers.google.com/youtube/v3/docs/members/list#resultsPerPage": integer }, "https://developers.google.com/youtube/v3/docs/members/list#items": [ member Resource ] } ``` ### 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#memberListResponse`. | | `etag` | `etag` The Etag of this resource. | | `nextPageToken` | `string` The token that can be used as the value of the `pageToken` parameter to retrieve the next page in the result set. Page tokens can expire, and your application should drop the token and call the API without a `pageToken` to start a new request. | | `pageInfo` | `object` The `pageInfo` object encapsulates paging information for the result set. | | pageInfo.`totalResults` | `integer` The total number of results in the result set. | | pageInfo.`resultsPerPage` | `integer` The number of results included in the API response. | | `items[]` | `list` A list of members that match the request criteria. | ## Errors The following table identifies error messages that the API could return in response to a call to this method. Please see the [error message](https://developers.google.com/youtube/v3/docs/errors) documentation for more detail. | Error type | Error detail | Description | |--------------------|----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `badRequest (400)` | `channelMembershipsNotEnabled` | The creator channel authorizing the request does not have channel memberships enabled. | | `badRequest (400)` | `invalidMode` | The [mode](https://developers.google.com/youtube/v3/docs/members/list#mode) parameter value is invalid. This error might occur if the [pageToken](https://developers.google.com/youtube/v3/docs/members/list#pageToken) parameter specifies a token that was retrieved using a different mode than the one specified. | | `badRequest (400)` | `invalidPageToken` | The [pageToken](https://developers.google.com/youtube/v3/docs/members/list#pageToken) parameter value is invalid. This error can occur if the page token used in the request has expired or is not recognized. | | `badRequest (400)` | `invalidHasAccessToLevel` | The [hasAccessToLevel](https://developers.google.com/youtube/v3/docs/members/list#hasAccessToLevel) parameter value is invalid. There is no level with the specified [id](https://developers.google.com/youtube/v3/docs/membershipsLevels#id). | | `badRequest (400)` | `invalidFilterByMemberChannelId` | The [filterByMemberChannelId](https://developers.google.com/youtube/v3/docs/members/list#filterByMemberChannelId) parameter value is invalid. This error occurs if the [filterByMemberChannelId](https://developers.google.com/youtube/v3/docs/members/list#filterByMemberChannelId) parameter value specifies more than 100 channels. | --- # Source: https://developers.google.com/youtube/v3/docs/membershipsLevels.md.txt # MembershipsLevels Note: This endpoint can only be used by individual creators to make requests for their own, channel-memberships-enabled YouTube channel. Reach out to your Google or YouTube representative to request access. A **membershipsLevel** resource identifies a pricing level managed by the creator that authorized the API request. ## Methods The API supports the following methods for `membershipsLevel` resources: [list](https://developers.google.com/youtube/v3/docs/membershipsLevels/list) : Lists membership levels for the channel that authorized the request. ## Resource representation The following JSON structure shows the format of a `membershipsLevel` resource: ```text { "kind": "youtube#membershipsLevel", "etag": etag, "id": string, "snippet": { "creatorChannelId": string, "levelDetails": { "displayName": 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#membershipsLevel`. | | `etag` | `etag` The Etag of this resource. | | `id` | `string` The ID that YouTube assigns to uniquely identify the membership level. This value will not change even if the level's display name changes. | | `snippet` | `object` The `snippet` object contains details about the membership level. | | snippet.`creatorChannelId` | `string` The YouTube channel ID of the creator that owns the pricing level. | | snippet.`levelDetails` | `object` This object contains data about the membership level. | | snippet.levelDetails.`displayName` | `string` The level's display name. | --- # Source: https://developers.google.com/youtube/v3/docs/membershipsLevels/list.md.txt # MembershipsLevels: list Note: This endpoint can only be used by individual creators to make requests for their own, channel-memberships-enabled YouTube channel. Reach out to your Google or YouTube representative to request access. Lists membership levels for the channel that authorized the request. Levels are returned in implicit display order. API requests to this method yield one of the following responses: - If the creator has enabled channel memberships and has pricing levels, then the API response contains the list of levels. - If the creator has enabled channel memberships but has not defined pricing levels, then the API response contains an empty list. - If the creator has not enabled channel memberships, the API returns a [channelMembershipsNotEnabled](https://developers.google.com/youtube/v3/docs/membershipsLevels/list#errors) error. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 1 unit. ## Request ### HTTP request ``` GET https://www.googleapis.com/youtube/v3/membershipsLevels ``` This request requires authorization with the following scope: | Scope | |-----------------------------------------------------------------------| | `https://www.googleapis.com/auth/youtube.channel-memberships.creator` | ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters || |--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---| | **Required parameters** ||| | `part` | `string` The **part** parameter specifies the `membershipsLevel` resource properties that the API response will include. The parameter value is a comma-separated list of resource parts. The following list shows the parts that can be retrieved: - `id` - `snippet` | ### Request body Do not provide a request body when calling this method. ## Response If successful, this method returns a response body with the following structure: ```objective-c { "kind": "youtube#membershipsLevelListResponse", "etag": etag, "items": [ membershipsLevel Resource ] } ``` ### 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#membershipsLevelListResponse`. | | `etag` | `etag` The Etag of this resource. | | `items[]` | `list` A list of `membershipsLevel` resources owned by the channel that authorized the API request. | ## Errors The following table identifies error messages that the API could return in response to a call to this method. Please see the [error message](https://developers.google.com/youtube/v3/docs/errors) documentation for more detail. | Error type | Error detail | Description | |--------------------|--------------------------------|----------------------------------------------------------------------------------------| | `badRequest (400)` | `channelMembershipsNotEnabled` | The creator channel authorizing the request does not have channel memberships enabled. | --- # Source: https://developers.google.com/youtube/v3/docs/playlistImages.md.txt # PlaylistImages A **playlistImage** resource identifies the thumbnail image associated with a playlist. ## Methods The API supports the following methods for `playlistImages` resources: [list](https://developers.google.com/youtube/v3/docs/playlistImages/list) : Returns a collection of playlist images that match the API request parameters. [Try it now](https://developers.google.com/youtube/v3/docs/playlistImages/list#usage). [insert](https://developers.google.com/youtube/v3/docs/playlistImages/insert) : Adds a thumbail image to a playlist. [Try it now](https://developers.google.com/youtube/v3/docs/playlistImages/insert#usage). [update](https://developers.google.com/youtube/v3/docs/playlistImages/update) : Updates the thumbnail image for an existing playlist. [Try it now](https://developers.google.com/youtube/v3/docs/playlistImages/update#usage). [delete](https://developers.google.com/youtube/v3/docs/playlistImages/delete) : Deletes a playlist thumbnail image. [Try it now](https://developers.google.com/youtube/v3/docs/playlistImages/delete#usage). ## Resource representation The following JSON structure shows the format of a `playlistImages` resource: ```carbon { "https://developers.google.com/youtube/v3/docs/playlistImages#kind": "youtube#playlistImage", "https://developers.google.com/youtube/v3/docs/playlistImages#id": string, "https://developers.google.com/youtube/v3/docs/playlistImages#snippet": { "https://developers.google.com/youtube/v3/docs/playlistImages#snippet.playlistId": string, "https://developers.google.com/youtube/v3/docs/playlistImages#snippet.type": string, "https://developers.google.com/youtube/v3/docs/playlistImages#snippet.width": string, "https://developers.google.com/youtube/v3/docs/playlistImages#snippet.height": 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#playlistImage`. | | `id` | `string` The ID that YouTube uses to uniquely identify the playlist image. | | `snippet` | `object` The `snippet` object contains basic details about the playlist image, such as its type and dimensions. | | snippet.`playlistId` | `string` The playlist ID of the playlist this image is associated with. | | snippet.`type` | `string` The image type. | | snippet.`width` | `string` The image's width. | | snippet.`height` | `string` The images's height. | --- # Source: https://developers.google.com/youtube/v3/docs/playlistImages/delete.md.txt # PlaylistImages: delete Deletes a playlist image. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 50 units. ## Request ### HTTP request ``` DELETE https://www.googleapis.com/youtube/v3/playlistImages ``` ### Authorization This request requires authorization with at least one of the following scopes ([read more about authentication and authorization](https://developers.google.com/youtube/v3/guides/authentication)). | Scope | |-----------------------------------------------------| | `https://www.googleapis.com/auth/youtubepartner` | | `https://www.googleapis.com/auth/youtube` | | `https://www.googleapis.com/auth/youtube.force-ssl` | ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters || |--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---| | **Required parameters** ||| | `id` | `string` The **id** parameter specifies the YouTube playlist image ID for the playlist image that is being deleted. In a `playlistImages` resource, the `id` property specifies the playlist image's ID. | | **Optional parameters** ||| | `onBehalfOfContentOwner` | `string` **Note:** The **onBehalfOfContentOwner** parameter is intended exclusively for YouTube content partners and can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication). This parameter is designed for YouTube content partners that own and manage many different YouTube channels. It enables users affiliated with the content owner to authenticate once and then be able to access and manage all of the content owner's video and channel data, without having to provide authentication credentials for each individual channel. When the parameter is present, its value identifies a content owner, and the request's authorization credentials identify a YouTube user who is authorized to act on behalf of that content owner. The account that the user authenticates with must be [linked to the specified content owner](https://support.google.com/youtube/answer/4524878) in the YouTube Creator Studio settings. | ### Request body Do not provide a request body when calling this method. ## Response If successful, this method returns an HTTP `204` response code (`No Content`). --- # Source: https://developers.google.com/youtube/v3/docs/playlistImages/insert.md.txt # PlaylistImages: insert Adds an image to a playlist. This method supports media upload. Uploaded files must conform to these constraints: - **Maximum file size:** 2MB - **Accepted aspect ratio:** 1:1 (square) - **Accepted Media MIME types:** `image/jpeg`, `image/png` **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 50 units. ## Request ### HTTP request ``` POST https://www.googleapis.com/youtube/v3/playlistImages ``` ### Authorization This request requires authorization with at least one of the following scopes ([read more about authentication and authorization](https://developers.google.com/youtube/v3/guides/authentication)). | Scope | |-----------------------------------------------------| | `https://www.googleapis.com/auth/youtubepartner` | | `https://www.googleapis.com/auth/youtube` | | `https://www.googleapis.com/auth/youtube.force-ssl` | ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters || |---------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---| | **Required parameters** ||| | `part` | `string` The **part** parameter specifies a comma-separated list of one or more `playlistImage` resource properties that the API response will include. If the parameter identifies a property that contains child properties, the child properties will be included in the response. | | **Optional parameters** ||| | `onBehalfOfContentOwner` | `string` This parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication). **Note:** This parameter is intended exclusively for YouTube content partners. The **onBehalfOfContentOwner** parameter indicates that the request's authorization credentials identify a YouTube CMS user who is acting on behalf of the content owner specified in the parameter value. This parameter is intended for YouTube content partners that own and manage many different YouTube channels. It allows content owners to authenticate once and get access to all their video and channel data, without having to provide authentication credentials for each individual channel. The CMS account that the user authenticates with must be linked to the specified YouTube content owner. | | `onBehalfOfContentOwnerChannel` | `string` This parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication). **Note:** This parameter is intended exclusively for YouTube content partners.
The **onBehalfOfContentOwnerChannel** parameter specifies the YouTube channel ID of the channel to which a video is being added. This parameter is required when a request specifies a value for the `onBehalfOfContentOwner` parameter, and it can only be used in conjunction with that parameter. In addition, the request must be authorized using a CMS account that is linked to the content owner that the `onBehalfOfContentOwner` parameter specifies. Finally, the channel that the `onBehalfOfContentOwnerChannel` parameter value specifies must be linked to the content owner that the `onBehalfOfContentOwner` parameter specifies. This parameter is intended for YouTube content partners that own and manage many different YouTube channels. It allows content owners to authenticate once and perform actions on behalf of the channel specified in the parameter value, without having to provide authentication credentials for each separate channel. | ### Request body Provide a [playlistImages resource](https://developers.google.com/youtube/v3/docs/playlistImages#resource) in the request body. For that resource: - You must specify a value for these properties: - `snippet.playlistId` - `snippet.type` - You can set values for these properties: - `snippet.width` - `snippet.height` ## Response If successful, this method returns a [playlistImages resource](https://developers.google.com/youtube/v3/docs/playlistImages#resource) in the response body. --- # Source: https://developers.google.com/youtube/v3/docs/playlistImages/list.md.txt # PlaylistImages: list Returns a collection of playlist images that match the API request parameters. You can retrieve the playlist image of a specified playlist or retrieve one or more playlist images by their unique IDs. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 1 unit. ## Request ### HTTP request ``` GET https://www.googleapis.com/youtube/v3/playlistImages ``` ### Authorization This request requires authorization with at least one of the following scopes ([read more about authentication and authorization](https://developers.google.com/youtube/v3/guides/authentication)). | Scope | |-----------------------------------------------------| | `https://www.googleapis.com/auth/youtubepartner` | | `https://www.googleapis.com/auth/youtube` | | `https://www.googleapis.com/auth/youtube.force-ssl` | ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters || |---------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---| | **Required parameters** ||| | `part` | `string` The **part** parameter specifies a comma-separated list of one or more `playlistImage` resource properties that the API response will include. If the parameter identifies a property that contains child properties, the child properties will be included in the response. | | **Filters (specify exactly one of the following parameters)** ||| | `id` | `string` The **id** parameter specifies a comma-separated list of one or more unique playlist image IDs. | | `playlistId` | `string` The **playlistId** parameter specifies the unique ID of the playlist for which you want to retrieve playlist images. Note that even though this is an optional parameter, every request to retrieve playlist images must specify a value for either the `id` parameter or the `playlistId` parameter. | | **Optional parameters** ||| | `maxResults` | `unsigned integer` The **maxResults** parameter specifies the maximum number of images that should be returned in the result set. Acceptable values are `0` to `50`, inclusive. The default value is `5`. | | `onBehalfOfContentOwner` | `string` This parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication). **Note:** This parameter is intended exclusively for YouTube content partners. The **onBehalfOfContentOwner** parameter indicates that the request's authorization credentials identify a YouTube CMS user who is acting on behalf of the content owner specified in the parameter value. This parameter is intended for YouTube content partners that own and manage many different YouTube channels. It allows content owners to authenticate once and get access to all their video and channel data, without having to provide authentication credentials for each individual channel. The CMS account that the user authenticates with must be linked to the specified YouTube content owner. | | `onBehalfOfContentOwnerChannel` | `string` This parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication). **Note:** This parameter is intended exclusively for YouTube content partners.
The **onBehalfOfContentOwnerChannel** parameter specifies the YouTube channel ID of the channel to which a video is being added. This parameter is required when a request specifies a value for the `onBehalfOfContentOwner` parameter, and it can only be used in conjunction with that parameter. In addition, the request must be authorized using a CMS account that is linked to the content owner that the `onBehalfOfContentOwner` parameter specifies. Finally, the channel that the `onBehalfOfContentOwnerChannel` parameter value specifies must be linked to the content owner that the `onBehalfOfContentOwner` parameter specifies. This parameter is intended for YouTube content partners that own and manage many different YouTube channels. It allows content owners to authenticate once and perform actions on behalf of the channel specified in the parameter value, without having to provide authentication credentials for each separate channel. | | `pageToken` | `string` The **pageToken** parameter identifies a specific page in the result set that should be returned. In an API response, the `nextPageToken` and `prevPageToken` properties identify other pages that could be retrieved. | ### Request body Do not provide a request body when calling this method. ## Response If successful, this method returns a response body with the following structure: ```objective-c { "kind": "youtube#playlistImageListResponse", "nextPageToken": string, "prevPageToken": string, "pageInfo": { "totalResults": integer, "resultsPerPage": integer }, "items": [ playlistImages Resource ] } ``` ### 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#playlistImageListResponse`. | | `nextPageToken` | `string` The token that can be used as the value of the `pageToken` parameter to retrieve the next page in the result set. | | `prevPageToken` | `string` The token that can be used as the value of the `pageToken` parameter to retrieve the previous page in the result set. | | `pageInfo` | `object` The `pageInfo` object encapsulates paging information for the result set. | | pageInfo.`totalResults` | `integer` The total number of results in the result set. | | pageInfo.`resultsPerPage` | `integer` The number of results included in the API response. | | `items[]` | `list` A list of playlist images that match the request criteria. | --- # Source: https://developers.google.com/youtube/v3/docs/playlistImages/update.md.txt # PlaylistImages: update Modifies a playlist image. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 50 units. ## Request ### HTTP request ``` PUT https://www.googleapis.com/youtube/v3/playlistImages ``` ### Authorization This request requires authorization with at least one of the following scopes ([read more about authentication and authorization](https://developers.google.com/youtube/v3/guides/authentication)). | Scope | |-----------------------------------------------------| | `https://www.googleapis.com/auth/youtubepartner` | | `https://www.googleapis.com/auth/youtube` | | `https://www.googleapis.com/auth/youtube.force-ssl` | ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters || |--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---| | **Required parameters** ||| | `part` | `string` The **part** parameter specifies a comma-separated list of one or more `playlistImage` resource properties that the API response will include. If the parameter identifies a property that contains child properties, the child properties will be included in the response. | | **Optional parameters** ||| | `onBehalfOfContentOwner` | `string` **Note:** The **onBehalfOfContentOwner** parameter is intended exclusively for YouTube content partners and can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication). This parameter is designed for YouTube content partners that own and manage many different YouTube channels. It enables users affiliated with the content owner to authenticate once and then be able to access and manage all of the content owner's video and channel data, without having to provide authentication credentials for each individual channel. When the parameter is present, its value identifies a content owner, and the request's authorization credentials identify a YouTube user who is authorized to act on behalf of that content owner. The account that the user authenticates with must be [linked to the specified content owner](https://support.google.com/youtube/answer/4524878) in the YouTube Creator Studio settings. | ### Request body Provide a [playlistImages resource](https://developers.google.com/youtube/v3/docs/playlistImages#resource) in the request body. For that resource: - You must specify a value for these properties: - `snippet.playlistId` - `snippet.type` - You can set values for these properties: - `snippet.width` - `snippet.height` ## Response If successful, this method returns a [playlistItem resource](https://developers.google.com/youtube/v3/docs/playlistImages#resource) in the response body. --- # 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. | --- # Source: https://developers.google.com/youtube/v3/docs/playlistItems/delete.md.txt # PlaylistItems: delete Deletes a playlist item. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 50 units. ## Common use cases The list below shows common use cases for this method. Hover over a use case to see its description, or click on a use case to load sample parameter values in the APIs Explorer. You can open the [fullscreen APIs Explorer](https://developers.google.com/youtube/v3/docs/playlistItems/delete#) to see code samples that dynamically update to reflect the parameter values entered in the Explorer. The table below shows common use cases for this method. You can click on a use case name to load sample parameter values in the APIs Explorer. Or you can see code samples for a use case in the fullscreen APIs Explorer by clicking on the code icon below a use case name. In the fullscreen UI, you can update parameter and property values and the code samples will dynamically update to reflect the values you enter. This method has one common use case, which is described below. The buttons below the description populate the APIs Explorer with sample values or open the fullscreen APIs Explorer to show code samples that use those values. The code samples also dynamically update if you change the values.
## Request ### HTTP request ``` DELETE https://www.googleapis.com/youtube/v3/playlistItems ``` ### Authorization This request requires authorization with at least one of the following scopes. To read more about authentication and authorization, see [Implementing OAuth 2.0 authorization](https://developers.google.com/youtube/v3/guides/authentication). | Scope | |-----------------------------------------------------| | `https://www.googleapis.com/auth/youtubepartner` | | `https://www.googleapis.com/auth/youtube` | | `https://www.googleapis.com/auth/youtube.force-ssl` | ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters || |--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---| | **Required parameters** ||| | `id` | `string` The **id** parameter specifies the YouTube playlist item ID for the playlist item that is being deleted. In a `playlistItem` resource, the `id` property specifies the playlist item's ID. | | **Optional parameters** ||| | `onBehalfOfContentOwner` | `string` **Note:** The **onBehalfOfContentOwner** parameter is intended exclusively for YouTube content partners and can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication). This parameter is designed for YouTube content partners that own and manage many different YouTube channels. It enables users affiliated with the content owner to authenticate once and then be able to access and manage all of the content owner's video and channel data, without having to provide authentication credentials for each individual channel. When the parameter is present, its value identifies a content owner, and the request's authorization credentials identify a YouTube user who is authorized to act on behalf of that content owner. The account that the user authenticates with must be [linked to the specified content owner](https://support.google.com/youtube/answer/4524878) in the YouTube Creator Studio settings. | ### Request body Do not provide a request body when calling this method. ## Response If successful, this method returns an HTTP `204 No Content` status code. ## Errors The following table identifies error messages that the API could return in response to a call to this method. For more details, see [YouTube Data API - Errors](https://developers.google.com/youtube/v3/docs/errors). | Error type | Error detail | Description | |----------------------|--------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| | `forbidden (403)` | `playlistItemsNotAccessible` | The request is not properly authorized to delete the specified playlist item. | | `notFound (404)` | `playlistItemNotFound` | The playlist item identified with the request's `id` parameter cannot be found. | | `invalidValue (400)` | `playlistOperationUnsupported` | The API does not support the ability to delete videos from the specified playlist. For example, you can't delete a video from your uploaded videos playlist. | ## Try it! Use the APIs Explorer to call this API and see the API request and response. --- # Source: https://developers.google.com/youtube/v3/docs/playlistItems/insert.md.txt # PlaylistItems: insert Adds a resource to a playlist. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 50 units. ## Common use cases The list below shows common use cases for this method. Hover over a use case to see its description, or click on a use case to load sample parameter values in the APIs Explorer. You can open the [fullscreen APIs Explorer](https://developers.google.com/youtube/v3/docs/playlistItems/insert#) to see code samples that dynamically update to reflect the parameter values entered in the Explorer. The table below shows common use cases for this method. You can click on a use case name to load sample parameter values in the APIs Explorer. Or you can see code samples for a use case in the fullscreen APIs Explorer by clicking on the code icon below a use case name. In the fullscreen UI, you can update parameter and property values and the code samples will dynamically update to reflect the values you enter. This method has one common use case, which is described below. The buttons below the description populate the APIs Explorer with sample values or open the fullscreen APIs Explorer to show code samples that use those values. The code samples also dynamically update if you change the values.
## Request ### HTTP request ``` POST https://www.googleapis.com/youtube/v3/playlistItems ``` ### Authorization This request requires authorization with at least one of the following scopes ([read more about authentication and authorization](https://developers.google.com/youtube/v3/guides/authentication)). | Scope | |-----------------------------------------------------| | `https://www.googleapis.com/auth/youtubepartner` | | `https://www.googleapis.com/auth/youtube` | | `https://www.googleapis.com/auth/youtube.force-ssl` | ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters || |--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---| | **Required parameters** ||| | `part` | `string` The **part** parameter serves two purposes in this operation. It identifies the properties that the write operation will set as well as the properties that the API response will include. The following list contains the `part` names that you can include in the parameter value: - `contentDetails` - `id` - `snippet` - `status` | | **Optional parameters** ||| | `onBehalfOfContentOwner` | `string` This parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication). **Note:** This parameter is intended exclusively for YouTube content partners. The **onBehalfOfContentOwner** parameter indicates that the request's authorization credentials identify a YouTube CMS user who is acting on behalf of the content owner specified in the parameter value. This parameter is intended for YouTube content partners that own and manage many different YouTube channels. It allows content owners to authenticate once and get access to all their video and channel data, without having to provide authentication credentials for each individual channel. The CMS account that the user authenticates with must be linked to the specified YouTube content owner. | ### Request body Provide a [playlistItem resource](https://developers.google.com/youtube/v3/docs/playlistItems#resource) in the request body. For that resource: - You must specify a value for these properties:
- `snippet.playlistId` - `snippet.resourceId`
- You can set values for these properties:
- `snippet.playlistId` - `snippet.position` - `snippet.resourceId` - `contentDetails.note` - `contentDetails.startAt` - `contentDetails.endAt`
## Response If successful, this method returns a [playlistItem resource](https://developers.google.com/youtube/v3/docs/playlistItems#resource) in the response body. ## Errors The following table identifies error messages that the API could return in response to a call to this method. Please see the [error message](https://developers.google.com/youtube/v3/docs/errors) documentation for more detail. | Error type | Error detail | Description | |----------------------|-----------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `forbidden (403)` | `playlistContainsMaximumNumberOfVideos` | The playlist already contains the maximum allowed number of items. | | `forbidden (403)` | `playlistItemsNotAccessible` | The request is not properly authorized to insert the specified playlist item. | | `invalidValue (400)` | `invalidContentDetails` | The `contentDetails` property in the request is not valid. A possible reason is that `contentDetails.note` field is longer than 280 characters. | | `invalidValue (400)` | `invalidPlaylistItemPosition` | The request attempts to set the playlist item's position to an invalid or unsupported value. Check the value of the `position` property in the resource's `snippet`. | | `invalidValue (400)` | `invalidResourceType` | The `type` specified for the resource ID is not supported for this operation. The resource ID identifies the item being added to the playlist -- e.g. `youtube#video`. | | `invalidValue (400)` | `manualSortRequired` | The request attempts to set the playlist item's position, but the playlist does not use manual sorting. (For example, playlist items might be sorted by date or popularity.) You can address the error by removing the `snippet.position` element from the resource that the request is inserting. If you want the playlist item to have a particular position in the list, you need to first update the playlist's **Ordering** option to **Manual** in the playlist's settings. This settings can be adjusted in the [YouTube Video Manager](https://www.youtube.com/view_all_playlists). | | `invalidValue (400)` | `videoAlreadyInAnotherSeriesPlaylist` | The video that you are trying to add to the playlist is already in another series playlist. | | `notFound (404)` | `playlistNotFound` | The playlist identified with the request's `playlistId` parameter cannot be found. | | `notFound (404)` | `videoNotFound` | The video that you are trying to add to the playlist cannot be found. Check the value of the `videoId` property to ensure that it is correct. | | `required (400)` | `channelIdRequired` | The request does not specify a value for the required `channelId` property. | | `required (400)` | `playlistIdRequired` | The request does not specify a value for the required `playlistId` property. | | `required (400)` | `resourceIdRequired` | The request must contain a resource in which the `snippet` object specifies a `resourceId`. | | `invalidValue (400)` | `playlistOperationUnsupported` | The API does not support the ability to insert videos into the specified playlist. For example, you can't insert a video into your uploaded videos playlist. | ## Try it! Use the APIs Explorer to call this API and see the API request and response. --- # Source: https://developers.google.com/youtube/v3/docs/playlistItems/list.md.txt # 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. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 1 unit. ## Common use cases The list below shows common use cases for this method. Hover over a use case to see its description, or click on a use case to load sample parameter values in the APIs Explorer. You can open the [fullscreen APIs Explorer](https://developers.google.com/youtube/v3/docs/playlistItems/list#) to see code samples that dynamically update to reflect the parameter values entered in the Explorer. The table below shows common use cases for this method. You can click on a use case name to load sample parameter values in the APIs Explorer. Or you can see code samples for a use case in the fullscreen APIs Explorer by clicking on the code icon below a use case name. In the fullscreen UI, you can update parameter and property values and the code samples will dynamically update to reflect the values you enter. This method has one common use case, which is described below. The buttons below the description populate the APIs Explorer with sample values or open the fullscreen APIs Explorer to show code samples that use those values. The code samples also dynamically update if you change the values.
## Request ### HTTP request ``` GET https://www.googleapis.com/youtube/v3/playlistItems ``` ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters || |--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---| | **Required parameters** ||| | `part` | `string` The **part** parameter specifies a comma-separated list of one or more `playlistItem` resource properties that the API response will include. If the parameter identifies a property that contains child properties, the child properties will be included in the response. For example, in a `playlistItem` resource, the `snippet` property contains numerous fields, including the `title`, `description`, `position`, and `resourceId` properties. As such, if you set **part=snippet**, the API response will contain all of those properties. The following list contains the `part` names that you can include in the parameter value: - `contentDetails` - `id` - `snippet` - `status` | | **Filters (specify exactly one of the following parameters)** ||| | `id` | `string` The **id** parameter specifies a comma-separated list of one or more unique playlist item IDs. | | `playlistId` | `string` The **playlistId** parameter specifies the unique ID of the playlist for which you want to retrieve playlist items. Note that even though this is an optional parameter, every request to retrieve playlist items must specify a value for either the `id` parameter or the `playlistId` parameter. | | **Optional parameters** ||| | `maxResults` | `unsigned integer` The **maxResults** parameter specifies the maximum number of items that should be returned in the result set. Acceptable values are `0` to `50`, inclusive. The default value is `5`. | | `onBehalfOfContentOwner` | `string` This parameter can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication). **Note:** This parameter is intended exclusively for YouTube content partners. The **onBehalfOfContentOwner** parameter indicates that the request's authorization credentials identify a YouTube CMS user who is acting on behalf of the content owner specified in the parameter value. This parameter is intended for YouTube content partners that own and manage many different YouTube channels. It allows content owners to authenticate once and get access to all their video and channel data, without having to provide authentication credentials for each individual channel. The CMS account that the user authenticates with must be linked to the specified YouTube content owner. | | `pageToken` | `string` The **pageToken** parameter identifies a specific page in the result set that should be returned. In an API response, the `nextPageToken` and `prevPageToken` properties identify other pages that could be retrieved. | | `videoId` | `string` The **videoId** parameter specifies that the request should return only the playlist items that contain the specified video. | ### Request body Do not provide a request body when calling this method. ## Response If successful, this method returns a response body with the following structure: ```objective-c { "kind": "youtube#playlistItemListResponse", "etag": etag, "nextPageToken": string, "prevPageToken": string, "pageInfo": { "totalResults": integer, "resultsPerPage": integer }, "items": [ playlistItem Resource ] } ``` ### 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#playlistItemListResponse`. | | `etag` | `etag` The Etag of this resource. | | `nextPageToken` | `string` The token that can be used as the value of the `pageToken` parameter to retrieve the next page in the result set. | | `prevPageToken` | `string` The token that can be used as the value of the `pageToken` parameter to retrieve the previous page in the result set. | | `pageInfo` | `object` The `pageInfo` object encapsulates paging information for the result set. | | pageInfo.`totalResults` | `integer` The total number of results in the result set. | | pageInfo.`resultsPerPage` | `integer` The number of results included in the API response. | | `items[]` | `list` A list of playlist items that match the request criteria. | ## Examples **Note:** The following code samples may not represent all supported programming languages. See the [client libraries](https://developers.google.com/youtube/v3/libraries) documentation for a list of supported languages. ### Go This code sample calls the API's `playlistItems.list` method to retrieve a list of videos uploaded to the channel associated with the request. The code also calls the `channels.list` method with the `mine` parameter set to `true` to retrieve the playlist ID that identifies the channel's uploaded videos. This example uses the [Go client library](https://github.com/google/google-api-go-client). ```go package main import ( "fmt" "log" "google.golang.org/api/youtube/v3" ) // Retrieve playlistItems in the specified playlist func playlistItemsList(service *youtube.Service, part string, playlistId string, pageToken string) *youtube.PlaylistItemListResponse { call := service.PlaylistItems.List(part) call = call.PlaylistId(playlistId) if pageToken != "" { call = call.PageToken(pageToken) } response, err := call.Do() handleError(err, "") return response } // Retrieve resource for the authenticated user's channel func channelsListMine(service *youtube.Service, part string) *youtube.ChannelListResponse { call := service.Channels.List(part) call = call.Mine(true) response, err := call.Do() handleError(err, "") return response } func main() { client := getClient(youtube.YoutubeReadonlyScope) service, err := youtube.New(client) if err != nil { log.Fatalf("Error creating YouTube client: %v", err) } response := channelsListMine(service, "contentDetails") for _, channel := range response.Items { playlistId := channel.ContentDetails.RelatedPlaylists.Uploads // Print the playlist ID for the list of uploaded videos. fmt.Printf("Videos in list %s\r\n", playlistId) nextPageToken := "" for { // Retrieve next set of items in the playlist. playlistResponse := playlistItemsList(service, "snippet", playlistId, nextPageToken) for _, playlistItem := range playlistResponse.Items { title := playlistItem.Snippet.Title videoId := playlistItem.Snippet.ResourceId.VideoId fmt.Printf("%v, (%v)\r\n", title, videoId) } // Set the token to retrieve the next page of results // or exit the loop if all results have been retrieved. nextPageToken = playlistResponse.NextPageToken if nextPageToken == "" { break } fmt.Println() } } } https://github.com/youtube/api-samples/blob/07263305b59a7c3275bc7e925f9ce6cabf774022/go/my_uploads.go ``` ### .NET The following code sample calls the API's `playlistItems.list` method to retrieve a list of videos uploaded to the channel associated with the request. The code also calls the `channels.list` method with the `mine` parameter set to `true` to retrieve the playlist ID that identifies the channel's uploaded videos. This example uses the [.NET client library](https://developers.google.com/api-client-library/dotnet). ```gdscript using System; using System.IO; using System.Reflection; using System.Threading; using System.Threading.Tasks; using Google.Apis.Auth.OAuth2; using Google.Apis.Services; using Google.Apis.Upload; using Google.Apis.Util.Store; using Google.Apis.YouTube.v3; using Google.Apis.YouTube.v3.Data; namespace Google.Apis.YouTube.Samples { /// /// YouTube Data API v3 sample: retrieve my uploads. /// Relies on the Google APIs Client Library for .NET, v1.7.0 or higher. /// See https://developers.google.com/api-client-library/dotnet/get_started /// internal class MyUploads { [STAThread] static void Main(string[] args) { Console.WriteLine("YouTube Data API: My Uploads"); Console.WriteLine("============================"); try { new MyUploads().Run().Wait(); } catch (AggregateException ex) { foreach (var e in ex.InnerExceptions) { Console.WriteLine("Error: " + e.Message); } } Console.WriteLine("Press any key to continue..."); Console.ReadKey(); } private async Task Run() { UserCredential credential; using (var stream = new FileStream("client_secrets.json", FileMode.Open, FileAccess.Read)) { credential = await GoogleWebAuthorizationBroker.AuthorizeAsync( GoogleClientSecrets.Load(stream).Secrets, // This OAuth 2.0 access scope allows for read-only access to the authenticated // user's account, but not other types of account access. new[] { YouTubeService.Scope.YoutubeReadonly }, "user", CancellationToken.None, new FileDataStore(this.GetType().ToString()) ); } var youtubeService = new YouTubeService(new BaseClientService.Initializer() { HttpClientInitializer = credential, ApplicationName = this.GetType().ToString() }); var channelsListRequest = youtubeService.Channels.List("contentDetails"); channelsListRequest.Mine = true; // Retrieve the contentDetails part of the channel resource for the authenticated user's channel. var channelsListResponse = await channelsListRequest.ExecuteAsync(); foreach (var channel in channelsListResponse.Items) { // From the API response, extract the playlist ID that identifies the list // of videos uploaded to the authenticated user's channel. var uploadsListId = channel.ContentDetails.RelatedPlaylists.Uploads; Console.WriteLine("Videos in list {0}", uploadsListId); var nextPageToken = ""; while (nextPageToken != null) { var playlistItemsListRequest = youtubeService.PlaylistItems.List("snippet"); playlistItemsListRequest.PlaylistId = uploadsListId; playlistItemsListRequest.MaxResults = 50; playlistItemsListRequest.PageToken = nextPageToken; // Retrieve the list of videos uploaded to the authenticated user's channel. var playlistItemsListResponse = await playlistItemsListRequest.ExecuteAsync(); foreach (var playlistItem in playlistItemsListResponse.Items) { // Print information about each video. Console.WriteLine("{0} ({1})", playlistItem.Snippet.Title, playlistItem.Snippet.ResourceId.VideoId); } nextPageToken = playlistItemsListResponse.NextPageToken; } } } } } https://github.com/youtube/api-samples/blob/07263305b59a7c3275bc7e925f9ce6cabf774022/dotnet/MyUploads.cs ``` ### Ruby This sample calls the API's `playlistItems.list` method to retrieve a list of videos uploaded to the channel associated with the request. The code also calls the `channels.list` method with the `mine` parameter set to `true` to retrieve the playlist ID that identifies the channel's uploaded videos. This example uses the [Ruby client library](https://developers.google.com/api-client-library/ruby). ```ruby #!/usr/bin/ruby require 'rubygems' gem 'google-api-client', '>0.7' require 'google/api_client' require 'google/api_client/client_secrets' require 'google/api_client/auth/file_storage' require 'google/api_client/auth/installed_app' # This OAuth 2.0 access scope allows for read-only access to the authenticated # user's account, but not other types of account access. YOUTUBE_READONLY_SCOPE = 'https://www.googleapis.com/auth/youtube.readonly' YOUTUBE_API_SERVICE_NAME = 'youtube' YOUTUBE_API_VERSION = 'v3' def get_authenticated_service client = Google::APIClient.new( :application_name => $PROGRAM_NAME, :application_version => '1.0.0' ) youtube = client.discovered_api(YOUTUBE_API_SERVICE_NAME, YOUTUBE_API_VERSION) file_storage = Google::APIClient::FileStorage.new("#{$PROGRAM_NAME}-oauth2.json") if file_storage.authorization.nil? client_secrets = Google::APIClient::ClientSecrets.load flow = Google::APIClient::InstalledAppFlow.new( :client_id => client_secrets.client_id, :client_secret => client_secrets.client_secret, :scope => [YOUTUBE_READONLY_SCOPE] ) client.authorization = flow.authorize(file_storage) else client.authorization = file_storage.authorization end return client, youtube end def main client, youtube = get_authenticated_service begin # Retrieve the "contentDetails" part of the channel resource for the # authenticated user's channel. channels_response = client.execute!( :api_method => youtube.channels.list, :parameters => { :mine => true, :part => 'contentDetails' } ) channels_response.data.items.each do |channel| # From the API response, extract the playlist ID that identifies the list # of videos uploaded to the authenticated user's channel. uploads_list_id = channel['contentDetails']['relatedPlaylists']['uploads'] # Retrieve the list of videos uploaded to the authenticated user's channel. next_page_token = '' until next_page_token.nil? playlistitems_response = client.execute!( :api_method => youtube.playlist_items.list, :parameters => { :playlistId => uploads_list_id, :part => 'snippet', :maxResults => 50, :pageToken => next_page_token } ) puts "Videos in list #{uploads_list_id}" # Print information about each video. playlistitems_response.data.items.each do |playlist_item| title = playlist_item['snippet']['title'] video_id = playlist_item['snippet']['resourceId']['videoId'] puts "#{title} (#{video_id})" end next_page_token = playlistitems_response.next_page_token end puts end rescue Google::APIClient::TransmissionError => e puts e.result.body end end main https://github.com/youtube/api-samples/blob/07263305b59a7c3275bc7e925f9ce6cabf774022/ruby/my_uploads.rb ``` ## Errors The following table identifies error messages that the API could return in response to a call to this method. Please see the [error message](https://developers.google.com/youtube/v3/docs/errors) documentation for more detail. | Error type | Error detail | Description | |----------------------|--------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------| | `forbidden (403)` | `playlistItemsNotAccessible` | The request is not properly authorized to retrieve the specified playlist. | | `forbidden (403)` | `watchHistoryNotAccessible` | Watch history data cannot be retrieved through the API. | | `forbidden (403)` | `watchLaterNotAccessible` | Items in "watch later" playlists cannot be retrieved through the API. | | `notFound (404)` | `playlistNotFound` | The playlist identified with the request's `playlistId` parameter cannot be found. | | `notFound (404)` | `videoNotFound` | The video identified with the request's `videoId` parameter cannot be found. | | `required (400)` | `playlistIdRequired` | The subscribe request does not specify a value for the required `playlistId` property. | | `invalidValue (400)` | `playlistOperationUnsupported` | The API does not support the ability to list videos in the specified playlist. For example, you can't list a video in your watch later playlist. | ## Try it! Use the APIs Explorer to call this API and see the API request and response. --- # Source: https://developers.google.com/youtube/v3/docs/playlistItems/update.md.txt # PlaylistItems: update Modifies a playlist item. For example, you could update the item's position in the playlist. **Quota impact:** A call to this method has a [quota cost](https://developers.google.com/youtube/v3/getting-started#quota) of 50 units. ## Common use cases The list below shows common use cases for this method. Hover over a use case to see its description, or click on a use case to load sample parameter values in the APIs Explorer. You can open the [fullscreen APIs Explorer](https://developers.google.com/youtube/v3/docs/playlistItems/update#) to see code samples that dynamically update to reflect the parameter values entered in the Explorer. The table below shows common use cases for this method. You can click on a use case name to load sample parameter values in the APIs Explorer. Or you can see code samples for a use case in the fullscreen APIs Explorer by clicking on the code icon below a use case name. In the fullscreen UI, you can update parameter and property values and the code samples will dynamically update to reflect the values you enter. This method has one common use case, which is described below. The buttons below the description populate the APIs Explorer with sample values or open the fullscreen APIs Explorer to show code samples that use those values. The code samples also dynamically update if you change the values.
## Request ### HTTP request ``` PUT https://www.googleapis.com/youtube/v3/playlistItems ``` ### Authorization This request requires authorization with at least one of the following scopes ([read more about authentication and authorization](https://developers.google.com/youtube/v3/guides/authentication)). | Scope | |-----------------------------------------------------| | `https://www.googleapis.com/auth/youtubepartner` | | `https://www.googleapis.com/auth/youtube` | | `https://www.googleapis.com/auth/youtube.force-ssl` | ### Parameters The following table lists the parameters that this query supports. All of the parameters listed are query parameters. | Parameters || |--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---| | **Required parameters** ||| | `part` | `string` The **part** parameter serves two purposes in this operation. It identifies the properties that the write operation will set as well as the properties that the API response will include. Note that this method will override the existing values for all of the mutable properties that are contained in any parts that the parameter value specifies. For example, a playlist item can specify a start time and end time, which identify the times portion of the video that should play when users watch the video in the playlist. If your request is updating a playlist item that sets these values, and the request's `part` parameter value includes the `contentDetails` part, the playlist item's start and end times will be updated to whatever value the request body specifies. If the request body does not specify values, the existing start and end times will be removed and replaced with the default settings. The following list contains the `part` names that you can include in the parameter value: - `contentDetails` - `id` - `snippet` - `status` | | **Optional parameters** ||| | `onBehalfOfContentOwner` | `string` **Note:** The **onBehalfOfContentOwner** parameter is intended exclusively for YouTube content partners and can only be used in a properly [authorized request](https://developers.google.com/youtube/v3/guides/authentication). This parameter is designed for YouTube content partners that own and manage many different YouTube channels. It enables users affiliated with the content owner to authenticate once and then be able to access and manage all of the content owner's video and channel data, without having to provide authentication credentials for each individual channel. When the parameter is present, its value identifies a content owner, and the request's authorization credentials identify a YouTube user who is authorized to act on behalf of that content owner. The account that the user authenticates with must be [linked to the specified content owner](https://support.google.com/youtube/answer/4524878) in the YouTube Creator Studio settings. | ### Request body Provide a [playlistItem resource](https://developers.google.com/youtube/v3/docs/playlistItems#resource) in the request body. For that resource: - You must specify a value for these properties:
- `id` - `snippet.playlistId` - `snippet.resourceId`
- You can set values for these properties:
- `snippet.position` - `contentDetails.note` - `contentDetails.startAt` - `contentDetails.endAt`
If you are submitting an update request, and your request does not specify a value for a property that already has a value, the property's existing value will be deleted. ## Response If successful, this method returns a [playlistItem resource](https://developers.google.com/youtube/v3/docs/playlistItems#resource) in the response body. ## Errors The following table identifies error messages that the API could return in response to a call to this method. Please see the [error message](https://developers.google.com/youtube/v3/docs/errors) documentation for more detail. | Error type | Error detail | Description | |----------------------|--------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `forbidden (403)` | `playlistItemsNotAccessible` | The request is not properly authorized to update the specified playlist item. | | `invalidValue (400)` | `invalidPlaylistItemPosition` | The request attempts to set the playlist item's position to an invalid or unsupported value. Check the value of the `position` property in the resource's `snippet`. | | `invalidValue (400)` | `invalidResourceType` | The `type` specified for the resource ID is not supported for this operation. The resource ID identifies the item being added to the playlist -- e.g. `youtube#video`. | | `invalidValue (400)` | `invalidSnippet` | The request does not specify a valid `snippet` property. | | `invalidValue (400)` | `manualSortRequired` | The request attempts to set the playlist item's position, but the playlist does not use manual sorting. (For example, playlist items might be sorted by date or popularity.) You can address the error by removing the `snippet.position` element from the resource that the request is inserting. If you want the playlist item to have a particular position in the list, you need to first update the playlist's **Ordering** option to **Manual** in the playlist's settings. This settings can be adjusted in the [YouTube Video Manager](https://www.youtube.com/view_all_playlists). | | `notFound (404)` | `playlistItemNotFound` | The playlist item identified with the request's `id` property cannot be found. | | `notFound (404)` | `playlistNotFound` | The playlist identified with the request's `playlistId` parameter cannot be found. | | `required (400)` | `channelIdRequired` | The request does not specify a value for the required `channelId` property. | | `required (400)` | `playlistIdRequired` | The request does not specify a value for the required `playlistId` property. | | `required (400)` | `playlistItemIdRequired` | The playlist item resource specified in the request must use the `id` property to identify the playlist item that is being updated. | | `invalidValue (400)` | `playlistOperationUnsupported` | The API does not support the ability to update videos in the specified playlist. For example, you can't update a video in your uploaded videos playlist. | ## Try it! Use the APIs Explorer to call this API and see the API request and response. --- # Source: https://developers.google.com/youtube/v3/docs/playlists.md.txt # 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. 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 - positively rated (liked) videos 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](https://developers.google.com/youtube/v3/docs/channels) for a given channel. You can then use the [playlistItems.list](https://developers.google.com/youtube/v3/docs/playlistItems/list) method to retrieve any of those lists. You can also add or remove items from those lists by calling the [playlistItems.insert](https://developers.google.com/youtube/v3/docs/playlistItems/insert) and [playlistItems.delete](https://developers.google.com/youtube/v3/docs/playlistItems/delete) methods.
## Methods The API supports the following methods for `playlists` resources: [list](https://developers.google.com/youtube/v3/docs/playlists/list) : 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. [Try it now](https://developers.google.com/youtube/v3/docs/playlists/list#usage). [insert](https://developers.google.com/youtube/v3/docs/playlists/insert) : Creates a playlist. [Try it now](https://developers.google.com/youtube/v3/docs/playlists/insert#usage). [update](https://developers.google.com/youtube/v3/docs/playlists/update) : Modifies a playlist. For example, you could change a playlist's title, description, or privacy status. [Try it now](https://developers.google.com/youtube/v3/docs/playlists/update#usage). [delete](https://developers.google.com/youtube/v3/docs/playlists/delete) : Deletes a playlist. [Try it now](https://developers.google.com/youtube/v3/docs/playlists/delete#usage). ## Resource representation The following JSON structure shows the format of a `playlists` resource: ```gdscript { "https://developers.google.com/youtube/v3/docs/playlists#kind": "youtube#playlist", "https://developers.google.com/youtube/v3/docs/playlists#etag": etag, "https://developers.google.com/youtube/v3/docs/playlists#id": string, "https://developers.google.com/youtube/v3/docs/playlists#snippet": { "https://developers.google.com/youtube/v3/docs/playlists#snippet.publishedAt": datetime, "https://developers.google.com/youtube/v3/docs/playlists#snippet.channelId": string, "https://developers.google.com/youtube/v3/docs/playlists#snippet.title": string, "https://developers.google.com/youtube/v3/docs/playlists#snippet.description": string, "https://developers.google.com/youtube/v3/docs/playlists#snippet.thumbnails": { (key): { "https://developers.google.com/youtube/v3/docs/playlists#snippet.thumbnails.(key).url": string, "https://developers.google.com/youtube/v3/docs/playlists#snippet.thumbnails.(key).width": unsigned integer, "https://developers.google.com/youtube/v3/docs/playlists#snippet.thumbnails.(key).height": unsigned integer } }, "https://developers.google.com/youtube/v3/docs/playlists#snippet.channelTitle": string, "https://developers.google.com/youtube/v3/docs/playlists#snippet.defaultLanguage": string, "https://developers.google.com/youtube/v3/docs/playlists#snippet.localized": { "https://developers.google.com/youtube/v3/docs/playlists#snippet.localized.title": string, "https://developers.google.com/youtube/v3/docs/playlists#snippet.localized.description": string } }, "https://developers.google.com/youtube/v3/docs/playlists#status": { "https://developers.google.com/youtube/v3/docs/playlists#status.privacyStatus": string, "https://developers.google.com/youtube/v3/docs/playlists#status.podcastStatus": enum }, "https://developers.google.com/youtube/v3/docs/playlists#contentDetails": { "https://developers.google.com/youtube/v3/docs/playlists#contentDetails.itemCount": unsigned integer }, "https://developers.google.com/youtube/v3/docs/playlists#player": { "https://developers.google.com/youtube/v3/docs/playlists#player.embedHtml": string }, "https://developers.google.com/youtube/v3/docs/playlists#localizations": { (key): { "https://developers.google.com/youtube/v3/docs/playlists#localizations.title": string, "https://developers.google.com/youtube/v3/docs/playlists#localizations.description": 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#playlist`. | | `etag` | `etag` The Etag of this resource. | | `id` | `string` The ID that YouTube uses to uniquely identify the playlist. | | `snippet` | `object` The `snippet` object contains basic details about the playlist, such as its title and description. | | snippet.`publishedAt` | `datetime` The date and time that the playlist was created. 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 channel that published the playlist. | | snippet.`title` | `string` The playlist's title. | | snippet.`description` | `string` The playlist's description. | | snippet.`thumbnails` | `object` A map of thumbnail images associated with the playlist. 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 video belongs to. | | snippet.`tags[]` | `list` This property has been deprecated. Keyword tags associated with the playlist. | | snippet.`defaultLanguage` | `string` The language of the text in the `playlist` resource's `snippet.title` and `snippet.description` properties. | | snippet.`localized` | `object` The `snippet.localized` object contains either a localized title and description for the playlist or the title in the [default language](https://developers.google.com/youtube/v3/docs/playlists#snippet.defaultLanguage) for the playlist's metadata. - Localized text is returned in the resource snippet if the [playlists.list](https://developers.google.com/youtube/v3/docs/playlists/list) request used the `hl` parameter to specify a language for which localized text should be returned *and* localized text is available in that language. - Metadata for the default language is returned if an `hl` parameter value is not specified *or* a value is specified but localized metadata is not available for the specified language. The property contains a read-only value. Use the [localizations](https://developers.google.com/youtube/v3/docs/playlists#localizations) object to add, update, or delete localized titles. | | snippet.localized.`title` | `string` The localized playlist title. | | snippet.localized.`description` | `string` The localized playlist description. | | `status` | `object` The `status` object contains status information for the playlist. | | status.`privacyStatus` | `string` The playlist's privacy status. Valid values for this property are: - `private` - `public` - `unlisted` | | status.`podcastStatus` | `string` The playlist's podcast status. If value is `enabled`, the playlist is marked as a podcast show. To set a playlist's podcast status to `enabled`, the playlist must have a [playlist image](https://developers.google.com/youtube/v3/docs/playlistImages/insert). Valid values for this property are: - `enabled` - `disabled` - `unspecified` | | `contentDetails` | `object` The `contentDetails` object contains information about the playlist content, including the number of videos in the playlist. | | contentDetails.`itemCount` | `unsigned integer` The number of videos in the playlist. | | `player` | `object` The `player` object contains information that you would use to play the playlist in an embedded player. | | player.`embedHtml` | `string` An `