YouTube

YouTube API v2.0 - Branding options

Note: The YouTube Data API (v2) has been officially deprecated as of March 4, 2014. Please refer to our deprecation policy for more information.

Overview

This page explains how to use the API to retrieve and programmatically update channel page branding elements.

Please note the following restrictions for this API feature:

  • You can only retrieve or update channel branding information for a channel that is linked to a YouTube content partner participating in the YouTube Partner Program. If you try to retrieve branding options for other channels, the API will return an entry that does not include any channel settings.

  • An API request to retrieve or update channel branding settings must specify a developer key.

  • An API request to update channel branding settings must be authenticated by the channel owner.

Note: This part of the YouTube API exposes user interface (UI) settings. As the YouTube channel page changes, the UI settings that you can update via the API will also change.

This page contains the following sections:

  • The Branding settings section defines the branding options that you can set via the API.

  • The Retrieving branding settings section explains how to retrieve a feed of your channel's current branding settings.

  • The Updating branding settings section explains how to submit an HTTP PUT request to update branding options for your channel.

  • The Uploading images section explains how to upload images to YouTube's image server so that you can update branding options to display those images.

  • The Error responses section lists errors that the API can return in response to requests to retrieve or update channel branding options.

Branding settings

The API uses the <yt:option> element to identify branding settings for your channel. The element's name attribute identifies the setting, and the element's value specifies the value that your channel currently uses for that setting.

For example, the XML excerpt below indicates that the title of the 'Featured channels' module is Check it out:

<yt:option name='channel.featured_channels_module1.title.string'>Check it out</yt:option>

The tables below identify the channel branding settings that can be retrieved or updated using the API. In each table, the setting name identifies the value of the <yt:option> element's name attribute, and the description explains the format of the element's value.

  1. General
  2. Images
  3. Tabs
  4. Content
  5. Tracking

General

Setting name Description
channel.global.title.string This property specifies your channel title. The title displays above your channel name, next to the button for subscribing to your channel. It has a maximum length of 30 characters.
channel.global.description.string This property updates the channel description that appears in the channel information box on your brand channel page.
channel.global.keywords.string This property lists keywords associated with your channel. The keywords will help users find your channel via YouTube search results.

Images

See the Uploading images section for more details.

Setting name Description
channel.background.image.url The value specifies the URL for the channel page background image. Brand channels have the option of uploading background images up to 1MB. However, we recommend that you choose a background image that is 256KB or smaller, which is the maximum background image size for standard user channels. Larger background images correlate to higher page latency, so if you upload a 1MB image, users visiting your page will have to wait longer for your page to load.
channel.banner.image_height.int This option sets the height of the channel banner. The banner can be between 1 pixel and 150 pixels tall, and the value should be an integer between 1 and 150.
channel.banner.image.imap_script Use this setting if you want your channel banner to link to multiple locations. Your image map code only needs to include the <area> tags for the image map, though it can wrap the <area> tags in a <map> tag as well.

Tabs

Setting name Description
channel.tabs.default_tab.string This property specifies which content tab (Featured, Feed, or Videos) users should see when viewing your channel.
channel.feed_tab.is_default_for_subscribers.bool This property lets you specify that the Feed tab should be the default tab for users who have already subscribed to your channel even if you have selected a different default tab for the channel. This option exists because subscribed users are likely to have already seen your featured video (or playlist). As such, sending them to the Feed tab can give them access to the most recent activity on your channel rather than directing them to a tab that might contain more introductory information about your brand that they have already viewed.
channel.featured_tab.show.bool This property indicates whether the channel should display a Featured content tab. The Featured tab is an optional channel page element that lets you highlight content that you think will be most engaging to users.
channel.featured_tab.template.string This property identifies the template that you want to use for the channel's Featured tab. Valid values are Creator, Blogger, Network, Everything, and Live Broadcaster.

Content

