Google Trends Scraper — Interest Over Time, by Region & Related Queries

Give it a list of search terms. Get back one row per term: the interest-over-time curve, the interest by region, the top and rising related queries, and — already computed — the average, the peak and its date, the latest value and the momentum.

Every keyword is collected on its own, inside its own time budget. A term Google throttles or stalls on comes back labelled as such while the rest keep going, and the run still ends and still writes everything it collected.

---

Why this one

The failure mode on this data source is not crashing, it is hanging — and a hung run hands back nothing at all, including the keywords it had already finished.

This actor makes the keyword, not the run, the unit of work:

1. One keyword never costs you the run. Each term gets its own deadline (45 s by default, configurable). When it expires, that single row is returned with status: "timed_out" and the real reason in error; the run carries on to the next term. 25 keywords over 5 years complete in about 47 seconds.
2. You are never charged for a curve that was not delivered. The billing event fires once per keyword whose interest curve was actually obtained and written to the dataset — never on no_data, failed, timed_out or skipped_run_budget, and never twice for the same term (the list is de-duplicated, case-insensitively, before anything is collected). There is no per-run start fee.
3. The statistics are computed for you, and computed correctly. Average, peak, peak date, latest value and momentum come with the curve. All of them exclude the final partial bucket — the one Google flags isPartial, covering a week or a month that has not finished yet. Counting it makes every trend look like it just collapsed.

---

Input

Field	Type	Default	What it does
keywords	array of strings	—	The search terms, one plain string each. Collected independently. Duplicates removed, case-insensitively. Up to 500 terms per run.
geo	string	"" (worldwide)	Two-letter country code (US, FR, GB) or a sub-region (US-CA, FR-IDF).
timeRange	string	today 12-m	now 1-H, now 4-H, now 1-d, now 7-d, today 1-m, today 3-m, today 12-m, today 5-y, all. Google picks the granularity from the window: hourly under a week, daily up to nine months, weekly beyond, monthly for the full history.
searchType	string	web	Which Google surface the interest is measured on: web, images, news, youtube, shopping. Only web has the full history back to 2004.
category	integer	0	Google Trends category id to narrow the topic (0 all, 7 finance, 71 food and drink, 174 computers and electronics).
includeRegions	boolean	true	Adds interestByRegion. One extra request per keyword, no extra charge.
includeRelated	boolean	true	Adds topRelatedQueries and risingRelatedQueries. One extra request per keyword, no extra charge.
trendingSearches	boolean	false	Also returns the day's trending searches for the country, with rank and approximate traffic. These rows carry no curve and are never charged.
keywordTimeoutSecs	integer	45	How long one keyword may take before it is returned marked as timed out. 10 to 180. Raise it on all.
language	string	en-US	Interface language, which drives the region names and date labels Google returns (en-US, fr-FR, de-DE).

{
  "keywords": ["bitcoin", "seo audit", "coffee"],
  "geo": "US",
  "timeRange": "today 12-m",
  "includeRegions": true,
  "includeRelated": true
}

---

Output

One row per keyword, always the same shape whatever happened to that keyword. Real excerpt, trimmed for length:

{
  "keyword": "bitcoin",
  "geo": "US",
  "timeRange": "today 12-m",
  "searchType": "web",
  "status": "ok",
  "interestOverTime": [
    { "date": "2025-08-31T00:00:00.000Z", "label": "Aug 31 – Sep 6, 2025", "value": 25, "hasData": true, "partial": false }
  ],
  "dataPoints": 54,
  "averageInterest": 35.3,
  "peakInterest": 100,
  "peakDate": "2026-02-01T00:00:00.000Z",
  "latestInterest": 20,
  "momentum": -7.9,
  "interestByRegion": [
    { "geoCode": "US-WY", "geoName": "Wyoming", "value": 100, "hasData": true }
  ],
  "regionsWithData": 51,
  "topRelatedQueries": [
    { "query": "bitcoin price", "value": 100, "formattedValue": "100", "breakout": false }
  ],
  "risingRelatedQueries": [
    { "query": "how to buy bitcoin safely", "value": 13600, "formattedValue": "Breakout", "breakout": true }
  ],
  "warnings": [],
  "error": null,
  "exploreUrl": "https://trends.google.com/trends/explore?q=bitcoin&date=today+12-m&hl=en-US&geo=US",
  "collectedAt": "2026-09-06T07:24:55.889Z",
  "durationMs": 4501
}

