getVideoCategories

Retrieve YouTube video categories for a specific region to filter trending videos and perform category-specific operations. Supports two-letter country codes for regional category variations.

Instructions

Retrieves available video categories for a specific region. Returns a list of YouTube video categories with their IDs and titles that can be used for filtering trending videos or other category-specific operations. Different regions may have different available categories.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`regionCode`	No	Two-letter country code (e.g., 'US', 'GB', 'JP'). Defaults to 'US'	US

Implementation Reference

src/tools/general/getVideoCategories.ts:24-37 (handler)

The getVideoCategoriesHandler function implements the core logic of the tool by parsing input parameters and calling the YouTube service to fetch video categories.

export const getVideoCategoriesHandler = async (
  params: VideoCategoriesParams,
  youtubeService: YoutubeService
): Promise<CallToolResult> => {
  try {
    const validatedParams = getVideoCategoriesSchema.parse(params);
    const { regionCode } = validatedParams;

    const categories = await youtubeService.getVideoCategories(regionCode);
    return formatSuccess(categories);
  } catch (error: unknown) {
    return formatError(error);
  }
};

src/tools/general/getVideoCategories.ts:9-15 (schema)

Zod schema for validating the input parameters (regionCode) of the getVideoCategories tool.

export const getVideoCategoriesSchema = z.object({
  regionCode: regionCodeSchema
    .default("US")
    .describe(
      "Two-letter country code (e.g., 'US', 'GB', 'JP'). Defaults to 'US'"
    ),
});

src/tools/index.ts:131-138 (registration)
Registration of the getVideoCategories tool within the allTools function, including config and a wrapped handler that injects the youtubeService dependency.
```
{
  config: getVideoCategoriesConfig,
  handler: (params) =>
    getVideoCategoriesHandler(
      params as unknown as VideoCategoriesParams,
      youtubeService
    ),
},
```

src/services/youtube.service.ts:738-778 (helper)

The YoutubeService.getVideoCategories method implements the YouTube API interaction to list video categories for a region, including caching and error handling. This is called by the tool handler.

async getVideoCategories(regionCode: string = "US") {
  const cacheKey = this.cacheService.createOperationKey(
    "getVideoCategories",
    {
      regionCode,
    }
  );

  const operation = async () => {
    try {
      const response = await this.trackCost(
        () =>
          this.youtube.videoCategories.list({
            part: ["snippet"],
            regionCode: regionCode,
          }),
        API_COSTS["videoCategories.list"]
      );

      const categories = response.data.items?.map((category) => ({
        id: category.id,
        title: category.snippet?.title,
      }));

      return categories || [];
    } catch (error) {
      throw new YouTubeApiError(
        `YouTube API call for getVideoCategories failed for regionCode: ${regionCode}`,
        error
      );
    }
  };

  return this.cacheService.getOrSet(
    cacheKey,
    operation,
    CACHE_TTLS.STATIC,
    CACHE_COLLECTIONS.VIDEO_CATEGORIES,
    { regionCode }
  );
}

mcp-youtube