Channels | YouTube Data API | Google Developers

A channel resource contains information about a YouTube channel.

Methods

The API supports the following methods for channels resources:

list: Returns a collection of zero or more channel resources that match the request criteria. Try it now.
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.

Resource representation

The following JSON structure shows the format of a channels resource:

{
  "kind": "youtube#channel",
  "etag": etag,
  "id": string,
  "snippet": {
    "title": string,
    "description": string,
    "customUrl": string,
    "publishedAt": datetime,
    "thumbnails": {
      (key): {
        "url": string,
        "width": unsigned integer,
        "height": unsigned integer
      }
    },
    "defaultLanguage": string,
    "localized": {
      "title": string,
      "description": string
    },
    "country": string
  },
  "contentDetails": {
    "relatedPlaylists": {
      "likes": string,
      "favorites": string,
      "uploads": string,
      "watchHistory": string,
      "watchLater": string
    }
  },
  "statistics": {
    "viewCount": unsigned long,
    "commentCount": unsigned long,
    "subscriberCount": unsigned long,
    "hiddenSubscriberCount": boolean,
    "videoCount": unsigned long
  },
  "topicDetails": {
    "topicIds": [
      string
    ]
  },
  "status": {
    "privacyStatus": string,
    "isLinked": boolean,
    "longUploadsStatus": string
  },
  "brandingSettings": {
    "channel": {
      "title": string,
      "description": string,
      "keywords": string,
      "defaultTab": string,
      "trackingAnalyticsAccountId": string,
      "moderateComments": boolean,
      "showRelatedChannels": boolean,
      "showBrowseView": boolean,
      "featuredChannelsTitle": string,
      "featuredChannelsUrls": [
        string
      ],
      "unsubscribedTrailer": string,
      "profileColor": string,
      "defaultLanguage": string,
      "country": string
    },
    "watch": {
      "textColor": string,
      "backgroundColor": string,
      "featuredPlaylistId": string
    },
    "image": {
      "bannerImageUrl": string,
      "bannerMobileImageUrl": string,
      "watchIconImageUrl": string,
      "trackingImageUrl": string,
      "bannerTabletLowImageUrl": string,
      "bannerTabletImageUrl": string,
      "bannerTabletHdImageUrl": string,
      "bannerTabletExtraHdImageUrl": string,
      "bannerMobileLowImageUrl": string,
      "bannerMobileMediumHdImageUrl": string,
      "bannerMobileHdImageUrl": string,
      "bannerMobileExtraHdImageUrl": string,
      "bannerTvImageUrl": string,
      "bannerTvLowImageUrl": string,
      "bannerTvMediumImageUrl": string,
      "bannerTvHighImageUrl": string,
      "bannerExternalUrl": string
    },
    "hints": [
      {
        "property": string,
        "value": string
      }
    ]
  },
  "invideoPromotion": {
    "defaultTiming": {
      "type": string,
      "offsetMs": unsigned long,
      "durationMs": unsigned long
    },
    "position": {
      "type": string,
      "cornerPosition": string
    },
    "items": [
      {
        "id": {
          "type": string,
          "videoId": string,
          "websiteUrl": string,
          "recentlyUploadedBy": string
        },
        "timing": {
          "type": string,
          "offsetMs": unsigned long,
          "durationMs": unsigned long
        },
        "customMessage": string,
        "promotedByContentOwner": boolean
      }
    ],
    "useSmartTiming": boolean
  },
  "auditDetails": {
    "overallGoodStanding": boolean,
    "communityGuidelinesGoodStanding": boolean,
    "copyrightStrikesGoodStanding": boolean,
    "contentIdClaimsGoodStanding": boolean
  },
  "contentOwnerDetails": {
    "contentOwner": string,
    "timeLinked": datetime
  },
  "localizations": {
    (key): {
      "title": string,
      "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 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 (`YYYY-MM-DDThh:mm:ss.sZ`) 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.
`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.
`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 for the channel's metadata. Localized text is returned in the resource snippet if the `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, 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` 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` 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` method.
`contentDetails.relatedPlaylists.likes`	`string` The ID of the playlist that contains the channel's liked videos. Use the `playlistItems.insert` and `playlistItems.delete` methods to add or remove items from that list.
`contentDetails.relatedPlaylists.favorites`	`string` The ID of the playlist that contains the channel's favorite videos. Use the `playlistItems.insert` and `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` method to upload new videos and the `videos.delete` method to delete previously uploaded videos.
`contentDetails.relatedPlaylists.watchHistory`	`string` Note: This property has been deprecated. The property's value is always set to `HL`. The API now returns an empty list in response to requests for playlist details (`playlists.list`) or playlist items (`playlistItems.list`) for this playlist. That empty-list behavior is also true for any `watchHistory` playlist IDs that your API Client may have already stored.
`contentDetails.relatedPlaylists.watchLater`	`string` Note: This property has been deprecated. The property's value is always set to `WL`. The API now returns an empty list in response to requests for playlist details (`playlists.list`) or playlist items (`playlistItems.list`) for this playlist. That empty-list behavior is also true for any `watchLater` playlist IDs that your API Client may have already stored.
`statistics`	`object` The `statistics` object encapsulates statistics for the channel.
`statistics.viewCount`	`unsigned long` The number of times the channel has been viewed.
`statistics.commentCount`	`unsigned long` The number of comments for the channel.
`statistics.subscriberCount`	`unsigned long` The number of subscribers that the channel has.
`statistics.hiddenSubscriberCount`	`boolean` Indicates whether the channel's subscriber count is publicly visible.
`statistics.videoCount`	`unsigned long` The number of videos uploaded to the channel.
`topicDetails`	`object` The `topicDetails` object encapsulates information about Freebase topics associated with the channel. Important: Due to the deprecation of Freebase and the Freebase API, topic IDs will start working differently as of February 10, 2017. At that time, YouTube will start returning a small set of topic IDs instead of the much more granular set of IDs returned now. See the revision history for more details about this change.
`topicDetails.topicIds[]`	`list` A list of Freebase topic IDs associated with the channel. Important: See the `topicDetails` property for important information about an upcoming change to topic ID behavior.
`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. See the YouTube Help Center for more information about this feature. 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 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 at https://www.youtube.com/verify. See the YouTube Help Center for more detailed information about this feature.
`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.
`brandingSettings.channel.defaultTab`	`string` The content tab that users should display by default when viewers arrive at your channel page.
`brandingSettings.channel.trackingAnalyticsAccountId`	`string` The ID for a Google Analytics account that you want to use to track and measure traffic to your channel.
`brandingSettings.channel.moderateComments`	`boolean` This setting determines 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`.
`brandingSettings.channel.showRelatedChannels`	`boolean` This setting indicates whether YouTube should show an algorithmically generated list of related channels on your channel page.
`brandingSettings.channel.showBrowseView`	`boolean` This setting indicates whether the channel page should display content in a browse or feed view. For example, the browse view might display separate sections for uploaded videos, playlists, and liked videos. The feed view, on the other hand, displays the channel's activity feed.
`brandingSettings.channel.featuredChannelsTitle`	`string` The title that displays above the featured channels module. The title has a maximum length of 30 characters.
`brandingSettings.channel.featuredChannelsUrls[]`	`list` A list of up to 100 channels that you would like to link to from the featured channels module. The property value is a list of YouTube channel ID values, each of which uniquely identifies a 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.profileColor`	`string` A prominent color that complements the channel's content.
`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` 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 background color for the video watch page's branded area.
`brandingSettings.watch.backgroundColor`	`string` Note: This property has been deprecated. The text 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` The `image` object encapsulates information about images that display on the channel's channel page or video watch pages.
`brandingSettings.image.bannerImageUrl`	`string` 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` The URL for the banner image shown on the channel page in mobile applications. The image is 640px by 175px.
`brandingSettings.image.watchIconImageUrl`	`string` 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` 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` 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` 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` 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` 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` 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` 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` 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` 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` 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` 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` 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` 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` Note: This property is only used in `channels.update` requests. This property specifies the location of the banner image that YouTube will use to generate the various banner image sizes for a channel. To obtain the URL banner image's external URL, you must first upload the channel banner image that you want to use by calling the `channelBanners.insert` method.
`brandingSettings.hints[]`	`list` The `hints` object encapsulates additional branding properties.
`brandingSettings.hints[].property`	`string` A property.
`brandingSettings.hints[].value`	`string` The property's value.
`invideoPromotion`	`object` The `invideoPromotion` object encapsulates information about a promotional campaign associated with the channel. A channel can use an in-video promotional campaign to display the thumbnail image of a promoted video in the video player during playback of the channel's videos. This object can only be retrieved (or updated) by the channel's owner.
`invideoPromotion.defaultTiming`	`object` The `defaultTiming` object identifies the channel's default timing settings for when a promoted item will display during a video playback. These default settings can be overriden by more specific `timing` settings for any given promoted item.
`invideoPromotion.defaultTiming.type`	`string` The timing method that determines when the promoted item is inserted during the video playback. If the value is `offsetFromStart`, then the `offsetMs` field represents an offset from the start of the video. If the value is `offsetFromEnd`, then the `offsetMs` field represents an offset from the end of the video.
`invideoPromotion.defaultTiming.offsetMs`	`unsigned long` The time offset, specified in milliseconds, that determines when the promoted item appears during video playbacks. The `type` property's value determines whether the offset is measured from the start or end of the video.
`invideoPromotion.defaultTiming.durationMs`	`unsigned long` Defines the duration in milliseconds for which the promotion should be displayed. If missing, the client should use the default.
`invideoPromotion.position`	`object` The `position` object encapsulates information about the spatial position within the video where the promoted item will be displayed.
`invideoPromotion.position.type`	`string` The manner in which the promoted item is positioned in the video player. Valid values for this property are: `corner`
`invideoPromotion.position.cornerPosition`	`string` The corner of the player where the promoted item will appear. Valid values for this property are: `bottomLeft` `bottomRight` `topLeft` `topRight`
`invideoPromotion.items[]`	`list` The list of promoted items in the order that they will display across different playbacks to the same viewer. Note that you can typically only set one promoted item for your channel. If you try to insert too many promoted items, the API will return a `tooManyPromotedItems` error, which has an HTTP `400` status code.
`invideoPromotion.items[].id`	`object` Identifies the promoted item.
`invideoPromotion.items[].id.type`	`string` The promoted item's type. Valid values for this property are: `video` `website` `recentUpload`
`invideoPromotion.items[].id.videoId`	`string` If the promoted item represents a video, then this value is present and identifies the YouTube ID that YouTube assigned to identify that video. This field is only present if the `type` property's value is `video`.
`invideoPromotion.items[].id.websiteUrl`	`string` If the promoted item represents a website, this field represents the url pointing to the website. This field will be present only if `type` has the value `website`. Links can be to associated websites, merchant sites, or social networking sites. See the YouTube Help Center instructions for associated websites and merchant sites for more information about enabling links for your content. By adding promotional links, you agree that those links will not be used to redirect traffic to unauthorized sites and that those links will comply with AdWords policies, YouTube ad policies, YouTube Community Guidelines and YouTube Terms of Service.
`invideoPromotion.items[].id.recentlyUploadedBy`	`string` If the `invideoPromotion.items[].id.type` property's value is `recentUpload`, then this field identifies the channel for which the most recently uploaded video will be promoted. By default, the channel is the same one for which the in-video promotion data is set. However, you can promote the most recently uploaded video from another channel by setting this property's value to the channel ID for that channel.
`invideoPromotion.items[].timing`	`object` The time during a video playback when the promoted item will display. These timing settings override the channel's default timing settings.
`invideoPromotion.items[].timing.type`	`string` The timing method that determines when the promoted item is inserted during the video playback. If the value is `offsetFromStart`, then the `offsetMs` field represents an offset from the start of the video. If the value is `offsetFromEnd`, then the `offsetMs` field represents an offset from the end of the video.
`invideoPromotion.items[].timing.offsetMs`	`unsigned long` The time offset, specified in milliseconds, that determines when the promoted item appears during video playbacks. The `type` property's value determines whether the offset is measured from the start or end of the video.
`invideoPromotion.items[].timing.durationMs`	`unsigned long` Defines the duration in milliseconds for which the promotion should be displayed. If missing, the client should use the default.
`invideoPromotion.items[].customMessage`	`string` A custom message to display for this promotion. This field is currently ignored unless the promoted item is a website. The property value has a maximum length of 40 characters.
`invideoPromotion.items[].promotedByContentOwner`	`boolean` Indicates whether the content owner's name will be shown when displaying the promotion. This field can only be set if the API request that sets the value is being made on the content owner's behalf. See the `onBehalfOfContentOwner` parameter for more information.
`invideoPromotion.useSmartTiming`	`boolean` Indicates whether the channel's promotional campaign uses "smart timing." This feature attempts to show promotions at a point in the video when they are more likely to be clicked and less likely to disrupt the viewing experience. This feature also picks up a single promotion to show on each video.
`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 relevant for YouTube Partners linked with the channel.
`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 (`YYYY-MM-DDThh:mm:ss.sZ`) 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 language code.
`localizations.(key).title`	`string` The localized channel title.
`localizations.(key).description`	`string` The localized channel description.