Keyword Interest for Google Trends: Over Time, by Region, Related Queries

Give it a list of keywords. For each keyword you get one row with:

• Interest over time: Google Trends' 0-100 search-interest timeline for your time range, plus the average, the peak value and the peak date;
• Interest by region: 0-100 per country (worldwide) or per state/province (when you pick a country), or per city / US metro area if you ask;
• Related queries: the top related queries and the rising ones, with Google's "Breakout" label kept;
• a status: ok, no_data, partial, rate_limited, error, not_attempted or stopped_bot_check, and a plain-English message when it isn't ok. error means Google answered with something we could not read (an unexpected HTTP error, a network failure or a response format we could not read) after retries, or answered a request with no data sections at all. The second case usually means the request itself was wrong, and the row's message names the input to change.

Every keyword you give gets a row, so you can see at a glance which ones need a rerun instead of finding them silently missing.

Input

Field	What it does	Default
keywords	One search term per line; each is looked up on its own (values relative to its own peak). Also accepted as searchTerms, queries, terms, keyword.	coffee, tea
comparisons	Optional. One line per comparison, up to 5 keywords separated by commas (coffee, tea, matcha). Keywords in a comparison are scaled together, like the website's compare view, so their values can be compared with each other. Each keyword still gets its own row, with comparedWith listing the others.	none
geo	Two-letter country code (US, GB, AU), optionally with a sub-region (US-CA); empty = worldwide. Also accepted as country.	worldwide
timeframe	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, or two dates 2024-01-01 2024-12-31.	today 12-m
category	Google Trends category number, 0 = all. A number Google Trends does not know is refused: you get error rows whose message says so (and the run ends as Failed) instead of rows saying the keyword had no data.	0
searchType	web, images, news, shopping or youtube.	web
includeInterestOverTime, includeInterestByRegion, includeRelatedQueries	Turn sections off to finish faster.	all on
regionResolution	auto, COUNTRY, REGION, CITY, DMA.	auto
pauseSeconds, maxRetries, maxMinutes	Pace (at least 3 s between requests), retries after HTTP 429, and a time budget.	5 s, 4, until the run timeout

Example (API / AI agents):

{"keywords": ["air fryer", "sourdough"], "comparisons": ["coffee, tea, matcha"], "geo": "US", "timeframe": "today 5-y"}

Invalid input (an unknown time range, a region name instead of a code, more than 5 keywords in a comparison, a category that is not a whole number of 0 or more, a pauseSeconds / maxRetries / maxMinutes that is not a number) stops the run at once with a message saying what to change.

Output

One dataset row per keyword (views: Overview, Interest over time, Interest by region, Related queries), and a run summary in the key-value store record OUTPUT (status counts, duration, keywords per minute, requests and HTTP 429 responses). Example row from our test run of 2026-09-25, with the source field added in version 1.1 (worldwide, today 12-m; lists cut to their first item; the full row had 53 weekly points, 57 countries and 25 top and 25 rising queries):

{
  "keyword": "coffee",
  "source": "Google Trends, https://trends.google.com",
  "comparedWith": [],
  "status": "ok",
  "message": null,
  "geo": "worldwide",
  "timeframe": "today 12-m",
  "category": 0,
  "searchType": "web",
  "interestOverTime": [{"date": "2025-09-21", "label": "Sep 21 – 27, 2025", "value": 59, "isPartial": false}],
  "averageInterest": 75.6,
  "peakInterest": 100,
  "peakDate": "2026-05-10",
  "interestByRegion": [{"geoCode": "SG", "geoName": "Singapore", "value": 100}],
  "regionResolution": "COUNTRY",
  "relatedQueriesTop": [{"query": "coffee shop", "value": 100}],
  "relatedQueriesRising": [{"query": "how to remove coffee stain from carpet", "increasePercent": 9100, "formattedValue": "Breakout", "breakout": true}],
  "fetchedAt": "2026-09-25T16:10:54Z"
}

Every row also carries a source field, Google Trends, https://trends.google.com. It survives into the raw dataset and into every one of the named views (overview, interest over time, interest by region and related queries), so the citation Google asks for travels with the data whichever way you read it.

The average and peak leave out the last point when Google marks it as partial (the current, incomplete week or day).

How it fetches, and what that means for speed

