📈 Google Trends Insights Scraper

Extract structured Google Trends data at scale: interest over time, interest by region/city/DMA, related queries and topics, and real-time trending searches — plus a deterministic statistics bundle (peak, trend direction, %-change, breakout flag, volatility) computed for every keyword. Built on the actively-maintained trendspy library (current Google Trends endpoints), so it keeps working where old pytrends-based scrapers return HTTP 429.

Ideal for SEO keyword research, market research, content planning, seasonality analysis, demand forecasting, and BI dashboards (JSON / CSV / Excel export).

---

🗃️ What you can extract (dataTypes)

Each data type is opt-in and billed as its own pay-per-event, so you only pay for (and only trigger the proxy cost of) the data you actually request.

Data type	Returns
TIMESERIES	Interest over time per keyword (0-100), isPartial per point, per-keyword averageInterest, and the full derived-stats bundle.
GEO	Interest by region / state / city / DMA: geoName, regionCode, value, resolution.
RELATED_QUERIES	Top and rising related search queries with their relative / %-change value and a breakout flag.
RELATED_TOPICS	Top and rising related topics (topicTitle, topicType, topicMid, value).
TRENDING_NOW	Real-time trending searches for a region: keyword, volume, volumeGrowthPct, startedAt, trendKeywords, topics, and optional news articles.

📊 Derived statistics (per keyword, pure arithmetic — no AI)

Computed locally from the interest-over-time series:

averageInterest · peakValue + peakDate · minValue · latestValue · trendDirection + regression slope · percentChange (second-half vs first-half) · breakout (>5000% rise) · volatilityStdDev + volatilityCV · spikeDates (points above mean + 2 standard deviations).

---

⚙️ Key features

• Opt-in, separately-billed data types — fetch only what you need.
• Comparison mode — compare up to 5 keywords in one normalized 0-100 request.
• Google property (gprop) — Web, News, Images, YouTube, or Shopping verticals.
• Free-text geo — country (US), region (US-NY), city (US-NY-501), or DMA.
• Full category support — numeric ID or a search name resolved against the full tree.
• Language / timezone — configurable hl and tz.
• Custom absolute or relative date range (datepicker) overriding the presets.
• Output shaping — wide (nested timeline + stats) or long (row per date × keyword).
• Resilient fetching — exponential backoff honoring Retry-After, proxy-IP rotation within a tier, and automatic tier escalation none → datacenter → residential.
• ISO-8601 UTC dates + scrapedAt, group dedup, and explicit (unbilled) {type: "error", reason} rows when a query returns no data.

---

🛠️ How to use

1. Add search terms (or paste Google Trends URLs, or a public Google Sheet ID).
2. Choose the data types you want.
3. Set time range / custom dates, geo, category, and gprop.
4. For reliable results, enable Apify Proxy (RESIDENTIAL recommended — Google Trends aggressively rate-limits datacenter IPs).
5. Run and export as JSON, CSV, or Excel.

---

⚙️ Example input

{
  "searchTerms": ["chatgpt", "gemini", "claude"],
  "isMultiple": false,
  "dataTypes": ["TIMESERIES", "RELATED_QUERIES", "GEO"],
  "gprop": "web",
  "timeRange": "today 12-m",
  "geo": "US",
  "category": "",
  "outputFormat": "wide",
  "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"] }
}

To compare terms in a single normalized chart, set isMultiple: true and pass one comma-joined term, e.g. ["chatgpt, gemini, claude"].

---

📤 Example output

Interest over time (wide):

{
  "type": "interest_over_time",
  "keyword": "chatgpt",
  "groupKeywords": ["chatgpt"],
  "averageInterest": 61.2,
  "peakValue": 100,
  "peakDate": "2025-04-13",
  "minValue": 21,
  "latestValue": 88,
  "trendDirection": "rising",
  "slope": 0.42,
  "percentChange": 73.5,
  "breakout": false,
  "volatilityStdDev": 18.4,
  "volatilityCV": 0.3,
  "spikeDates": ["2025-04-13"],
  "timeRange": "today 12-m",
  "geoCode": "US",
  "gprop": "web",
  "normalizedTo": "Values are 0-100, relative within this single request/comparison group.",
  "timeline": [
    { "date": "2024-07-07", "value": 42, "isPartial": false },
    { "date": "2024-07-14", "value": 45, "isPartial": false }
  ],
  "scrapedAt": "2026-07-02T00:00:00Z"
}

Interest by region:

{ "type": "interest_by_region", "keyword": "chatgpt", "geoName": "California",
  "regionCode": "US-CA", "value": 100, "resolution": "REGION", "geoCode": "US" }

Related query (rising, breakout):

{ "type": "related_query", "keyword": "chatgpt", "relation": "rising",
  "query": "chatgpt login", "value": 5000, "isBreakout": true }

---

💳 Pricing (pay-per-event)

Event	Charged when
row_result	one interest-over-time result (per keyword group)
region_result	one interest-by-region result (per keyword group)
related_result	one related-queries or related-topics result (per keyword)
trend_result	one trending-now result set (per region)

Empty results emit an unbilled {type: "error", reason} row instead of charging.

---

⚖️ Legal

Google Trends exposes only public, aggregated, anonymized search-interest data (no personal data). Use the data for research and analysis in compliance with Google's terms and your local laws.

---

❓ FAQ

Why do some values look "relative"? Google Trends never returns absolute search counts — values are 0-100, normalized within each request (see normalizedTo).

Why is the newest point flagged isPartial? The most recent time bucket is not yet complete; isPartial: true marks it so you can exclude it from analysis.

I get empty results / 429s. Google Trends rate-limits datacenter IPs hard. Enable RESIDENTIAL proxy; the actor also backs off and rotates IPs automatically.