Setting name Description
channel.modules.show_comments.bool The value indicates whether the channel page should display the comments module. If enabled, the comments module displays on the Featured and Feed tabs.
channel.modules.moderate_comments.bool The value indicates whether user-submitted comments left on the channel page need to be approved by the channel owner to be publicly visible. The default value is false.
channel.featured_video_module.video_id.string This property identifies the video that should play in the featured video player when the channel's Featured tab loads. If the featured_video_module.show_list.bool setting is also set to True and the featured_video_module.featured_list.id specifies a playlist ID, then the playlist will begin playing with this video.
channel.featured_video_module.playlist_id.string This property identifies the playlist that should play in the featured video player when the channel's Featured tab loads. If you provide a value for this setting but do not specify a value for the featured_video_module.featured_video.id property, then the playlist will start playing with the first item in the playlist.
channel.featured_playlist_module.playlist_id.string This property specifies the playlist ID that identifies the playlist that you want to appear in the single playlist module. This module only displays in the Featured tab's Blogger template.
channel.featured_playlists_module.title.string This property specifies a title for the featured playlists module.
channel.featured_playlists_module.playlist_id.list This property specifies a list of one to ## playlists that you want to display in the featured playlists module. That module displays in all Featured tab templates except the Network template.
channel.featured_channels_module1.title.string This property specifies a title for the featured channels module. That module displays on the Creator, Blogger, and Network templates.
channel.featured_channels_module1.channel_name.list This property specifies a list of up to 16 channels that you would like to link to from the featured channels module. The property value is a string that consists of a comma-separated list of YouTube user ID values, each of which uniquely identifies a channel. User IDs are communicated in API responses as the value of the <yt:userId> tag.
channel.featured_channels_module2.title.string This property specifies a title for the more featured channels module. That module only displays on the Network template.
channel.featured_channels_module2.channel_name.list This property specifies a list of up to 16 channels that you would like to link to from the more featured channels module. The property value is a string that consists of a comma-separated list of YouTube user ID values, each of which uniquely identifies a channel. User IDs are communicated in API responses as the value of the <yt:userId> tag.

Tracking

Setting name Description
channel.tracking.image.url This property specifies the URL for a 1px by 1px tracking pixel that you use to collect statistics for views of your channel or video pages.
channel.tracking.analytics_account.id This property lets you enter the ID for a Google Analytics account that you want to use to track and measure traffic to your channels. Google Analytics provides a comprehensive view of how visitors access and interact with channels. Google Analytics reports provide data such as traffic referral patterns, repeat visitation, user demographics, and much, much more.

Retrieving branding settings

This section explains how to retrieve a feed listing a specific user's playlists. Note that any request to retrieve channel branding information must specify a developer key.

  • To request a feed of the currently logged-in user's channel branding settings, send a GET request to the following URL:

    http://gdata.youtube.com/feeds/api/partners/default/branding/default?v=2
  • To retrieve a feed of another channel's branding settings, send a GET request to the following URL:

    http://gdata.youtube.com/feeds/api/partners/CHANNEL_NAME/branding/default?v=2

The XML entry below shows a sample API response to a request to retrieve a channel's branding settings:

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:app='http://www.w3.org/2007/app'
    xmlns:gd='http://schemas.google.com/g/2005'
    xmlns:yt='http://gdata.youtube.com/schemas/2007'
    gd:etag='W/"D0IDR347eCp7ImA9WxBbGU4."'>
  <id>tag:youtube.com,2008:partner:USERNAME:branding:default</id>
  <published>2010-03-18T18:06:16.000Z</published>
  <updated>2010-03-18T18:06:16.000Z</updated>
  <app:edited>2010-03-18T18:06:16.000Z</app:edited>
  <link rel='self' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/partners/USERNAME/branding/default?v=2'/>
  <link rel='edit' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/partners/USERNAME/branding/default?v=2'/>

  <!-- GENERAL SETTINGS -->
  <yt:option name='channel.global.title.string'>My title</yt:option>
  <yt:option name='channel.global.description.string'>About my channel.</yt:option>
  <yt:option name='channel.global.keywords.string'>some,channel,tags</yt:option>

  <!-- IMAGE SETTINGS -->
  <yt:option name='channel.background.image.url'>http://i3.ytimg.com/bg/ZxE-foo3h3B3mb4cuiBcKA/default.jpg?app=bg&v=c6bed2</yt:option>
  <yt:option name='channel.banner.image_height.int'>150</yt:option>
  <yt:option name='channel.banner.image.imap_script'>
    &lt;map name="ytimgmap"&gt;
      &lt;area shape="rect" coords="0,0,960,70" href="www.google.com" alt="Link to google.com" /&gt;
    &lt;/map&gt;
  </yt:option>

  <!-- TAB SETTINGS -->
  <yt:option name='channel.tabs.default_tab.string'>Featured</yt:option>
  <yt:option name='channel.feed_tab.is_default_for_subscribers.bool'>True</yt:option>
  <yt:option name='channel.featured_tab.show.bool'>True</yt:option>
  <yt:option name='channel.featured_tab.template.string'>Blogger</yt:option>

  <!-- CONTENT SETTINGS -->
  <yt:option name='channel.modules.show_comments.bool'>True</yt:option>
  <yt:option name='channel.modules.moderate_comments.bool'>True</yt:option>
  <yt:option name='channel.featured_channels_module1.title.string'>Other great channels</yt:option>
  <yt:option name='channel.featured_channels_module1.channel_name.list'>
    channel1,channel2,channel3,channel4,...
  </yt:option>

  <!-- TRACKING INFORMATION SETTINGS -->
  <yt:option name='channel.tracking.image.url'>http://www.example.com/tracking_image</yt:option>
  <yt:option name='channel.tracking.analytics_account.id'>UA-793910-4</yt:option>
