31 – YouTube Data API – Guide Categories – list function

This is article 31 of the YouTube API With PHP series.

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

This is not to be confused with the Video categories list. If you want a list of available Video Categories, then you should check the Video Categories resource. The Guide Category will only return recommended categories. In some cases, there may not be any Guide Categories.

Every guide category has a Channel associated with it. These Channels are created by Youtube and are not user-created.

The following function is available.


Returns a list of categories that can be associated with YouTube channels.

The Request URL is

GET https://www.googleapis.com/youtube/v3/guideCategories


  • key (string) required. Your API key
  • part (string). Required. Only this value is valid:
    • “snippet”
  • Filters (string) required. One of the following:
    • id (string) This specifies a comma-separated list of video category IDs for the resources that you are retrieving.
    • regionCode (string) This instructs the API to return the list of guide categories available in the specified country. The parameter value is a two letter country code.
  • hl (string) optional. The hl parameter specifies the language that will be used for text values in the API response. The default value is en-US.


Example Requests

Get guide categories for a particular country



Get guide categories for a Channel category




A successful API call will return an array of GuideCategory resources encoded in json:

  "kind": "youtube#guideCategoryListResponse",
  "etag": etag,
  "nextPageToken": string,
  "prevPageToken": string,
  "pageInfo": {
            "totalResults": integer,
            "resultsPerPage": integer
  "items": [
            (guideCategory resource)


The Response components are explained below:

  • kind (string) “youtube#guideCategoryListResponse”
  • etag (string) See ETags Explained section
  • 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 GuideCategory Resource items returned

The JSON structure of a GuideCategory Resource is shown below:

  "kind": "youtube#guideCategory",
  "etag": etag,
  "id": string,
  "snippet": {
     "channelId": "UCBR8-60-B28hp2BmDPdntcQ",
     "title": string


An explanation of the various fields are given below:

  • kind (string) This value is always “youtube#guideCategory”
  • etag (string) See ETags Explained section
  • id (string) The ID that YouTube uses to uniquely identify the guide category.
  • channelId (string) The ID that YouTube uses to uniquely identify the channel publishing the guide category.
  • title (string) The category’s title.


Sample code to get all the guideCategories for a country:

    error_reporting(E_ALL ^ E_NOTICE ^ E_WARNING ^ E_DEPRECATED);
    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");

   	 $accessToken = $_SESSION["access_token"];

   	 // make api request
   	 $url = "https://www.googleapis.com/youtube/v3/guideCategories?key=" . $g_youtubeDataAPIKey .

   	 $curl = curl_init();
   	 curl_setopt_array($curl, array(
   				 CURLOPT_URL => $url,
   				 CURLOPT_USERAGENT => 'YouTube API Tester',
   				 CURLOPT_CAINFO => "../../cert/cacert.pem",
   				 CURLOPT_CAPATH => "../../cert/cacert.pem",
   	 $resp = curl_exec($curl);

   	 if ($resp) {
   		 $json = json_decode($resp);
   		 if ($json) {
   			 echo("JSON decoded<br>");
   			 $total = $json->pageInfo->totalResults;
   			 echo($total . " categories found.<br><br>");
   			 $items = $json->items;

   			 foreach($items as $item) {
   				 $id = $item->id;
   				 $channelId = $item->snippet->channelId;
   				 $title = $item->snippet->title;

   				 echo("id :" . $id . " Channel id: " . $channelId . "<br>");
   				 echo($title . "<hr>");
   			 exit("Error. could not parse JSON." . json_last_error_msg());

   	 } // if resp

Here is the Output:

JSON decoded
id :GCQmVzdCvZiBZb3VUdWJl Channel id: UCBR8-60-B28hp2BmDPdntcQ
Best of YouTube
id :GCQ3JlYXRvciBvbiB0aGUgUmlzZQ Channel id: UCBR8-60-B28hp2BmDPdntcQ
Creator on the Rise
id :GCTXVzaWM Channel id: UCBR8-60-B28hp2BmDPdntcQ
id :GCQ29tZWR5 Channel id: UCBR8-60-B28hp2BmDPdntcQ
id :GCRmlsbSAmIEVudGVydGFpbm1lbnQ Channel id: UCBR8-60-B28hp2BmDPdntcQ
Film & Entertainment
id :GCR2FtaW5n Channel id: UCBR8-60-B28hp2BmDPdntcQ
id :GCQmVhdXR5ICYgRmFzaGlvbg Channel id: UCBR8-60-B28hp2BmDPdntcQ
Beauty & Fashion
id :GCU3BvcnRz Channel id: UCBR8-60-B28hp2BmDPdntcQ
id :GCVGVjaA Channel id: UCBR8-60-B28hp2BmDPdntcQ
id :GCQ29va2luZyAmIEhlYWx0aA Channel id: UCBR8-60-B28hp2BmDPdntcQ
Cooking & Health
id :GCTmV3cyAmIFBvbGl0aWNz Channel id: UCBR8-60-B28hp2BmDPdntcQ
News & Politics

Be the first to comment

Leave a Reply

Your email address will not be published.