Understand
Google Trends and its limits
Google Trends and its limits. A sampled, relative index, the official alpha, pytrends, and SerpApi. The chart is live when the endpoint answers.
Understanding the labHow to use it and why you'd want to
Why you'd want to
Load interest asks this server for a relative interest series, trying a third-party engine when a key is set and otherwise the website endpoint. After Accept the data source is queued, not the index.
How to use it
- Load interest calls this site's own route.
- A configured key tries the third-party engine first.
- Otherwise the website endpoint is used. A short cache can answer.
- The latest point is compared with a short mean. The index is not sent.
What the number is
Google’s Trends help says the product is a largely unfiltered sample of searches. Each point is divided by the total searches for that place and time, then scaled from 0 to 100 inside that request. The same interest in two places does not mean the same number of searches. A term with very low volume shows as 0.
The help also says the series includes statistical noise, most visible when interest is low, and that one-off spikes in those series are not evidence of individual searches. Trends is not a poll. Adding a second term rescales the whole chart, because 100 is the peak inside that request.
Three ways to call it
Official alpha
Google’s alpha page says it is accepting applications and cannot open the API for everyone yet. The 24 July 2025 announcement says access starts with a limited set of testers. It describes consistently scaled interest, a rolling 1,800-day window up to about two days ago, daily through yearly aggregation, and ISO 3166-2 regions. That scaling is different from the website’s 0 to 100. The public docs do not publish a base URL, so this site does not call the alpha.
pytrends
pytrends 4.9.2 (PyPI, 13 April 2023) is an unofficial client for the website. Its project text says it works until Google changes the backend, that it is looking for maintainers, and that the rate limit is not public. The source treats HTTP 429 as a quota error. A broken response is a broken response.
SerpApi
SerpApi is a third-party Google Trends engine. This server calls it only when SERPAPI_API_KEY or SERPAPI_KEY is set, and the key stays on the server. If that call fails, the page tries the website endpoint. If both fail, the chart stays empty.
Live comparison
Up to five terms, one time range, one category, and one place. The server caches a successful answer for about an hour and a failure for about 10 minutes. A browser User-Agent is sent because the website endpoint is the one the Trends page calls.
The category picker did not answer. The list is All categories only.
Labeled example
Example. Not a measurement from Google or from this site.
These points are written in the repository so the chart has a shape when Trends does not answer. They are not interest scores.
- example alpha
- example beta
| Time | example alpha | example beta |
|---|---|---|
| Point 1 | 10 | 50 |
| Point 2 | 12 | 48 |
| Point 3 | 11 | 52 |
| Point 4 | 13 | 49 |
| Point 5 | 40 | 47 |
| Place | example alpha | example beta |
|---|---|---|
| Example northEX-N | 40 | 20 |
| Example southEX-S | 15 | 47 |
Related queries
- example related phrase100
Rising queries
- example rising phraseBreakout
The same comparison, run on the example series.
example alpha · window 4 · ratio 1.5
Latest 40. Mean of 4 earlier points 11.5. Multiple 3.48. Alert.
Official alpha, described
No request. The public docs do not publish a base URL.
# Official Google Trends API (alpha)
# Docs: https://developers.google.com/search/apis/trends
# Announcement, 24 July 2025: https://developers.google.com/search/blog/2025/07/trends-api
#
# Google says the alpha is open by application to a limited set of testers.
# The public docs do not publish a base URL or a self-serve key, so this repo
# does not call it. The announcement describes:
# - consistently scaled interest (the website still rescales each request from 0 to 100)
# - a rolling window of 1,800 days, with data up to about two days ago
# - daily, weekly, monthly, and yearly aggregation
# - region and subregion codes from ISO 3166-2
# The website comparison limit in that announcement is 5 terms.
# The alpha docs page says the UI compares eight. This page sends at most five.
Python · pytrends
Interest over time, region, and related queries.
"""Unofficial. pytrends 4.9.2 on PyPI (13 April 2023) calls the Trends website.
The project text says it is unofficial, that it lasts until Google changes the
backend, and that the rate limit is not public. Its source treats HTTP 429 as
a quota error. The README says it is looking for maintainers.
This is not the official alpha API.
"""
from pytrends.request import TrendReq
pytrends = TrendReq(hl="en-US", tz=360)
pytrends.build_payload(
["personalization"],
cat=0, # category id from the Trends URL, after cat=
timeframe="today 12-m", # also: now 7-d, today 1-m, today 3-m, today 5-y
geo="US", # "" is worldwide. "US-CA" is a state. Metro uses resolution="DMA".
)
interest = pytrends.interest_over_time()
regions = pytrends.interest_by_region(resolution="REGION", inc_geo_code=True)
related = pytrends.related_queries()
Python · spike job
A cron-sized comparison. The 1.5 multiple is a lab choice.
# Lab choice, not a Google threshold: alert when the latest complete point
# is at least 1.5 times the mean of up to 4 earlier points.
# Drop a partial last bucket before you call spike().
# A zero baseline makes any later point look like a spike. Google’s Trends
# help says low-interest series include statistical noise.
WINDOW = 4
RATIO = 1.5
def spike(values: list[float]) -> dict | None:
if len(values) < 2:
return None
latest = values[-1]
prior = values[:-1][-WINDOW:]
baseline = sum(prior) / len(prior)
if baseline == 0:
return {"alert": latest > 0, "latest": latest, "baseline": baseline, "weak_baseline": True}
multiple = latest / baseline
return {
"alert": latest >= baseline * RATIO,
"latest": latest,
"baseline": baseline,
"multiple": multiple,
"weak_baseline": False,
}
# Schedule with cron. Back off on HTTP 429. Do not invent a point when the call fails.
# 15 * * * * python spike_check.py
Node · website endpoint
The same unofficial explore and multiline calls this server makes.
// Unofficial. These are the Trends website endpoints pytrends calls.
// Google can change them, refuse the call, or answer HTTP 429.
// There is no published quota. Cache the result. Do not fill a failure with a guess.
const term = "personalization"
const req = JSON.stringify({
comparisonItem: [{ keyword: term, time: "today 12-m", geo: "US" }],
category: 0,
property: "",
})
const explore = new URL("https://trends.google.com/trends/api/explore")
explore.searchParams.set("hl", "en-US")
explore.searchParams.set("tz", "360")
explore.searchParams.set("req", req)
function trendsJson(text) {
const start = text.indexOf("{")
if (start < 0) throw new Error("Trends did not return a JSON object")
return JSON.parse(text.slice(start))
}
const explored = await fetch(explore, { method: "POST" })
if (!explored.ok) throw new Error("Trends explore failed: " + explored.status)
const widgets = trendsJson(await explored.text()).widgets
const series = widgets.find((widget) => widget.id === "TIMESERIES")
if (!series) throw new Error("No interest-over-time widget")
const points = new URL("https://trends.google.com/trends/api/widgetdata/multiline")
points.searchParams.set("hl", "en-US")
points.searchParams.set("tz", "360")
points.searchParams.set("req", JSON.stringify(series.request))
points.searchParams.set("token", series.token)
const lined = await fetch(points)
if (!lined.ok) throw new Error("Trends timeline failed: " + lined.status)
const timeline = trendsJson(await lined.text())
console.log(timeline.default.timelineData.slice(-3))
Node · SerpApi
Uses SERPAPI_API_KEY. The key is not written into the page.
// Third-party. SerpApi sells a Google Trends engine. The key stays on the server.
// https://serpapi.com/google-trends-api
const key = process.env.SERPAPI_API_KEY
if (!key) throw new Error("SERPAPI_API_KEY is not set")
const url = new URL("https://serpapi.com/search.json")
url.searchParams.set("engine", "google_trends")
url.searchParams.set("q", "personalization")
url.searchParams.set("data_type", "TIMESERIES") // also GEO_MAP, RELATED_QUERIES
url.searchParams.set("date", "today 12-m")
url.searchParams.set("geo", "US")
url.searchParams.set("cat", "0")
url.searchParams.set("api_key", key)
const body = await (await fetch(url)).json()
console.log(body.interest_over_time?.timeline_data?.slice(-3))
Node · spike job
Exit when the fetch throws. Do not substitute a value.
// Same rule as the Python job. 1.5 and 4 are choices of this lab.
const WINDOW = 4
const RATIO = 1.5
function spike(values) {
if (values.length < 2) return null
const latest = values.at(-1)
const prior = values.slice(0, -1).slice(-WINDOW)
const baseline = prior.reduce((sum, value) => sum + value, 0) / prior.length
if (baseline === 0) return { alert: latest > 0, latest, baseline, weakBaseline: true }
const multiple = latest / baseline
return { alert: latest >= baseline * RATIO, latest, baseline, multiple, weakBaseline: false }
}
// Cron or a scheduled function. If the fetch throws, log the failure and exit.
// Do not write a substitute value.
WalkthroughHow we built itShowHide
Example vendor setup is marked below. eVar and event numbers are examples. This lab does not call Adobe.
The Trends lab asks this server for a relative interest series, tries a third-party engine when a key is set, and otherwise calls the website endpoint. After Accept, Load interest queues trends_view with data_source, and the lab does not call Adobe.
Ask the site’s own route
Load interest fetches /api/lab/trends with the terms, place, time, category, and resolution. The route calls loadTrends. A failed fetch still records data_source unreachable when consent is on.
Try the third-party engine, then the website
loadUncached calls the third-party engine only when a key is present. If that throws, or if there is no key, it calls the website endpoint. If both fail, the response is ok false and the chart stays empty.
Keep a short cache
loadTrends returns a cached success or a cached failure before it starts another flight for the same ask. The page says a success is about an hour and a failure about 10 minutes.
Compare the latest point with a short mean
seriesSpike takes the latest complete point and the mean of up to four earlier points. It alerts when the latest point is at least the lab ratio times that mean. A zero mean alerts only when the latest point is above zero.
Send the source, not the index
After Accept, trends_view sends data_source from the response source, or unreachable. The 0 to 100 points and the labeled example series are not parameters.
From the code
A key tries the third-party engine. The website endpoint is the fallback. A double failure stays empty.
if (key) {
try {
return { ...(await fromSerpApi(ask)), cached: false }
} catch (error) {
errors.push(error instanceof Error ? error.message : "SerpApi did not answer.")
}
}
try {
return { ...(await fromWebsite(ask)), cached: false }
} catch (error) {
errors.push(error instanceof Error ? error.message : "Google Trends did not answer.")
}
return {
ok: false,
error: errors[0] ?? "Trends is unreachable from this server. Nothing below is filled in with estimated interest.",
}The latest point against the mean of the earlier window. The ratio comes from the lab constants.
export function seriesSpike(values: number[], window = SPIKE_WINDOW, ratio = SPIKE_RATIO): SpikeRead | SpikeUnread {
if (values.length < 2 || !values.every((value) => Number.isFinite(value))) return { ready: false }
const latest = values[values.length - 1]
const prior = values.slice(0, -1).slice(-window)
if (!prior.length) return { ready: false }
const baseline = prior.reduce((sum, value) => sum + value, 0) / prior.length
const weakBaseline = baseline === 0
const multiple = weakBaseline ? null : latest / baseline
const alert = weakBaseline ? latest > 0 : latest >= baseline * ratio
return { ready: true, latest, baseline, points: prior.length, multiple, alert, ratio, weakBaseline }
}Google and Adobe
Google queues trends_view after Accept. Adobe is an example of the same fields.
After Accept, Load interest queues trends_view. data_source is website, serpapi, or unreachable. Interest points are not parameters. The labeled example chart does not queue this event. This is queued only after Accept. This site does not call Adobe.
Simplified shape of the object queued after Accept. Register any new parameter as an event-scoped custom dimension. This site does not call gtag('set').
dataLayer.push({
event: "trends_view",
data_source: "website",
})Example implementation. This site does not call Adobe. eVar110, prop110, and event110 are example variable numbers. In Launch, a data element reads the value and a rule sends it when the value changes. In the report suite, enable eVar110 with Most Recent allocation and expire it on the hit. A processing rule is unnecessary if the data element maps straight to that eVar.
Example alloy payload. _example is a placeholder schema, not a real tenant.
alloy("sendEvent", {
xdm: {
eventType: "web.webinteraction.linkClicks",
_example: {
trendsSource: "website",
},
},
})Example hit. eVar110 is hit-scoped in this example. prop110 dies at the same hit.
s.eVar110 = "website"
s.prop110 = "website"
s.events = "event110"
s.linkTrackVars = "eVar110,prop110,events"
s.linkTrackEvents = "event110"
s.tl(true, "o", "trends_view")Translation
Each lab field, the GA4 name, and the example Adobe variable. Scope is the part that usually gets lost in the translation.
Data source
GA4. Parameter data_source on trends_view. Values are website, serpapi, or unreachable.
Adobe. Example eVar110, expire on the hit.
Scope. Event. A user property would remember website after a later request fails.
Interest point
GA4. Not sent. The 0 to 100 series stays on the page.
Adobe. Example prop110. Do not write the index into a prop. Not sent.
Scope. A chart value. It is not a hit metric and not a visit property.
Spike alert
GA4. Not sent. seriesSpike is computed in the page.
Adobe. Example eVar110 for the word alert. Not sent.
Scope. A calculation for this view. It is not an event.
Example series
GA4. Not sent. The repository points are labeled as not a measurement.
Adobe. Example prop110. Not sent.
Scope. Fixture data. It is not a user property and not a hit.
Recommended next
Why these picksReading path transitions…