</entry>

Note: When you retrieve a channel's branding settings, the API response does not list Boolean values that have a value of False. In addition, the API generally only returns the image and content settings for which the channel owner has set values so that the branding settings entry only includes content settings for images and other text that will display on the specified channel page. However, the following options will be included in the entry even if the channel owner has not set them:

Setting name Default value
channel.tabs.default_tab.string Featured
channel.background.image.url http://i3.ytimg.com/u/CHANNEL_ID/channels3_background.jpg?v=0
channel.banner.image_height.int 0
channel.featured_tab.template.string Creator

Updating branding options

You can update the branding options for a channel by sending a PUT or PATCH request, authenticated by the channel owner, to the following URL:

http://gdata.youtube.com/feeds/api/partner/default/branding/default
  • If you send a PUT request, it will update all of the channel's branding options. In processing your request, the API server will delete the channel's existing branding options and then insert any options specified in the body of the request. If the request does not specify a value for a particular branding option, then the option will revert to its default setting.

  • If you send a PATCH request, use the <entry> element's gd:fields attribute to identify the setting(s) that you want to update. (In fact, the gd:fields attribute indicates that you want to delete an existing setting. If your request does not specify a new value for the setting, the setting will revert to its default value.)

    • To update all of the channel's branding settings, set the gd:fields attribute value to yt:option and specify a <yt:option> tag for each branding setting that you want to set. (All other branding settings will revert to their default values.)

    • To update specific branding settings, set the gd:fields attribute value so that it only identifies the settings that you want to update. Include a <yt:option> tag for each of those settings that you want to set to a different value. (Other settings that you identify will revert to their default values.)

    • To delete all of the channel's branding settings, set the gd:fields attribute value to yt:option, but do not include any <yt:option> tags in the XML request.

Sample request to update brand options

The sample request below updates the channel's title, description, keywords, and featured channels module settings while resetting all other branding options to their default settings.

PUT /feeds/api/partners/default/branding/default HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:yt='http://gdata.youtube.com/schemas/2007'
    xmlns:gd='http://schemas.google.com/g/2005'>
  <yt:option name='channel.global.title.string'>Broccoli</yt:option>
  <yt:option name='channel.global.title.description'>
    Videos that showcase broccoli, a truly wonderful vegetable.
  </yt:option>
  <yt:option name='channel.global.keywords.string'>Broccoli,florets</yt:option>
  <yt:option name='channel.featured_channels_module1.title.string'>Other awesome channels</yt:option>
  <yt:option
    name='channel.featured_channels_module1.channel_name.list'>Spinach,Cauliflower,Cheetos</yt:option>
</entry>

In response to your request, the API will return the current branding settings for the updated channel. A best practice for both PUT and PATCH operations is to check the returned entry to verify that the API server successfully processed your changes. The Partial Updates section of the Developer's Guide explains PATCH requests in more detail.

Uploading images

Several branding options specify URLs for images that display on your channel page. However, before you can use an image for a branding option, you first need to upload the image to YouTube's image server. This section explains how to upload your images and obtain image URLs that you can use to update your channel branding options.

