dariomory/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.
- 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** | GitHub https://github.com/dariomory
- Free software: MIT License
Install
Requires Node.js 18+ (uses the global fetch). Ships ESM and CommonJS with bundled type declarations.
Usage
Errors
Failed requests throw ResponseError, or TooManyRequestsError (a subclass) on HTTP 429.
Both carry .status and the raw .response.
Trending backends: RPC and RSS
Google exposes trending searches two ways. They are not interchangeable, so backend lets
you pick:
| | "rpc" (batchexecute) | "rss" (feed) |
|---|---|---|
| items | 50 | 10 |
| payload | ~2 KB JSON | ~21 KB XML |
| growth % and volume | ✅ | ❌ — buckets like "2000+" |
| news articles | ❌ | ✅ |
| window selection | ✅ | ignored by Google |
| worldwide | ✅ | ❌ country only |
"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.
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:
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