• It asks Google Trends' own web endpoints at a steady pace (by default one request every 5 seconds), from the run's own address, with a User-Agent that names this actor. It does not use proxies, rotate addresses or disguise itself as a browser.
• Before the first Trends request, every run reads Google Trends' robots.txt with that same User-Agent and checks every path the run will ask for against it, using the robots.txt standard's rules (longest match wins; an allow beats a disallow of the same length). If a path the run needs is disallowed, the run stops there: each keyword not yet fetched gets a not_attempted row naming the path and the rule, and the run ends as Failed. If robots.txt cannot be read at all (a 5xx answer, a rate-limit answer, a network failure, or a page such as a captcha instead of the file), the run also stops before asking Google for anything, because an unreadable file is no basis for continuing; those rows say the file could not be read rather than naming a rule. An ordinary "not found" answer (a 4xx) is different: the standard reads that as no rules, so the run continues. If the check stops a run before any request, only the run's start charge (US$0.00005 at the default memory, see Pricing) is charged and no keyword is. If it stops a run part way (a request address Google Trends hands back during the run matches a disallow rule, or a redirect leads somewhere not allowed), keywords already returned with status ok are charged as usual, and the keyword that was stopped and the ones after it are not.
• Each keyword on its own takes 4 requests with all three sections on (2 with only interest over time); a comparison of 5 takes 12 requests. So with the default pace one keyword takes about 20 seconds with all sections, about 10 seconds with interest over time only.
• When Google answers HTTP 429 (too many requests), the actor waits 30 s, 60 s, 120 s... and retries, up to maxRetries times. If Google still refuses, that keyword gets a rate_limited row (or partial if some sections were fetched) and the run moves on.
• If Google ever shows a captcha or "unusual traffic" page, the run stops there: remaining keywords get not_attempted rows. It never tries to get past such a page.
• Measured in our own test runs on Apify (256 MB memory, default pace, all three sections, worldwide, last 12 months). These are single runs from one day, not a guarantee; Google's rate limits vary.
  • 200-keyword run on 2026-09-25: all 198 real keywords ok (the other 2 were deliberately made-up terms and came back no_data), 80 minutes in total, about 2.5 keywords per minute. Google answered HTTP 429 23 times in 824 requests; every one cleared after the back-off wait, so no keyword ended rate_limited. No captcha or bot page. Platform usage was US$0.069, about US$0.34 per 1,000 keywords.
  • The default input (coffee, tea) finished in under a minute in each of our smoke runs.

Limitations

• Google Trends values are relative (0-100) and sampled by Google; two fetches of the same keyword can differ slightly, as they do on the website.
• Very rare keywords return no_data, as on the website.
• Related topics and the daily "Trending now" list are not included yet.
• The endpoints are the ones the Trends website itself uses; Google can change them without notice. We run this actor daily to catch that: a run in which no keyword is ok and at least one row has status error still saves its rows, then ends as Failed. Runs where every keyword is no_data, rate_limited, not_attempted or stopped_bot_check end as Succeeded, since those are Google's answers, explained in each row's message; a run stopped by the robots.txt check ends as Failed (each row names the denial or says why the file could not be read; charges are as described in the robots.txt paragraph above). A request Google Trends refuses (an unknown category, for example) also comes back as error rows, so the run ends as Failed with a message naming the input to fix, rather than reporting made-up "no data" rows.

Use with AI agents

Give keywords as a list of strings, and read status first: only ok and partial rows carry data. Values from separate keywords are not comparable with each other; put up to 5 keywords in one comparisons line when they need to be.

Pricing

Pay per event:

• US$0.002 per keyword returned with data (status ok, event keyword). Keywords with no data, rate-limited or not attempted are not charged.
• Our start charge, once per run: US$0.00005 per GB of run memory, minimum one GB (event apify-actor-start). At the default 256 MB that is US$0.00005 per run. Apify charges this automatically when the run starts, including a run that ends Failed (a run the robots.txt check stops, for example): stopping early avoids the per-keyword charge, not this one.

There's no extra charge for platform usage. For example, fetching 50 keywords (all returning data) costs 50 × US$0.002 + US$0.00005 = about US$0.10. Apify shows the price before you run, and you can set a maximum charge per run.

Changes

• 1.1: every run now reads Google Trends' robots.txt before its first Trends request and checks each path it is about to ask for against it; a disallowed path, or a robots.txt that cannot be read, stops the run before it asks Google anything, with each keyword's row naming the rule or the fetch failure. A category number, region or time range that Google Trends refuses now ends the run Failed with a message naming the setting to check, instead of rows that just said "HTTP 400 from Google Trends" or looked like no data. Invalid category, pauseSeconds, maxRetries and maxMinutes values are now rejected at input time with a clear message instead of crashing the run. Every row carries a source field, kept in the raw dataset and all named views.
• 1.0: first public release.

Support

Use the Issues tab on this page. Replies are written with AI assistance; the human owner of Madrasco can be reached on request. This actor is built and maintained with AI agents by Madrasco.

Data source: Google Trends (https://www.google.com/trends). If you publish these figures, cite Google Trends as the source.

Built by Madrasco. Not affiliated with, endorsed by or sponsored by Google. Google Trends is a trademark of Google LLC. This actor returns aggregate, relative search-interest figures; it collects no personal data.