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

src/google_news_trends_mcp/server.py:297-315 (handler)

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

src/google_news_trends_mcp/server.py:64-76 (schema)

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

src/google_news_trends_mcp/server.py:55-62 (schema)

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

src/google_news_trends_mcp/news.py:280-301 (helper)

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 []

google-news-trends-mcp