trendflow
It is an MCP server for querying Google Trends data programmatically.
search_topics — resolve a named entity to a Google Trends topic id (
mid) for better coverage.get_interest_over_time — get normalized historical search interest for 1-5 terms, compare trends over time.
get_interest_by_region — break down interest by country, region, or city.
get_related_queries — discover top and rising related searches for a keyword.
get_trending_now — list currently trending searches by country, with optional RSS news articles.
research_trend — combine interest over time, regional popularity, and related queries in one call.
Provides tools for querying and exporting Google Trends data, including interest over time, interest by region, trending searches, related queries, and topics/search suggestions.
This server has a remotely hosted endpoint. Open its connector listing for connection details, authentication requirements, and setup instructions:
Trendflow JS
A type-safe JavaScript/TypeScript library for querying and exporting Google Trends data.
The JavaScript port of trendflow-py.
📖 Documentation: trendflow.mory.dev/docs/js — guides for both libraries, plus a hosted MCP server for ChatGPT, Claude, and Cursor.
npm package: https://www.npmjs.com/package/trendflow
API reference: https://dariomory.github.io/trendflow-js/
Python sibling: https://pypi.org/project/trendflow-py/
Created by: Dario Mory | GitHub https://github.com/dariomory
Free software: MIT License
Install
npm install trendflowRequires Node.js 18+ (uses the global fetch). Ships ESM and CommonJS with bundled type declarations.
Related MCP server: Google Trends MCP Server
Usage
import { Client, Region, Timeframe, Resolution, SearchProperty, ExportFormat } from "trendflow";
// Initialize client (optional config)
const tf = new Client({ language: "en", timeout: 10_000 });
// --- Const objects for type safety ---
// Region.US, Region.GB, Region.DE ... (or any code: "US-CA", "807")
// Timeframe.PAST_HOUR ... PAST_5_YEARS, ALL_TIME (or "2023-01-01 2023-06-30")
// Resolution.COUNTRY, Resolution.REGION, Resolution.CITY
// SearchProperty.WEB, IMAGES, NEWS, YOUTUBE, SHOPPING
// Fetch interest over time
const data = await tf.interestOverTime(
["Python", "JavaScript", "Rust"],
Timeframe.PAST_YEAR,
Region.US,
);
console.log(data.keywords); // ["Python", "JavaScript", "Rust"]
console.log(data.granularity); // "weekly"
console.log(data.points); // TrendPoint[] — { date: Date, scores: Record<string, number> }
// Regional breakdown (region defaults to Region.US)
const regional = await tf.interestByRegion("Python", Resolution.COUNTRY);
for (const row of regional.rows) {
console.log(row.label, row.value);
}
// Trending searches right now (any country code, or omit for worldwide)
const trending = await tf.trendingNow(Region.US);
for (const item of trending.results) {
console.log(item.title, item.growth, item.volume, item.traffic);
// "fifa world cup 2026" 3650 6 "+3,650%"
}
// Related queries (region defaults to worldwide)
const related = await tf.relatedQueries("machine learning", { region: Region.GB });
for (const query of related.top) console.log(query.term, query.value);
for (const query of related.rising) console.log(query.term, query.breakout);
// --- Narrowing a query ---
// Every query method takes an optional category and search property, and any of them
// accepts a custom date range and a sub-region or metro code in place of the named values.
// "jaguar" the car, on YouTube, in California, over the first half of 2023
const jaguar = await tf.interestOverTime(["jaguar"], "2023-01-01 2023-06-30", "US-CA", {
category: 47, // Autos & Vehicles — disambiguates without needing a topic id
searchProperty: SearchProperty.YOUTUBE,
});
// --- Exports ---
data.toArray(); // [{ date: Date, Python: 80, ... }] — plain objects, the JS answer to DataFrames
data.toJSON(); // same rows with ISO 8601 date strings (also drives JSON.stringify)
data.toCSV(); // CSV text
// Node.js only — writes UTF-8 to disk
await data.export(ExportFormat.CSV, "trends.csv");
await data.export(ExportFormat.JSON, "trends.json");Errors
Failed requests throw ResponseError, or TooManyRequestsError (a subclass) on HTTP 429.
Both carry .status and the raw .response.
import { TooManyRequestsError } from "trendflow";
try {
await tf.interestOverTime(["Python"], Timeframe.PAST_YEAR, Region.US);
} catch (error) {
if (error instanceof TooManyRequestsError) {
// Google is rate-limiting this IP — back off and retry later.
}
}Trending backends: RPC and RSS
Google exposes trending searches two ways. They are not interchangeable, so backend lets
you pick:
|
| |
items | 50 | 10 |
payload | ~2 KB JSON | ~21 KB XML |
growth % and volume | ✅ | ❌ — buckets like |
news articles | ❌ | ✅ |
| ✅ | ignored by Google |
worldwide | ✅ | ❌ country only |
const rss = await tf.trendingNow(Region.US, { backend: "rss" });
rss.source; // "rss"
rss.results[0].articles;
// [{ title: "...", url: "https://...", source: "Buffalo News", picture: "https://..." }]"auto" (the default) tries the RPC and falls back to the feed. The RPC comes first
deliberately: it returns five times the items with real growth figures, so defaulting to RSS
would quietly degrade results. Reach for "rss" when you want the articles — that is the
one thing the RPC cannot give you — or as a second opinion if the RPC id ever goes stale.
Note that the feed is not a lighter path despite being a feed, and Google ignores hours,
sort and count on it: it always returns the same 10 entries.
Topics and search suggestions
Google distinguishes a search term (the literal string) from a topic (the entity, in
every spelling and language). suggestions() finds the topic; every query method already
accepts one — pass the mid where you would pass a keyword.
const topics = await tf.suggestions("artificial intelligence");
// [{ mid: "/m/0mkz", title: "Artificial intelligence", type: "Professional field" }]
const data = await tf.interestOverTime(
[topics[0].mid, "artificial intelligence"],
Timeframe.PAST_YEAR,
Region.US,
);
// { "/m/0mkz": 62, "artificial intelligence": 1 }That gap is the point: the topic scores 62 where the literal phrase scores 1, because it aggregates every phrasing and translation people actually search.
suggestions() needs no cookie and no proxy — it answers on IPs the widgetdata endpoints
reject with 429, same as trendingNow(). type disambiguates same-name entities
("Nike" returns both the company and the goddess) and is null when Google omits it.
Rate limits
Google Trends aggressively rate-limits datacenter and shared IPs, so 429 is common even on
your first request of the day. Two things matter:
User-Agent. Google returns
429to the default agent strings Node HTTP clients send, no matter how few requests you have made. This library sends a browser User-Agent by default for exactly that reason — if you overrideheaders, keep a realistic one.IP reputation. Once an IP is flagged, every request gets
429regardless of headers. Route through a residential proxy to recover.
Using a proxy pool
Pass a list of proxy URLs and the client rotates through them automatically, moving to the next one whenever a query is refused:
import { Client, Region, Timeframe } from "trendflow";
const tf = new Client({
proxies: [
"http://user:pass@gate.decodo.com:7000",
"http://user:pass@gate.decodo.com:7000",
],
maxProxyAttempts: 3, // defaults to the pool size, capped at 5
onProxyRotate: ({ attempt, error }) => console.warn(`rotated after ${attempt}:`, error),
});
const data = await tf.interestOverTime(["Python"], Timeframe.PAST_YEAR, Region.US);
console.log(tf.currentProxy); // the proxy that answeredProxy support needs undici, an optional peer
dependency — npm install undici. Entries are just URLs, so a pool can mix providers. Repeating one rotating gateway also works: each entry gets its own connection, so it lands on a fresh exit IP.
Rotation happens per query, not per request — this matters. Google binds the NID
cookie and the widget token to the IP that requested them, so a single query must complete
on one exit IP; sending the follow-up widgetdata call from a different IP earns an instant
429. The pool pins one proxy for the whole query and advances only on failure, re-seeding
the cookie jar each time. For the same reason, point the pool at sticky sessions rather
than per-request rotating endpoints if your provider offers the choice.
Rotation is skipped for errors a different IP cannot fix, such as a 404 or the
UnknownRpcError raised when Google renames a batchexecute RPC id.
Where to get proxies
Residential proxies are what actually clears Google's 429. Verified against this library:
Provider | Notes | Endpoint format |
Decodo (formerly Smartproxy) | Cheapest entry tier; pay-as-you-go available. Used to verify this library's live tests. |
|
const tf = new Client({
proxies: ["http://user:pass@gate.decodo.com:7000"],
});Ask for sticky sessions when you sign up — per-request rotating endpoints break the
cookie/token binding described above. Note that a shared residential pool can be exhausted
for Google Trends specifically, in which case even a valid proxy returns 429; that is what
maxProxyAttempts is for.
Bringing your own client
For logging, caching, or custom routing, pass a fetch instead (mutually exclusive with
proxies — the library will tell you if you pass both):
import { ProxyAgent, fetch as undiciFetch } from "undici";
const agent = new ProxyAgent("http://user:pass@proxy.example.com:7000");
const tf = new Client({
fetch: ((input, init = {}) =>
undiciFetch(input, { ...init, dispatcher: agent })) as typeof globalThis.fetch,
});Browser / Next.js
Every method except export() works anywhere fetch does, but Google Trends sends no CORS
headers — calls from browser JavaScript will be blocked. Use this library server-side
(Route Handlers, Server Actions, API routes) and pass results to the client.
MCP server
An MCP server ships alongside the library as trendflow-mcp, so agents can query
Google Trends directly. It's a separate package — the library keeps its zero runtime
dependencies.
claude mcp add trendflow -- npx -y trendflow-mcpSix tools (search_topics, get_interest_over_time, get_interest_by_region,
get_related_queries, get_trending_now, research_trend) and two resources. See
mcp/README.md.
Feature Parity
Current: trendflow-py 0.2.0 · trendflow 0.1.0. Versions are independent; each changelog cross-references the sibling release.
Feature | Python — | JS — |
Interest over time | ✅ | ✅ |
Interest by region | ✅ | ✅ |
Trending now | ✅ | ✅ |
Trending growth % and volume | ✅ | ✅ |
Trending for any country code | ✅ | ✅ |
Trending news articles (RSS) | ✅ | ✅ |
Selectable trending backend | ✅ | ✅ |
Related queries | ✅ | ✅ |
Search suggestions | ✅ | ✅ |
Query by topic (entity mid) | ✅ | ✅ |
CSV / JSON export | ✅ | ✅ |
Rotating proxy pool | ✅ | ✅ |
Browser User-Agent by default | ✅ | ✅ |
Full geo hierarchy | ✅ | ✅ |
Overridable RPC ids | ✅ | ✅ |
pandas DataFrame | ✅ | ❌ N/A |
Plain-object rows | ❌ N/A | ✅ |
ESM + CommonJS + types | ❌ N/A | ✅ |
MCP server | 🔜 planned | |
CLI | ✅ | 🔜 planned |
Trending now
Google retired the hottrends/visualize/internal/data endpoint, along with
api/dailytrends and api/realtimetrends; all three now return HTTP 404. This library
calls the batchexecute RPC that trends.google.com itself uses instead — as does
trendflow-py from 0.2.0 — and it returns more
than the old endpoint did:
const trending = await tf.trendingNow(Region.US);
// { title: "fifa world cup 2026", growth: 3650, volume: 6, traffic: "+3,650%", articles: [] }Three practical wins over the old endpoint:
Growth and volume, not just titles.
growthis the percentage rise over the window,volumea relative search-volume index.Any country code, not the 16 hardcoded names the old endpoint required — and worldwide works, which it previously refused.
No cookie, and far looser rate limiting. This RPC answers on IPs that get a
429from the widgetdata endpoints, sotrendingNow()often works with no proxy at all.
articles is empty on this backend — the RPC carries no article links. Pass
{ backend: "rss" } to get the news articles behind each trend instead.
The window is selectable via TrendingWindow:
import { TrendingWindow } from "trendflow";
await tf.trendingNow(Region.US, { window: TrendingWindow.RISING }); // default: fastest-growing
await tf.trendingNow(Region.US, { window: TrendingWindow.TOP }); // highest-volumewindow is an undocumented Google parameter. Only these two values have behaviour worth
naming; other integers between 4 and 12 also return data over varying recency windows, and
you can pass one as a raw number.
Not implemented: captcha-gated RPCs
The same batchexecute endpoint exposes a higher-precision timeseries (floating-point
values rather than the rounded 0-100 the public API returns) and keyword-scoped related
queries. Both require a reCAPTCHA Enterprise token and return an empty payload without one,
so this library does not implement them — that data remains available through
interestOverTime() and relatedQueries(), which use the documented widgetdata endpoints.
API mapping
Python | JavaScript |
|
|
|
|
|
|
|
|
|
|
|
|
Notable differences:
Everything is async. All four query methods return promises.
timeoutis milliseconds (JS convention), not seconds.Enums are
as constobjects, soRegion.USis the string"US"and any valid string literal is accepted where the type is expected.Results are plain typed objects. Only
InterestOverTimeResultis a class, because it carries the conversion methods; the rest are interfaces.
Development
git clone git@github.com:dariomory/trendflow-js.git
cd trendflow-js
npm install
npm test # vitest — 60 tests, fully offline against a stubbed fetch
npm run qa # typecheck + test + buildThe unit tests never touch the network. To check the real endpoints:
npm run build && npm run smoke
TRENDFLOW_PROXY_URL=http://user:pass@host:7000 npm run smoke # via a proxyAuthor
Trendflow JS was created in 2026 by Dario Mory.
Available Tools
6 toolsget_interest_by_regionInterest by regionAInspect
Break down search interest for one term by geography. Use this when the user asks where something is popular, or wants a regional or city-level comparison. Values are Google's normalized relative interest (0-100 within the result set), not absolute search volume.
Inputs: keyword (required), region, resolution.
get_interest_over_timeInterest over timeAInspect
Get relative search interest for one or more terms over a historical period. Use this when the user asks how popular something is, whether it is rising or falling, or how several things compare — passing multiple keywords compares them against each other on one scale. Values are Google's normalized relative interest (0-100 within the result set), not absolute search volume.
Inputs: keywords (required), region, timeframe.
get_trending_nowTrending nowAInspect
List searches surging right now in a country. Use this for discovery — what is spiking without the user naming a term — and for news, monitoring, and real-time questions. Choose backend "rss" when the user wants to know why something is trending: it returns the news articles behind each entry, which the default source does not carry.
Inputs: limit, region, backend.
research_trendResearch a trendAInspect
Full picture of one term in a single call: interest over time, where it is popular, and what people search alongside it. Use this when the user asks to "research", "analyse", or "look into" a topic rather than asking one narrow question — it saves three round trips.
Each section is fetched independently, so a partial result is normal: any section that fails carries an error instead of data, and the rest still returns. Pass a topic id from search_topics for materially better numbers.
Inputs: keyword (required), region.
search_topicsSearch topicsAInspect
Look up the Google Trends topic id for a thing. Call this FIRST whenever the user names an entity — a company, product, person, technology, concept — then pass the returned mid as a keyword to the other tools.
A topic aggregates every spelling and translation of the same concept, so it measures far more search activity than the literal phrase: querying the topic for "artificial intelligence" scores 62 where the literal string scores 1. The type field disambiguates same-name entities (Nike the company vs the goddess). Skip this only when the user explicitly wants a literal phrase.
Cheapest tool here: it needs no cookie and works on IPs that rate-limit the others.
Inputs: query (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a clearly distinct purpose: topic lookup, time-series interest, regional breakdown, related queries, trending searches, and a combined research call. The only potential overlap is research_trend, but its description explicitly frames it as a convenience wrapper, reducing ambiguity.
Most tools follow a consistent verb_noun snake_case pattern, such as search_topics and get_interest_over_time. research_trend deviates slightly from the get_ prefix pattern, but still fits the overall verb_noun style.
Six tools is a well-scoped set for a Google Trends server. Each tool covers a distinct aspect of the domain without redundant or unnecessary additions.
The surface covers the core Google Trends workflow: resolving topics, measuring interest over time and by region, exploring related queries, checking current trending searches, and a combined research endpoint. No obvious missing functionality for the stated purpose.
Maintenance
Related MCP Connectors
Google Trends interest over time and by region, related queries and topics, and Trending Now.
Google Trends interest over time, by region, related queries, plus Trending Now.
Google Trends interest over time and by region, rising queries and trending searches.
Google Trends data via Apify: interest over time, by region, related queries and Trending Now.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables retrieval and analysis of Google Trends data for any search term over the last 12 months. Provides structured timeline data with relative interest scores that can be filtered by geography and category.-
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to access Google Trends data for comparing keywords, discovering trending searches, and analyzing regional interest through natural language.2MIT
- AlicenseBqualityDmaintenanceEnables Claude to query Google Trends data such as keyword interest, related queries, and regional popularity, with robust proxy rotation to bypass Google's anti-bot measures.5108 npm1MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to query Google Trends data, including search interest over time, regional breakdowns, trending searches, and keyword ideas.MIT