get_trending_terms
Fetch trending search terms for a specific geo location using Google Trends. Analyze popular keywords and trends to gain insights into current topics and regional interests.
Instructions
Returns google trends for a specific geo location.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| full_data | No | Return full data for each trend. Should be False for most use cases. | |
| geo | No | Country code, e.g. 'US', 'GB', 'IN', etc. | US |
Implementation Reference
- MCP tool handler implementation for 'get_trending_terms'. It accepts geo and full_data parameters, fetches trends from the news module, and formats the output using Pydantic models TrendingTermOut and TrendingTermArticleOut.@mcp.tool(description=news.get_trending_terms.__doc__, tags={"trends", "google", "trending"}) async def get_trending_terms( geo: Annotated[str, Field(description="Country code, e.g. 'US', 'GB', 'IN', etc.")] = "US", full_data: Annotated[ bool, Field(description="Return full data for each trend. Should be False for most use cases."), ] = False, ) -> list[TrendingTermOut]: if not full_data: trends = await news.get_trending_terms(geo=geo, full_data=False) return [TrendingTermOut(keyword=str(tt["keyword"]), volume=tt["volume"]) for tt in trends] trends = await news.get_trending_terms(geo=geo, full_data=True) trends_out = [] for trend in trends: trend = trend.__dict__ if "news" in trend: trend["news"] = [TrendingTermArticleOut(**article.__dict__) for article in trend["news"]] trends_out.append(TrendingTermOut(**trend)) return trends_out
- Pydantic output model for a trending term, used by the handler to serialize results.class TrendingTermOut(BaseModelClean): keyword: Annotated[str, Field(description="Trending keyword.")] volume: Annotated[Optional[str], Field(description="Search volume.")] = None trend_keywords: Annotated[Optional[list[str]], Field(description="Related keywords.")] = None link: Annotated[Optional[str], Field(description="URL to more information.")] = None started: Annotated[Optional[int], Field(description="Unix timestamp when the trend started.")] = None picture: Annotated[Optional[str], Field(description="URL to related image.")] = None picture_source: Annotated[Optional[str], Field(description="Source of the picture.")] = None news: Annotated[ Optional[list[TrendingTermArticleOut]], Field(description="Related news articles."), ] = None
- Pydantic model for news articles associated with trending terms.class TrendingTermArticleOut(BaseModelClean): title: Annotated[str, Field(description="Article title.")] = "" url: Annotated[str, Field(description="Article URL.")] = "" source: Annotated[Optional[str], Field(description="News source name.")] = None picture: Annotated[Optional[str], Field(description="URL to article image.")] = None time: Annotated[Optional[str | int], Field(description="Publication time or timestamp.")] = None snippet: Annotated[Optional[str], Field(description="Article preview text.")] = None
- Core helper function that fetches trending terms using trendspy.Trends().trending_now_by_rss(), sorts by volume, and returns simple dicts or full TrendKeywordLite objects based on full_data.@overload async def get_trending_terms(geo: str = "US", full_data: Literal[False] = False) -> list[dict[str, str]]: ... @overload async def get_trending_terms(geo: str = "US", full_data: Literal[True] = True) -> list[TrendKeywordLite]: ... async def get_trending_terms(geo: str = "US", full_data: bool = False) -> list[dict[str, str]] | list[TrendKeywordLite]: """ Returns google trends for a specific geo location. """ try: trends = cast(list[TrendKeywordLite], tr.trending_now_by_rss(geo=geo)) trends = sorted(trends, key=lambda tt: int(tt.volume[:-1]), reverse=True) if not full_data: return [{"keyword": trend.keyword, "volume": trend.volume} for trend in trends] return trends except Exception as e: logger.warning(f"Error fetching trending terms: {e}") return []