Google Trends Scraper — Interest Over Time & By Region

Google Trends data as clean JSON. Compare up to five search terms, for any country and any timeframe, and get back either a time series or a regional breakdown — one flat row per data point, ready for a spreadsheet or a dataframe.

Why this one

Google publishes no official Trends API. The endpoint behind trends.google.com works, but it rate-limits aggressively — it will happily hand you a valid session token and then answer 429 to the request that actually carries the data. That is why Trends scrapers have a reputation for failing halfway through.

This actor treats a 429 as "this IP is spent", not "the request was wrong". Each retry runs on a new residential IP with a fresh session, so a rate-limited attempt costs you a few seconds instead of a failed run.

That isn't a theoretical feature. Here's a real log line from the run that produced the regional example below:

WARN  Trends attempt 1/4 failed: comparedgeo HTTP 429 — rotating IP
WARN  Trends attempt 2/4 failed: comparedgeo HTTP 429 — rotating IP
INFO  Done. rows=102

Two IPs were rate-limited. You still got your 102 rows.

Input

Field	Type	Notes
keywords	array	Up to 5 terms to compare. Required.
geo	string	"US", "DE", "RO", or a sub-region like "US-CA". Empty = worldwide.
timeframe	string	now 7-d, today 1-m, today 12-m, today 5-y, all, or "2024-01-01 2024-12-31".
dataType	string	timeseries (interest over time) or geo (interest by region).
category	integer	Google Trends category id. 0 = all categories.
proxyConfiguration	object	Residential by default. Changing this will likely produce 429s.

Output

dataType: "timeseries" — one row per date per keyword:

{
  "keyword": "chatgpt",
  "date": "Jul 26, 2026",
  "timestamp": "2026-07-26T00:00:00.000Z",
  "value": 65,
  "isPartial": false,
  "geo": "US",
  "timeframe": "today 12-m",
  "scrapedAt": "2026-08-04T12:35:37.000Z"
}

dataType: "geo" — one row per region per keyword:

{
  "keyword": "skiing",
  "geoName": "Vermont",
  "geoCode": "US-VT",
  "value": 93,
  "hasData": true,
  "geo": "US",
  "timeframe": "today 12-m",
  "scrapedAt": "2026-08-04T12:37:17.000Z"
}

isPartial: true marks the final bucket of a series, where the period hasn't finished yet — useful to exclude before charting, or it will look like a sudden drop.

The one thing to understand about the numbers

Trends values are relative, not absolute. 100 is the peak of this particular comparison, and everything else is scaled against it. There is no search-volume figure hiding underneath.

The practical consequence: adding or removing a keyword rescales every other series. Two runs with different keyword sets are not comparable to each other. If you need a stable baseline across many runs, keep one fixed reference term in every query.

Typical uses

• Track a brand against its competitors over time
• Find which regions actually want a product before spending on ads there
• Check whether a term is genuinely breaking out or just seasonal
• Seasonality planning: pull today 5-y and look at the repeating shape

Limits

• Query shape changes how hard Google throttles. Measured: a 2-term query scoped to a country succeeded repeatedly in the same minutes that a 3-term worldwide query was refused on seven consecutive residential IPs. If a run fails, the fix is almost always to narrow it — set geo to a country, or compare fewer terms — not to retry the same thing. The actor says so in the error rather than failing silently.
• Google compares at most 5 terms per query — the actor rejects more instead of silently dropping them.
• Very low-volume terms come back as an empty series. That's Google having no data, not a scrape failure; the run logs a warning and finishes clean.
• Requests go through residential proxy by default because datacenter ranges are what Google blocks hardest.