getTrendingVideos
Discover popular videos by region and category using YouTube Data API v3. Filter trending content with country codes and category IDs to find what's currently popular in specific areas.
Instructions
Retrieves trending videos based on region and category. Returns a list of videos that are currently popular in the specified region and category. Use this when you want to discover what's trending in specific areas or categories. To get available category IDs and their names, use the getVideoCategories tool first.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| categoryId | No | YouTube category ID to filter trending videos by category. Use getVideoCategories tool to get available category IDs. | |
| maxResults | No | Maximum number of trending videos to return (1-500, default: 10) | |
| regionCode | No | Two-letter country code (e.g., 'US', 'GB', 'JP'). Defaults to 'US' | US |
Implementation Reference
- The primary handler function for the 'getTrendingVideos' tool. It validates the input parameters using Zod schema, calls the YoutubeService to fetch trending videos, formats the success response, or handles errors.export const getTrendingVideosHandler = async ( params: TrendingParams, youtubeService: YoutubeService ): Promise<CallToolResult> => { try { const validatedParams = getTrendingVideosSchema.parse(params); const trendingVideos = await youtubeService.getTrendingVideos(validatedParams); return formatSuccess(trendingVideos); } catch (error: unknown) { return formatError(error); } };
- Zod schema defining the input parameters for the getTrendingVideos tool: regionCode (default 'US'), optional categoryId, maxResults (default 10).export const getTrendingVideosSchema = z.object({ regionCode: regionCodeSchema .default("US") .describe( "Two-letter country code (e.g., 'US', 'GB', 'JP'). Defaults to 'US'" ), categoryId: categoryIdSchema.describe( "YouTube category ID to filter trending videos by category. Use getVideoCategories tool to get available category IDs." ), // categoryId is optional and has no default maxResults: maxResultsSchema .default(10) .describe( "Maximum number of trending videos to return (1-500, default: 10)" ), });
- src/tools/index.ts:123-130 (registration)Registration of the getTrendingVideos tool in the allTools function, providing its config and a wrapped handler that injects the youtubeService dependency.{ config: getTrendingVideosConfig, handler: (params) => getTrendingVideosHandler( params as unknown as TrendingParams, youtubeService ), },
- Core implementation in YoutubeService that fetches trending videos using YouTube Data API v3 videos.list with chart='mostPopular', processes statistics, calculates ratios, and handles caching.async getTrendingVideos( options: TrendingOptions ): Promise<LeanTrendingVideo[]> { const cacheKey = this.cacheService.createOperationKey( "getTrendingVideos", options ); const operation = async (): Promise<LeanTrendingVideo[]> => { try { const { regionCode = "US", categoryId, maxResults = 10 } = options; const params: youtube_v3.Params$Resource$Videos$List = { part: ["snippet", "statistics", "contentDetails"], chart: "mostPopular", regionCode: regionCode, maxResults: maxResults, }; if (categoryId) { params.videoCategoryId = categoryId; } const response = await this.trackCost( () => this.youtube.videos.list(params), API_COSTS["videos.list"] ); return ( response.data.items?.map((video) => { const viewCount = parseYouTubeNumber(video.statistics?.viewCount); const likeCount = parseYouTubeNumber(video.statistics?.likeCount); const commentCount = parseYouTubeNumber( video.statistics?.commentCount ); return { id: video.id, title: video.snippet?.title, channelId: video.snippet?.channelId, channelTitle: video.snippet?.channelTitle, publishedAt: video.snippet?.publishedAt, duration: video.contentDetails?.duration, viewCount: viewCount, likeCount: likeCount, commentCount: commentCount, likeToViewRatio: calculateLikeToViewRatio(viewCount, likeCount), commentToViewRatio: calculateCommentToViewRatio( viewCount, commentCount ), }; }) || [] ); } catch (error) { throw new YouTubeApiError( `YouTube API call for getTrendingVideos failed`, error ); } }; return this.cacheService.getOrSet( cacheKey, operation, CACHE_TTLS.DYNAMIC, CACHE_COLLECTIONS.TRENDING_VIDEOS, options ); }