TrendFlow

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](https://trendflow.mory.dev/docs/js) — guides for both libraries, plus a hosted MCP server for ChatGPT, Claude, and Cursor.

• GitHub: https://github.com/dariomory/trendflow-js/
• 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](https://mory.dev) | GitHub https://github.com/dariomory
• Free software: MIT License

Install

npm install trendflow

Requires Node.js 18+ (uses the global fetch). Ships ESM and CommonJS with bundled type declarations.

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 }

// 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:

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:

1. User-Agent. Google returns 429 to 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 override headers, keep a realistic one.
2. IP reputation. Once an IP is flagged, every request gets 429 regardless 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 answered

Proxy 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:

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-mcp

Six 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.