Field	Meaning
status	ok, no_data, failed, timed_out, skipped_run_budget, or trending. See the table below.
interestOverTime	The curve, point by point. value is Google's 0-100 relative index, partial marks the unfinished last bucket, hasData is false where Google reports nothing.
dataPoints	Number of points in the curve.
averageInterest	Mean of the curve, partial bucket excluded.
peakInterest / peakDate	Highest value and when it happened.
latestInterest	Last complete value.
momentum	Second half of the window minus the first half, in index points. Positive means rising.
interestByRegion	One entry per region, value on the same 0-100 scale. Read the caveat below.
regionsWithData	How many regions actually returned something.
topRelatedQueries	Most searched associated queries, value normalised to 100.
risingRelatedQueries	Fastest growing associated queries. breakout: true means growth Google does not put a number on.
trendingRank, trendingTraffic, trendingPublishedAt	Filled only on trending-search rows.
warnings	Non-fatal problems on an otherwise good row, e.g. the region panel did not answer.
error	Why this keyword has no curve, in plain words. null when it has one.
exploreUrl	The Google Trends page that shows the same query, so any row can be checked by hand.
durationMs	How long this keyword took.

What status tells you

Value	Meaning	Charged
ok	Curve obtained and delivered.	Yes
no_data	Google has no curve for this term: too little search volume. Curve, regions and related queries are empty rather than invented.	No
failed	The source returned an error for this term. error carries it verbatim.	No
timed_out	The term exceeded the time it was granted. error quotes the allowance actually given, not the one configured.	No
skipped_run_budget	The run hit its own time limit before reaching this term. It is still returned, saying so.	No
trending	A trending-search row, no curve by design.	No

---

Three things about this data that are easy to get wrong

Interest is an index, not a volume. Google Trends returns a relative 0-100 scale where 100 is the peak of that particular query over that particular window. It never returns a number of searches. Any tool telling you otherwise is guessing.

Interest by region is a share of local searches, not a ranking of places. Wyoming comes back at 100 for bitcoin, seo audit and coffee alike — a sparsely populated region hits the ceiling mechanically, because the metric is the weight of the term within that region's searches. Use it to compare a term against itself across places, not to find where the volume is.

Related topics are not returned, on purpose. Google's fourth panel only answers for entity identifiers, and comes back empty for plain search terms — measured empty 4 times out of 4, against 25 top and 25 rising related queries on the very same requests. An always-empty column is a lie, so it is not shipped.

---

Limits, stated plainly

• No absolute search volume. The source does not have it. See above.
• No related topics. See above.
• No multi-term comparison on one chart. Each keyword is measured on its own scale, which is what makes them independent and individually chargeable. Two rows are not comparable point to point.
• 500 keywords per run maximum. Past that the extra terms are dropped and the run log says so.
• Rate limiting happens, and it is absorbed rather than hidden. Google occasionally throttles the opening burst of a run; those keywords come back failed with the real reason, unbilled, and the rest of the run completes. Retrying them in a second run normally works.
• Granularity is Google's, not yours. Ask for 5 years and you get weekly points; ask for a day and you get hourly ones. There is no finer setting.

---

Cost

One event per keyword whose interest curve was obtained and delivered. Nothing on a keyword that returned no data, failed, timed out or was never reached; nothing on trending-search rows; no per-run start fee. The current rate is on this actor's pricing section.

Runs are light: 25 keywords over 5 years finish in about 47 seconds and peak at well under 100 MB of memory, so 256 MB is enough.

---

Typical uses

• Seasonality before you commit a budget. Pull 12 months on your product terms, sort by peakDate, and buy media before the peak rather than during it.
• Spotting a term going up. momentum over today 12-m on a list of category terms, filtered to positives, is a short list of what is gaining ground.
• Local targeting. interestByRegion on US or FR tells you where a term weighs most in local search, which is where landing pages and local campaigns earn their keep.
• Content ideas that already have demand. risingRelatedQueries with breakout: true is a list of questions people started asking recently.