Step 1: Upload an image via the API

To upload an image to YouTube's image server, send an HTTP POST request to the following URL:

http://uploads.gdata.youtube.com/feeds/api/partners/default/images/IMAGE_TYPE

In the URL, replace the string IMAGE_TYPE with one of the following values to specify the type of image that you are uploading:

Image type Description
channels3_background The channel background image serves as the canvas for your channel page. Once you have uploaded the image, update the background image for your channel by setting the channel.background.image.url property.

YouTube does not set minimum or maximum values for the height and width of the background image, but backgrounds are usually between 1500px and 2000px wide and between 1200px and 2500px tall. In addition, the image can be up to 1MB, though we recommend that you choose an image that is 256KB or smaller to reduce page latency for users visiting your page.
profile_image This icon is a square image that is referred to as the avatar in your channel settings. It appears on your brand channel page as well as in channel search results and on your account overview page. Your original image should be 1600 pixels square. Note, however, that YouTube will resize the image to a 36px-by-36px size for the video navigator and a 60px-by-60px size for the channel ID module, so your image should still be recognizable when resized to those dimensions.

Note: After you upload a profile image, it is immediately used in your account. You do not need to submit an additional request to set the profile image as a branding option.

The following request demonstrates how to add an image that you can then use for your branding options:

POST /feeds/api/partners/default/images/IMAGE_TYPE HTTP/1.1
Host: uploads.gdata.youtube.com
Content-Type: image/jpeg
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY

BINARY_FILE_DATA

Step 2: Parse the image URL from the API response

If your image upload is successful, the API will return an Atom entry, in which the <content> element contains the image URL that you will use when setting branding options. The XML below shows a sample API response to a request to add an image.

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
       xmlns:app='http://www.w3.org/2007/app'>
  <id>tag:youtube.com,2008:image:aG9VnLnUvd2F0Y2hfYmFja2dyb3VuZC4u</id>
  <updated>2010-03-16T10:21:26.859Z</updated>
  <app:edited>2010-03-16T10:21:26.859Z</app:edited>
  <category scheme='http://schemas.google.com/g/2005#kind'
            term='http://gdata.youtube.com/schemas/2007#image'/>
  <content type='image/jpeg'
    src='http://i2.ytimg.com/u/9jOdOLdhzt8hHJUg/image_type?v=4b9f5ba6'/>
  <link rel='self' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/partners/username/images/image_type/image_id'/>
  <link rel='edit' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/partners/username/images/image_type/image_id'/>
</entry>

You need to extract the image URL from the API response so that you can set a branding option to use the image as described in the next step.

Step 3: Use the image URL to set a branding option

Use the <yt:option> element to set the URL for the appropriate branding image. (This step is discussed in more detail in the Updating branding options section above.)

The sample request below instructs YouTube to replace the channel's current background image with the one at the URL specified in the request. It also indicates that the background image contains an 80-pixel-high banner that should appear above the channel content.

PATCH /feeds/api/partners/default/branding/default HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    xmlns:yt='http://gdata.youtube.com/schemas/2007'
    gd:fields='yt:option[@name="channel.background.image.url" or
                         @name="channel.banner.image_height.int"]'>
  <yt:option name='channel.background.image.url'>
    http://i2.ytimg.com/u/9jOdOLdhzt8hHJUg/channels3_background?v=4b9f5ba6
  </yt:option>
  <yt:option name='channel.banner.image_height.url'>80</yt:option>
</entry>

Error responses

API requests to retrieve or update branding options can return the following error responses:

  • GET requests

    • ResourceNotFoundException – The API request specifies an unknown user. The HTTP response code will be 404 (Not Found).

  • PUT/PATCH requests

    • ResourceNotFoundException – The API request specifies an unknown user or an unknown branding option. The HTTP response code will be 404 (Not Found).

    • ServiceForbiddenException – The API request is not properly authenticated to update the specified channel, or the request attempts to update a channel that is not linked to a YouTube content partner participating in the YouTube Partner Program. The HTTP response code will be 403 (Forbidden).

    • InvalidEntryException – The API request specifies an invalid value in a <yt:option> tag. The HTTP response code will be 400 (Bad Request).

pagination links

« Previous
Revision History
Next »
Deprecated Features

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.