Google Trends Scraper, no empty runs

If your last Google Trends scraper ran for twenty minutes, returned an empty dataset and charged you anyway, that is the problem this Actor exists to remove.

Every query is a direct HTTP call to Google Trends and comes back in about one second, with an explicit status: ok, no_data, invalid_input or error. You are charged once per query that returns a timeline with data. Empty, invalid and failed queries are free, so a bad run costs you nothing.

What you get as clean JSON: interest over time, interest by region and sub-region, and related queries (top and rising), for up to 5 terms per query, any country, any timeframe, on web, YouTube, images, news or shopping.

Why this Google Trends scraper

• No headless browser. Direct HTTP calls to Google Trends: about one second per query and a fraction of the memory of browser-based scrapers.
• Explicit statuses. Every query ends as ok, no_data, invalid_input or error. You always know why a row is empty.
• You only pay for data. Charged once per query that returns a timeline with data. Empty, invalid or failed queries are free.
• Input validated before Google is called. Wrong country codes, malformed timeframes, more than 5 terms or forbidden characters are rejected instantly with a readable message, not after a 400 from Google.
• Rate-limit aware. Calls are spaced and retried with backoff on Google's 429 responses, so bursts do not fail your run.
• Unicode search terms work: Japanese, Arabic, Cyrillic, accents, emojis, c#, .net.

Input

{
  "queries": [
    { "terms": ["laundry detergent"], "geo": "US", "timeframe": "today 12-m" },
    { "terms": ["lessive", "adoucissant"], "geo": "FR", "timeframe": "today 5-y" }
  ],
  "includeGeoBreakdown": true,
  "includeRelatedQueries": true
}

Field	Values
terms	1 to 5 search terms per query (Google's comparison limit)
geo	ISO country code (US, FR, DE), Google sub-region (US-CA, FR-J), or empty for 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 a past range YYYY-MM-DD YYYY-MM-DD
category	Google Trends category id, 0 for all
property	"" (web), youtube, images, news, froogle (shopping)

Output (one record per query)

{
  "status": "ok",
  "terms": ["lessive", "adoucissant"],
  "geo": "FR",
  "timeframe": "today 12-m",
  "note": "values = relative index 0-100 (100 = peak of the series), never an absolute volume",
  "timeline": [
    { "time": 1756598400, "date": "2025-08-31T00:00:00Z", "values": [73, 7], "partial": false }
  ],
  "geo_breakdown": [ { "geo_code": "FR-J", "name": "Île-de-France", "values": [100, 9] } ],
  "related_queries": {
    "top":    [ { "query": "lessive liquide", "value": 100 } ],
    "rising": [ { "query": "lessive enzymatique", "value": 350, "formatted": "+350%" } ]
  },
  "related_topics": "unavailable"
}

Read this before you compare numbers

Google Trends never returns search volumes. values is a relative index from 0 to 100 where 100 is the peak of the requested series. Comparing two terms in one query puts them on the same scale ([73, 7] means the second term gets about a tenth of the first's interest). Comparing values across two separate queries is meaningless.

A query can legitimately return "status": "no_data": the term has too little search volume in that country and timeframe (a French word queried in Italy, a niche term over the past hour, a random string). This is Google's answer, not a failure, and it is not charged.

related_topics is reported as unavailable: Google currently returns an empty list for topic entities through this channel. It is not advertised and not charged.

Limits

• Google throttles at roughly one request per second per IP. This Actor spaces its calls accordingly: expect about 1.5 s per query, plus 1 to 2 s when regional breakdown and related queries are requested.
• Up to 5 terms per query (Google limit). Send several queries for more terms.
• Custom date ranges must lie entirely in the past.

Use cases

Keyword research and SEO seasonality, product launch timing, market sizing by region, brand monitoring, e-commerce demand forecasting, content calendars, academic research on search interest.

Disclaimer

This is an unofficial tool. It is not affiliated with, endorsed by or sponsored by Google. "Google" and "Google Trends" are trademarks of Google LLC, used here only to describe the data source.