Developer guide · Trending Now · 2026
How to get Google Trends data in Node.js without an API key
The official Google Trends API, announced in July 2025, is still an alpha you have to apply for, so most teams end up running an unofficial client instead. google-trends-scraper is one: it fetches the Trending Now page, reads the trend rows Google inlines into that HTML, and returns them as typed objects — what is spiking in one region, how much it grew, and whether it is still running. This page documents the 0.2.x request flow, the options, the numbers you should not misread, and the older snippet that no longer works.
$ pnpm add google-trends-scraperNode 22.13+
Needs a global fetch and AbortSignal, nothing else
0 dependencies
ESM and CJS builds with bundled types
125 regions
Country list returned by the package on 18 Nov 2026
4h / 24h / 48h / 7d
The four Trending Now windows the board supports
The whole integration, in one function call
fetchTrendingNow is the only call you need for the board itself. The returned object echoes the options that actually took effect, so you never have to guess which default was applied.
import { fetchTrendingNow } from 'google-trends-scraper';
const result = await fetchTrendingNow({
geo: 'SG', // two-letter region, upper-cased for you
hours: 24, // 4, 24, 48 or 168
status: 'active',
sort: 'volume',
limit: 10,
});
console.log(result.geo, result.total, '→', result.items.length);
for (const item of result.items) {
console.log(item.rank, item.query, item.searchVolume, item.increasePercentage + '%');
}Listing the markets you can request is a second call, not a hard-coded array. The country list comes from a different internal endpoint and returns top-level regions only — no states, no provinces, no “your location” entry.
import { fetchCountries, fetchTrendingNow } from 'google-trends-scraper';
const countries = await fetchCountries({ hl: 'en' });
// [{ geo: 'AL', name: 'Albania' }, …, { geo: 'ZW', name: 'Zimbabwe' }]
// 125 top-level regions on 18 Nov 2026; states and provinces are excluded.
const hasKenya = countries.some((country) => country.geo === 'KE');
const nairobi = hasKenya ? await fetchTrendingNow({ geo: 'KE', hours: 24 }) : null;Pick the route that matches the data you actually need
“Get Google Trends data” means at least four different jobs, and the access route changes with each one. Deciding this first saves you from installing a trending-searches client when what you wanted was a five-year interest curve.
| What you need | Where it comes from | Access | Automatable |
|---|---|---|---|
| A one-off chart or CSV for a report | The Trends interface, then the download button | None | No |
| Interest over time, interest by region, related queries | The Explore section, or the official alpha API if you are accepted | Application for the API | Partly |
| The Trending Now board, on a schedule | This package: it reads the board Google inlines into the Trending Now page | None | Yes |
| Explore datasets at scale without maintaining a client | A hosted scraping vendor with its own proxy pool | Paid key | Yes |
One thing is missing from every row: absolute search volume. Google Trends does not publish a count of searches anywhere — not in the interface, not in the export, not in this package. Everything you read here is relative interest, a bucket floor, or a growth ratio.
Why the snippet in older tutorials returns nothing
If you are here because a working script stopped working, this is the reason. Earlier releases of this package — and most tutorials written around them — posted to Google’s internal batchexecute endpoint with the RPC id i0OFE. That call still answers with HTTP 200, which is what makes the failure confusing: the payload is simply null.
POST /_/TrendsUi/data/batchexecute?rpcids=i0OFE&source-path=%2Ftrending&hl=en HTTP/1.1
Host: trends.google.com
origin: https://trends.google.com
referer: https://trends.google.com/trending
f.req=[[["i0OFE","[null,null,\"SG\",0,\"en\",24,1]",null,"generic"]]]
HTTP/1.1 200 OK
)]}'
[["wrb.fr","i0OFE",null,null,null,[7],"generic"],["di",11],["af.httprm",10,"-5597701052979708537",135]]Read the frame from the left: wrb.fr is the envelope, the third element is the payload and it is null, and the [7] that follows is the status the page uses for a failed call. There are no rows to map, and no amount of retrying brings them back — the board moved.
Version 0.2.0 follows it. Instead of asking an RPC for the board, it requests the Trending Now page itself and reads the copy of the board that Google embeds in the markup for its own front end:
GET /trending?geo=SG&hl=en&hours=24 HTTP/1.1
Host: trends.google.com
accept: text/html
user-agent: Mozilla/5.0
<script class="ds:0">AF_initDataCallback({
key: 'ds:0',
hash: '2',
data: [null, [["argentina vs costa rica", null, "SG", [1794954600], null, null,
10000, null, 1000, ["argentina vs costa rica"], [17],
[[4928347159, "es", "SG"], [4943139614, "es", "SG"]],
"argentina vs costa rica"], /* …59 more rows… */]]
});</script>Those bytes are real, from a request made on 18 November 2026, trimmed to the first row of the Singapore 24-hour board. The full response is about 1.3 MB; the useful part is this one script tag.
Migrating from 0.1.x is a version bump
The option names, the result envelope and every item field are unchanged, so the call you already wrote keeps working once the dependency is updated. The one behavioural difference: category, status, sort and limit are now applied locally after the fetch, and the request to Google carries only geo, hl and hours.
What happens between the call and the array
Five stages, in order. Knowing them explains every option, every error code and every limit further down this page.
01Validate and normalise the options
The country code is checked against a two-letter pattern and upper-cased, the language tag is canonicalised with Intl.getCanonicalLocales, hours must be one of 4, 24, 48 or 168, and limit must be a non-negative integer or "all". A bad argument throws INVALID_ARGUMENT before anything touches the network.
02Request the Trending Now page
One GET per call to trends.google.com/trending with three query parameters — geo, hl and hours — plus an accept: text/html header and a plain user-agent. That is the whole request: no cookies, no session bootstrap, no key.
03Stream the HTML until the board appears
The response is roughly 1.3 MB of markup, and the board is at the very end of it: when we measured, the ds:0 script started at 98.6% of the document. That is exactly why the reader streams instead of buffering — it walks the response, keeps only the target script, discards everything else, and cancels the body once the callback is complete.
04Read the callback without running any JavaScript
The board is an AF_initDataCallback call with a key, a data value and an isError flag. The parser walks those properties, bracket-matches the data value (honouring string quoting and escapes), confirms the key is ds:0 and isError is not true, then parses the JSON. The page’s own scripts are never executed.
05Map rows, then filter, sort and truncate locally
Each row is a 13-field positional array, so every field is read by index and validated; seconds become milliseconds, a null end time becomes active: true, and rank is renumbered from 1 after your filters and limit are applied.
Why not drive a headless browser?
Because the data is already text. The rows arrive in the same response as the page, so a browser adds a few hundred megabytes of runtime, a platform-specific binary and a whole class of flakiness in exchange for nothing. Streaming the HTML and parsing one callback keeps a run in kilobytes and makes failure legible: an unexpected shape raises INVALID_RESPONSE instead of quietly returning an empty board, which is the failure mode that hides a broken pipeline for weeks.
Every option, and its default
Ten options, all optional. Defaults are applied before the request, so fetchTrendingNow() with no arguments is a valid call: Singapore, English, the 24-hour board, first 25 rows.
| Option | Type | Default | Notes |
|---|---|---|---|
| geo | string | 'SG' | Two-letter country or region code, upper-cased. The list of markets is fetched, not hard-coded: 125 regions came back on 18 Nov 2026. |
| hl | string | 'en' | Interface language for the returned names. zh-cn is canonicalised to zh-CN, and title sorting follows this locale. |
| hours | 4 | 24 | 48 | 168 | 24 | Which window of the board to read. Anything outside these four values is rejected. |
| category | number | 0 | Category id to keep, matched against each row’s categoryIds. 0 means every category. Applied locally. |
| status | 'all' | 'active' | 'ended' | 'all' | active keeps trends with no end time, ended keeps the rest. Applied locally. |
| sort | 'relevance' | 'volume' | 'recency' | 'title' | 'relevance' | relevance keeps the order Google returned; the other three sort locally by bucket floor, start time or title. |
| limit | number | 'all' | 25 | Applied after filtering. all keeps every row the source already returned — there is no pagination behind it. |
| timeoutMs | number | 30000 | Covers the request and the body read. Must be an integer between 1 and 2147483647. |
| signal | AbortSignal | — | Your own cancellation, for shutdown or for letting a newer run replace an older one. Rejects with ABORTED. |
| fetch | typeof fetch | globalThis.fetch | Injection point for a proxy-aware client, a logging wrapper or a test double. |
What comes back, field by field
One envelope, then an array of items. Here is the same call’s output, trimmed to a single row, taken from the live board rather than a fixture.
{
"geo": "SG",
"hl": "en",
"hours": 24,
"category": 0,
"status": "all",
"sort": "relevance",
"total": 60,
"filteredTotal": 60,
"items": [
{
"rank": 1,
"rawRank": 1,
"query": "argentina vs costa rica",
"normalizedQuery": "argentina vs costa rica",
"searchVolume": 10000,
"increasePercentage": 1000,
"startedAtMs": 1794954600000,
"endedAtMs": null,
"active": true,
"trendBreakdown": ["argentina vs costa rica"],
"categoryIds": [17],
"newsReferences": [{ "id": 4928347159, "language": "es", "geo": "SG" }]
}
]
}The envelope
- geo / hl / hours—The values that actually took effect, so defaults are never a guess.
- category / status / sort—Echoed back after normalisation, including limit: "all".
- total—How many rows the board returned this time — 60 for Singapore on the 24-hour window when we checked.
- filteredTotal—How many rows survived your category and status filters, before the limit was applied.
- items—The trimmed, renumbered array you actually iterate over.
Each item
- rank / rawRank—rank is the position in this output; rawRank is the position on the source board.
- query / normalizedQuery—The display query, and the cleaned form to use as a dedupe key.
- searchVolume—A bucket floor, not a count: the value 10000 is what the board renders as 10K+. The RSS writes the same floor as 10000+.
- increasePercentage—The growth figure the board reports, passed through untouched.
- startedAtMs / endedAtMs / active—Unix milliseconds. endedAtMs null becomes active: true, which is what the status filter reads.
- trendBreakdown—The related terms the board groups under the same trend.
- categoryIds—Numeric ids such as 17 for sports, matched by the category option.
- newsReferences—id plus language and country of the articles behind a trend. The source does not send usable links, so neither does the package.
Reading the volume tiers
The board publishes a floor per trend, and the floors are not evenly spaced. These are the tiers we saw across two live boards on 18 November 2026, with the honest use of each:
- 100+ / 200+The long tail. Useful for topic ideas, useless for prioritising.
- 500+ / 1K+A normal day’s mid-size spike in a mid-size market.
- 2K+ / 5K+ / 10K+What most “trending now” tutorials screenshot. Still a floor, not a count.
- 100K+ / 200K+ / 1M+National or global moments. Expect news and sport to dominate these rows.
Two consequences worth designing around. First, ties are normal: sorting by volume groups every row that shares a floor, and the order inside a bucket is not meaningful. Second, buckets are not traffic — a 10M+ row in a country of five million people is not ten million searches, it is the top step of a relative scale.
Five patterns worth copying
The package does one thing on purpose: fetch one board. Everything below is what people build on top of it, with the failure handling included rather than left as an exercise.
A daily content brief
Keep only trends that are still running, rank them by the volume tier, and turn them into headlines with the growth figure and start time attached.
import { fetchTrendingNow } from 'google-trends-scraper';
// One market, only trends that are still running, biggest bucket first.
const { items, geo, hours } = await fetchTrendingNow({
geo: 'US',
hours: 24,
status: 'active',
sort: 'volume',
limit: 10,
});
const brief = items.map((item) => ({
headline: item.query,
growth: item.increasePercentage + '%',
tier: item.searchVolume + '+',
startedAt: new Date(item.startedAtMs).toISOString(),
}));
console.log(`${items.length} live trends in ${geo} over the last ${hours}h`, brief);Sweep several markets in one job
Each region is its own request, so loop deliberately and leave a gap between calls. Nothing in the package rotates proxies or spaces requests for you.
const MARKETS = ['US', 'GB', 'SG', 'JP', 'KE'];
// One request per market, run sequentially. There is no pagination to loop over,
// and no retry inside the package, so pace the calls yourself.
for (const geo of MARKETS) {
const { items } = await fetchTrendingNow({ geo, hours: 24, limit: 10 });
console.log(geo, items.map((item) => item.normalizedQuery));
await new Promise((resolve) => setTimeout(resolve, 1000));
}Alert only on genuinely new trends
Polling a short window repeats itself: the same spike sits on the board for hours. Remember what you have already reported and diff against it, keyed on normalizedQuery so punctuation and casing changes do not create phantom alerts.
const seen = new Map<string, number>(); // normalizedQuery -> first seen (ms)
const TTL_MS = 7 * 24 * 60 * 60 * 1000;
/** Trends this process has not reported before, so an hourly poll stays quiet. */
async function pollOnce(geo: string) {
const { items } = await fetchTrendingNow({ geo, hours: 4, limit: 'all' });
const now = Date.now();
const fresh = items.filter((item) => !seen.has(item.normalizedQuery));
for (const item of fresh) seen.set(item.normalizedQuery, now);
for (const [query, firstSeen] of seen) {
if (now - firstSeen > TTL_MS) seen.delete(query);
}
return fresh;
}One retry, and only when it makes sense
The package deliberately never retries. When Google throttles you, honour retryAfter and try once more; when the payload shape changed, retrying is pointless.
import {
GoogleTrendsError,
GoogleTrendsErrorCode,
fetchTrendingNow,
} from 'google-trends-scraper';
/** The package never retries on its own: one explicit retry that honours retryAfter. */
async function fetchWithOneRetry(geo: string) {
try {
return await fetchTrendingNow({ geo, hours: 24 });
} catch (error) {
if (!(error instanceof GoogleTrendsError)) throw error;
if (error.code !== GoogleTrendsErrorCode.HttpError) throw error;
// retryAfter is usually a number of seconds, but the header may be an HTTP date.
const seconds = Number(error.retryAfter);
const waitMs = Number.isFinite(seconds) && seconds > 0 ? seconds * 1000 : 60_000;
await new Promise((resolve) => setTimeout(resolve, waitMs));
return await fetchTrendingNow({ geo, hours: 24 });
}
}Observe or proxy the request
The fetch option exists so you can log latency, route through a proxy agent, or swap in a test double without touching the parser.
import { fetchTrendingNow } from 'google-trends-scraper';
// Route the call through a proxy agent, or just log how long Google takes.
const observedFetch: typeof fetch = async (input, init) => {
const started = Date.now();
const response = await fetch(input, init);
console.log('trending page', response.status, Date.now() - started + 'ms');
return response;
};
const result = await fetchTrendingNow({ geo: 'SG', fetch: observedFetch });Errors you can branch on
Every failure is a GoogleTrendsError with a stable code, so the decision between fixing the call, backing off and alerting is a switch statement rather than a guess. The original failure is always preserved on cause.
| Code | Raised when | Sensible reaction |
|---|---|---|
| INVALID_ARGUMENT | An option, the signal, the injected fetch or timeoutMs is unusable. | Fix the call. Retrying the same input cannot succeed. |
| HTTP_ERROR | Google answered with a non-success status. Carries status and, when sent, retryAfter. | Back off and honour retryAfter. Treat 429 and 5xx as rate limiting or an outage. |
| NETWORK_ERROR | The connection failed. The original error is kept on cause. | Transient by nature. Retry with a delay rather than in a tight loop. |
| TIMEOUT | The request or the body read exceeded timeoutMs. | Raise timeoutMs on slow links, or retry later if the endpoint is slow for everyone. |
| ABORTED | Your own signal aborted the call. | Expected on shutdown. The abort reason is on cause. |
| INVALID_RESPONSE | The payload did not match the expected shape — a moved endpoint, a changed callback or an interstitial page. | Never treat it as an empty board. Log the payload: this is the signal that Google changed something. |
INVALID_RESPONSEdeserves its own alert. It means Google changed something — the script class, the callback shape, an interstitial page — and it is the difference between a pipeline that reports “no trends today” and one that tells you it is broken.
The official Google Trends API, honestly described
If your project can wait for access and needs Explore-grade data, the official alpha is the better answer than any scraper. Here is what it is, according to Google’s own documentation.
Access is an application, not a signup
The page is still titled alpha and still accepts applications. Google says it prioritises developers with a concrete use case who can give direct feedback, so there is no self-serve key to generate today.
It serves the Explore dataset
A rolling five-year window, daily to yearly aggregation, country and sub-region comparisons, and consistently scaled values that are no longer pinned to a 0–100 index — which is what lets you join requests and compare far more than the UI’s eight comparison groups.
Trending Now is a different product
The board this package reads shows what is spiking in one region inside a 4, 24 or 48 hour window or the past 7 days, and it refreshes on the order of ten minutes. Explore answers a different question, and the two are not substitutes.
The practical summary: the alpha is a research dataset with a queue in front of it, and Trending Now is a live board with no queue and no promise. Teams that need the board today run a client like this one and keep an eye on the alpha for the day it opens up.
Explore and Trending Now are not the same dataset
Most confusion around Google Trends data comes from treating these two as one product. Google’s own documentation keeps them apart, and so should your schema:
| Explore | Trending Now | |
|---|---|---|
| What it answers | How interest in terms I chose changed over time and by region | What is spiking right now in one country or region |
| The scale | A relative index, 0–100, rescaled per request | Bucketed traffic floors plus a growth percentage |
| Time framing | A rolling five-year window in the API; any range you like in the UI | The past 4 hours, 24 hours, 48 hours or 7 days |
| Terms per request | Up to 8 comparison groups in the redesigned UI | None: the board is whatever is spiking, in its own order |
| How you reach it | The Explore UI, or the official alpha API once you are accepted | The Trending Now page, its RSS export, or a client like this one |
Google’s help text for the trending board also settles the number question in one line: search volume is “bucketed traffic for the trend within the selected timeframe, with % growth vs. predicted baseline”. That is the whole vocabulary — a floor and a growth ratio, no counts.
How it compares with the other ways in
Every entry below was checked on 18 November 2026. The questions that decide it are always the same two: which dataset do you need, and is the client still being published?
| Option | Covers | Runtime | State |
|---|---|---|---|
| google-trends-scraper (this page) | The Trending Now board for one region, with growth, tier, timing and categories | Node.js 22.13+ | Actively published: 0.2.0 on 9 Nov 2026. Zero runtime dependencies, MIT. |
| google-trends-api | Explore-style endpoints plus daily and realtime trends | Node.js | 4.9.2 was the last release, in December 2020, yet it still records around 244,000 downloads a month. Popular and unmaintained at the same time. |
| pytrends | The same Explore-style endpoints, plus trending searches | Python | Last PyPI release 4.9.2 on 13 April 2023. The GitHub repository was archived in April 2025 and its maintainer now describes the project as completely unmaintained; it still has about 3,700 stars and well over a hundred open issues. |
| google-trends-now | The same Trending Now board, with an RSS fallback for a daily list | Node.js 22+ | The closest independent alternative: published four months ago, 232 weekly downloads, and it falls back to the ten-item RSS feed when the page path fails. |
| The Trending Now RSS feed | A daily list of ten queries per region | Any HTTP client | No growth percentage, no start or end time, no categories, no sort or status control, and the hours parameter is ignored — we sent hours=4 and got the same ten items back. Google documents neither the feed nor its ht: namespace. |
Disclosure: this page is written by the maintainers of google-trends-scraper, so weigh the comparison accordingly. Every date and download figure above can be checked in the npm and PyPI registries and in the repositories named in the table.
What this package will not do for you
The package is small because it refuses to pretend. These are the boundaries to design around before it reaches production.
The endpoint is unofficial and can move
The script class, the callback shape and the row layout belong to the Trending Now page, not to a published API. There is no deprecation notice and no version negotiation, which is exactly how 0.1.x broke.
Trending Now only
Interest over time, interest by region, related queries and historical comparisons are not part of this data source and are not simulated. For those, this package is the wrong tool.
Volume is a bucket, not a number
Google’s own help text calls it “bucketed traffic for the trend within the selected timeframe”. A value of 10000 means the board showed 10K+, and nothing finer than that is published.
No pagination
limit: "all" keeps what the source already returned; it does not ask for more pages. The pool size follows the window — 15 rows at 4 hours, 60 at 24, 99 at 48 and 290 at 7 days for Singapore when we checked.
Rate limiting is your responsibility
One request per call, no proxy rotation, no automatic retry. Cache the result, poll on a sensible interval, and do not run an unbounded loop over every market.
It needs a runtime with a global fetch
Node.js 22.13 or newer, or another server runtime that provides fetch, AbortSignal and streams. No polyfills ship with the package, and browser tabs are out of scope.
Google Trends data and this client: common questions
Does Google Trends have an official API?+
Is there a free Google Trends API?+
How do I get Google Trends data without an API key?+
Why does google-trends-scraper 0.1.x return no trending searches?+
Is google-trends-scraper an official Google Trends API?+
Does it need Puppeteer, Playwright or a headless browser?+
Why is the search volume 5K+ instead of an exact number?+
Can it return interest over time or related queries?+
Is there a Python version, and is this a pytrends replacement?+
How often does the Trending Now board update?+
Can I call it from a browser or an edge function?+
Is scraping Google Trends allowed?+
What a scraper cannot guarantee
These are the commitments this package deliberately does not make. If any of them is a hard requirement for your use case, an official data source or a paid vendor is the honest recommendation.
- It cannot promise that the endpoint stays where it is. The data path belongs to a web page, and web pages change without notice.
- It cannot guarantee freshness or completeness. The board is a sample of what is spiking, not every search in that region, and rows can end between two polls.
- It cannot give you absolute search volume, historic interest curves or related-query data, because the source does not publish them.
- It cannot retry, cache or pace requests on your behalf, and it cannot protect you from a rate limit you triggered yourself.
- It cannot make unofficial data official. If a report has to cite Google, cite the Explore export or the alpha API instead.
What it does commit to is legibility: typed results, typed errors, no silent empty boards, and a test suite that feeds the parser truncated, reordered and hostile payloads so a change on Google’s side surfaces as an exception you can see.
Who maintains this
google-trends-scraper is maintained by the team behind the Fort VPN Android app, and it is the same code we run in our own trend monitoring. If the board moves again, an issue with the raw payload is the fastest way to get a fix.
Other write-ups on this site cover privacy and networking topics rather than developer tooling, and the earlier, outdated version of this page is kept online for reference only.
Editorial review
- Written by
- Fort VPN Editorial Team
- Reviewed by
- Developer Tooling Reviewer
- Last reviewed
- November 18, 2026
- Checked against
- npm / PyPI / Google Search Central / live endpoint responses
Every request, row count and response shown on this page was captured on 18 November 2026 and is reproducible with the commands and code above.
The earlier version of this guide
Before 0.2.0, this write-up documented the batchexecute request flow, the response framing and the code samples of that era. It is still online and clearly marked as outdated, for anyone who followed the older approach and needs the original frame-by-frame breakdown.
Read the archived 0.1.x guide