This is article 16 of the YouTube API With PHP series.
Channels are where videos are posted. Every YouTube user gets a default channel. A user can only have one Channel, except in the case of a YouTube Channel partner who can have multiple channels. In this series, we are not going to deal with data related to Channel Partners.
This resource has two functions available:
- list
- update
1.list
This function returns a collection of zero or more Channel resources that match the request criteria. Some filters used in the API call require user authentication, others dont.
The Request URL is
GET https://www.googleapis.com/youtube/v3/channels
Parameters
- key (string) required. Your API key
- access_token (string) required in certain cases. This is the user Access token.
- part (string) required. One or all of the following , comma separated:
- “auditDetails”
- “brandingSettings”
- “contentDetails”
- “contentOwnerDetails”
- “Id”
- “invideoPromotion”
- “localizations”
- “snippet”
- “statistics”
- “status”
- “topicDetails”
- Filters – one of the following:
- categoryId (string) A YouTube category id for which it will find matching channels
- forUserName (string) Requests channel(s) owned by the username
- id (string) Can be a single channel id or multiple channel ids in comma separated fashion.
- managedByMe (boolean) . Valid only for YouTube Channel Partners. Not used in this book.
- mine (boolean) . If set to true, then fetches channels of the current user
- h1 (string) optional. Specify a two-letter international language in which to return the localized resources of the channel. If no valid resources are available, then the data is returned in the default language.
- maxResults (int) optional. Can be between 0 and 50. Default is 5.
- onBehalfOfContentOwner (string) optional. This is relevant only for YouTube Channel Partners. For this parameter, the API request URL should have user authentication.We will not be exploring this option.
- pageToken (string) optional. The pagetoken for nextPage or prevPage.
Example Requests
Get channel matching a channel id
https://www.googleapis.com/youtube/v3/channels?key=xx&part=contentDetails,brandingSettings,contentOwnerDetails,id,invideoPromotion,localizations,snippet,statistics,status,topicDetails&auditDetails&id=xxx
Get channels for a category Id
https://www.googleapis.com/youtube/v3/channels?key=xx&part=contentDetails,brandingSettings,contentOwnerDetails,id,invideoPromotion,localizations,snippet,statistics,status,topicDetails&auditDetails&categoryId=xxx
Get channels for a userName
https://www.googleapis.com/youtube/v3/channels?key=xx”&access_token=xx&part=contentDetails,brandingSettings,contentOwnerDetails,id,invideoPromotion,localizations,snippet,statistics,status,topicDetails&auditDetails&userName=xxxx
Get channels of current user
https://www.googleapis.com/youtube/v3/channels?key=xx&part=contentDetails,brandingSettings,contentOwnerDetails,id,invideoPromotion,localizations,snippet,statistics,status,topicDetails&auditDetails&mine=1
Response
A successful API call will return an array of Channel resources encoded in json:
{ "kind": "youtube#channelListResponse", "etag": etag, "nextPageToken": string, "prevPageToken": string, "pageInfo": { "totalResults": integer, "resultsPerPage": integer }, "items": [ (Channel Resource) ] }
The Response components are explained below:
- kind (string) “youtube#channelListResponse.”
- etag (string) See ETags Explained section
- url (string) url of the banner image
- nextPageToken (string) token for the next page
- prevPageToken (string) token for the previous page
- totalResults (int) total count of results obtained
- resultsPerPage (int) results per page requested
- items (array) array of Channel Resource items returned
The JSON structure of a Channel Resource is shown below:
{ "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 ], "topicCategories": [ 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 } } }
An explanation of the various fields are given below:
- kind (string) This value is always “youtube#channel”
- etag (string) See ETags Explained section
- id (string) unique id of this Channel
- title (string) The channel’s title.
- description (string) The channel’s description. The property’s value has a maximum length of 1000 characters.
- customUrl (string) The channel’s custom URL
- publishedAt (datetime) Date and time this channel was created. (YYYY-MM-DDThh:mm:ss.sZ) format.
- thumbnails.(key) (string) . Possible key values are :
- “default” default thumbnail image. For videos it is 120px x 90px. For a Channel it is 88px x 88px .
- “medium” medium resolution thumbnail image. For videos it is 320px x 180px. For a Channel it is 240px x 240px .
- “high” high resolution thumbnail image. For videos it is 480px x 360. For a Channel it is 800px x 800px.
- thumbnails.(key).url (string) The image URL
- thumbnails.(key).width (unsigned int) image width in pixels
- thumbnails.(key).height (unsigned int) image height in pixels
- defaultLanguage (string) Two letter language code, for the language used in the snippet.title and snippet.description values
- localized.title (string) localized channel title
- localized.description (string) localized channel description
- country (string) two letter country code, signifying the country to which this channel belongs to
- 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.
- 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.
- 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.
- viewCount (long) The number of times the channel has been viewed.
- commentCount (long) The number of comments for the channel.
- subscriberCount (long) The number of subscribers that the channel has.
- hiddenSubscriberCount (boolean) Indicates whether the channel’s subscriber count is publicly visible.
- videoCount (long) The number of videos uploaded to the channel.
- topicDetails (object) The topicDetails object encapsulates information about topics associated with the channel.
- topicCategories (list) A list of Wikipedia URLs that describe the channel’s content.
- privacyStatus (string) Privacy status of the channel. Can be one of the following:
- “private”
- “public”
- “unlisted”
- 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.
- 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. 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 and it does not have any worldwide Content ID blocks on its content.
- “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.
- brandingSettings (object) The brandingSettings object encapsulates information about the branding of the channel.
- channel.title (string) The channel’s title. The title has a maximum length of 30 characters.
- 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.
- channel.keywords (string) Keywords associated with your channel. The value is a space-separated list of strings
- channel.defaultTab (string) The content tab that users should display by default when viewers arrive at your channel page.
- channel.trackingAnalyticsAccountId (string) The ID for a Google Analytics account that you want to use to track and measure traffic to your channel.
- 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.
- channel.showRelatedChannels (boolean) This setting indicates whether YouTube should show an algorithmically generated list of related channels on your channel page.
- 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.
- channel.featuredChannelsTitle (string) The title that displays above the featured channels module. The title has a maximum length of 30 characters.
- 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.
- 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.
- channel.profileColor (string) A prominent color that complements the channel’s content.
- channel.defaultLanguage (string) Two letter language code for the text in the channel resource’s snippet.title and snippet.description properties.
- channel.country (string) Two letter country code for the country with which the channel is associated. Update this property to set the value of the snippet.country property.
- image.bannerImageUrl (string) The URL for the banner image shown on the channel page on the YouTube website. The image is 1060px by 175px.
- image.bannerMobileImageUrl (string) The URL for the banner image shown on the channel page in mobile applications. The image is 640px by 175px.
- 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.
- 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.
- 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.
- image.bannerTabletImageUrl (string) The URL for a banner image that displays on the channel page in tablet applications. The image is 1707px by 283px.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- image.bannerExternalUrl (string) 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.
- hints (list) The hints object encapsulates additional branding properties.
- hints[].property (string) property
- hints[].value (string) value of property
- 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.
- 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.
- 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.
- defaultTiming.durationMs (unsigned long) Defines the duration in milliseconds for which the promotion should be displayed. If missing, the client should use the default.
- position.type (string) The manner in which the promoted item is positioned in the video player. Only “corner” is a valid value at the moment.
- position.cornerPosition (string) The corner of the player where the promoted item will appear. Valid values for this property are:
- “bottomLeft”
- “bottomRight”
- “topLeft”
- “topRight”
- 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.
- items[].id.type (string) The promoted item’s type. Valid values for this property are:
- “video”
- “website”
- “recentUpload”
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- communityGuidelinesGoodStanding (boolean) Indicates whether the channel respects YouTube’s community guidelines.
- copyrightStrikesGoodStanding (boolean) Indicates whether the channel has any copyright strikes.
- contentIdClaimsGoodStanding (boolean) Indicates whether the channel has any unresolved claims.
- contentOwner (string) The ID of the content owner linked to the channel.
- timeLinked (datetime) The date and time of when the channel was linked to the content owner. The value is specified in (YYYY-MM-DDThh:mm:ss.sZ) format.
- localizations (object) The localizations object encapsulates translations of the channel’s metadata.
- (key) (string) Key is the two letter language code used for the translation
- (key).title (string) The localized channel title.
- (key).description (string) The localized channel description.
Sample code to get channels using channel id
<?php error_reporting(E_ALL ^ E_NOTICE ^ E_WARNING ^ E_DEPRECATED); set_time_limit(60 * 3); $g_youtubeDataAPIKey = "**"; $channelId = "**"; // make api request $url = "https://www.googleapis.com/youtube/v3/channels?key=" . $g_youtubeDataAPIKey . "&part=contentDetails,brandingSettings,contentOwnerDetails,id,invideoPromotion,localizations,snippet,statistics,status,topicDetails&auditDetails&id=" . $channelId; $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_RETURNTRANSFER => 1, CURLOPT_URL => $url, CURLOPT_USERAGENT => 'YouTube API Tester', CURLOPT_SSL_VERIFYPEER => 1, CURLOPT_SSL_VERIFYHOST=> 0, CURLOPT_CAINFO => "../../cert/cacert.pem", CURLOPT_CAPATH => "../../cert/cacert.pem", CURLOPT_FOLLOWLOCATION => TRUE )); $resp = curl_exec($curl); curl_close($curl); if ($resp) { $json = json_decode($resp); if ($json) { echo("JSON decoded<br>"); $total = $json->pageInfo->totalResults; echo($total . " channels found.<br><br>"); $items = $json->items; foreach($items as $item) { $title = $item->snippet->title; $description = $item->snippet->description; $publishedAt = $item->snippet->publishedAt; $image = $item->snippet->thumbnails->high->url; $country = $item->snippet->country; $viewCount = $item->statistics->viewCount; $commentCount = $item->statistics->commentCount; $subscriberCount = $item->statistics->subscriberCount; $videoCount = $item->statistics->videoCount; echo("<img src=\"" . $image . "\" align=left>"); echo("Title :" . $title . "<br>"); echo("Description :" . $description . "<br>"); echo("Created on :" . $publishedAt . "<br>"); echo("Views:" . $viewCount . "<br>"); echo("Comments :" . $commentCount . "<br>"); echo("Subscribers:" . $subscriberCount . "<br>"); echo("Videos:" . $videoCount . "<br>"); echo("<hr>"); } } else exit("Error. could not parse JSON." . json_last_error_msg()); } // if resp ?>
Output:
JSON decoded
1 channels found.
Title :People are Awesome
Description :Licensing & business inquiries: contact@peopleareawesome.com Submit Your Video: http://bit.ly/21-submit-here PEOPLE ARE AWESOME is the number one destination for amazing, original videos and compilations of ordinary people doing extraordinary things. We feature all sorts of different extreme sports and activities other amazing feats, including parkour, skateboarding, tricking, cliff diving, wingsuit flying, skiing, snowboarding, surfing, BMX, acrobatics, calisthenics, cheerleading, freestyle football, basketball dunks, extreme pogo, freerunning, cycling, kayaking, frisbee trick shots, golf, martial arts, BASE jumping and many, many more a host of other action sports! Whether you’re searching in 2015 or any other year, check out our amazing and original action sports videos in HD where we show you why we think people are awesome! People are Awesome is owned and operated by Jukin Media Inc.
Created on :2007-01-01T19:50:14.000Z
Views:262609812
Comments :2603
Subscribers:1676231
Videos:269
Sample code to list channels of the current user:
<?php error_reporting(E_ALL ^ E_NOTICE ^ E_WARNING ^ E_DEPRECATED); session_start(); set_time_limit(60 * 3); $g_youtubeDataAPIKey = "**"; $channelId = "UCIJ0lLcABPdYGp7pRMGccAQ"; $_SESSION["code_id"] = $_SERVER["PHP_SELF"]; if ($_SESSION["access_token"] == null || $_SESSION["access_token"] == "") { // check for oauth response header("Location: ../../init-login.php"); exit; } $accessToken = $_SESSION["access_token"]; // make api request $url = "https://www.googleapis.com/youtube/v3/channels?key=" . $g_youtubeDataAPIKey . "&access_token=" . $accessToken. "&part=contentDetails,brandingSettings,contentOwnerDetails,id,invideoPromotion,localizations,snippet,statistics,status,topicDetails&auditDetails&mine=true&h1=fr"; $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_RETURNTRANSFER => 1, CURLOPT_URL => $url, CURLOPT_USERAGENT => 'YouTube API Tester', CURLOPT_SSL_VERIFYPEER => 1, CURLOPT_SSL_VERIFYHOST=> 0, CURLOPT_CAINFO => "../../cert/cacert.pem", CURLOPT_CAPATH => "../../cert/cacert.pem", CURLOPT_FOLLOWLOCATION => TRUE )); $resp = curl_exec($curl); curl_close($curl); if ($resp) { $json = json_decode($resp); if ($json) { echo("JSON decoded<br>"); $total = $json->pageInfo->totalResults; echo($total . " channels found.<br><br>"); $items = $json->items; foreach($items as $item) { $title = $item->snippet->title; $description = $item->snippet->description; $publishedAt = $item->snippet->publishedAt; $image = $item->snippet->thumbnails->high->url; $country = $item->snippet->country; $viewCount = $item->statistics->viewCount; $commentCount = $item->statistics->commentCount; $subscriberCount = $item->statistics->subscriberCount; $videoCount = $item->statistics->videoCount; echo("<img src=\"" . $image . "\" align=left>"); echo("Title :" . $title . "<br>"); echo("Description :" . $description . "<br>"); echo("Created on :" . $publishedAt . "<br>"); echo("Views:" . $viewCount . "<br>"); echo("Comments :" . $commentCount . "<br>"); echo("Subscribers:" . $subscriberCount . "<br>"); echo("Videos:" . $videoCount . "<br>"); echo("<hr>"); } } else exit("Error. could not parse JSON." . json_last_error_msg()); } // if resp ?>
Output:
JSON decoded
1 channels found.
Title :Amit Sengupta
Description :
Created on :2009-06-26T04:18:48.000Z
Views:70901
Comments :1
Subscribers:14
Videos:46
In the sample codes we are specifying all the parts possible. This is not normally needed and you should only use the required parts.
Leave a Reply