# Google Trends Scraper (Interest & Related Queries) (`bgfc97/google-trends-scraper`) Actor

Scrape Google Trends by keyword: interest-over-time timeline plus top & rising related queries, by country (geo) and timeframe. No API key, no login. Fast pure-HTTP. Great for SEO, market research, content and trend-spotting.

- **URL**: https://apify.com/bgfc97/google-trends-scraper.md
- **Developed by:** [Bruno](https://apify.com/bgfc97) (community)
- **Categories:** Marketing, SEO tools
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$15.00 / 1,000 keyword series scrapeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Google Trends Scraper (real browser)

Get **Google Trends interest-over-time** and **related queries** for up to 5 compared keywords, any region and timeframe — driven by a **real headless browser (Playwright/Chromium)** over an **Apify residential proxy**, not raw HTTP. Google has no official Trends API; a bare HTTP client hitting its unofficial JSON endpoints gets 429'd almost instantly because it has no cookies/session/consent state. This Actor loads `trends.google.com` like a real visitor and reads the JSON the page itself fetches for its own chart.

### Why it's useful

Google Trends powers keyword research, content/SEO planning, investment sentiment signals, PR/brand monitoring and academic research — but it only has a manual web UI. This Actor turns it into a clean bulk API: compare keywords, pull the full interest-over-time series, and get the "related queries" (top + rising/breakout) for each one.

### Input

```json
{
  "keywords": ["bitcoin", "ethereum"],
  "geo": "US",
  "timeframe": "today 12-m",
  "includeRelatedQueries": true
}
```

- `keywords` — 1 to 5 search terms, compared together exactly like on trends.google.com.
- `geo` — two-letter country code (e.g. `US`, `BR`, `GB`); leave empty for worldwide.
- `timeframe` — Google Trends range string: `now 1-H`, `now 7-d`, `today 1-m`, `today 3-m`, `today 12-m`, `today 5-y`, or a custom `YYYY-MM-DD YYYY-MM-DD` range.
- `category` — optional Google Trends category ID (0 = all).
- `hl` — UI language/locale for labels, e.g. `en-US`, `pt-BR`.
- `includeRelatedQueries` — also fetch each keyword's related queries panel.
- `proxyConfiguration` — Apify Proxy for the browser session; defaults to the **RESIDENTIAL** group (datacenter IPs get blocked).
- `timeoutSecs` — how long to let the browser wait for the page's own data requests to fire (5-120, default 45).

### Output (one item per keyword)

```json
{
  "keyword": "bitcoin",
  "geo": "US",
  "timeframe": "today 12-m",
  "points": 52,
  "timeline": [
    { "time": "1727136000", "date": "2024-09-24T00:00:00.000Z", "formattedTime": "Sep 24, 2024", "value": 63, "formattedValue": "63", "hasData": true }
  ],
  "relatedQueries": {
    "top": [{ "query": "bitcoin price", "value": 100, "formattedValue": "100" }],
    "rising": [{ "query": "bitcoin etf", "value": 5000, "formattedValue": "Breakout" }]
  },
  "technique": "playwright-response-intercept",
  "scrapedAt": "2026-09-25T12:00:00.000Z"
}
```

### How it works (technique)

1. A real Playwright/Chromium browser, over an Apify **RESIDENTIAL** proxy session, navigates to `https://trends.google.com/trends/explore?q=...&geo=...&date=...&hl=...` — exactly the URL a human comparing these keywords would open. A cookie-consent interstitial, if shown, is auto-accepted.
2. The Actor registers a `page.on('response', ...)` listener **before** navigation and watches every network response the page itself makes.
3. The page's own JavaScript fires `GET /trends/api/widgetdata/multiline` (the interest-over-time chart data) and `GET /trends/api/widgetdata/relatedsearches` (top/rising related queries per keyword) using its own session cookies — these are captured directly from the browser, never re-requested by hand.
4. Google prefixes each JSON body with `)]}',` (an XSSI guard) — stripped before parsing.

### On blocking

Because these are the page's *own* requests with real cookies, they are far less likely to be blocked than the same URLs hit with a bare HTTP client (v1 of this Actor tried that and got 429'd). If the browser still can't get a chart to render within `timeoutSecs` (captcha wall, exhausted proxy pool, unusual keyword/geo/timeframe combo), the crawler retries with a fresh browser + proxy session up to 4 times; if every attempt fails, the Actor reports that honestly (with the real reason) instead of inventing numbers.

### Use cases

- 📈 **Keyword & SEO research** — seasonality, trend direction, rising queries to target.
- 💹 **Market/PR signal** — track interest spikes around brands, tickers, products, events.
- 🎓 **Research/journalism** — quantify public attention to a topic over time and by region.

### ⭐ Enjoying this Actor?

A quick **rating/review** helps others find it. Want Google-Trends-style Interest-by-Region or multi-timeframe batching added? Open a ticket on the **Issues** tab.

# Actor input Schema

## `keywords` (type: `array`):

One or more search terms to look up on Google Trends, e.g. "bitcoin". Up to 5 keywords are compared together in the same interest-over-time chart, exactly like comparing them on trends.google.com. Required.

## `geo` (type: `string`):

Two-letter country code to restrict results to, e.g. "US", "BR", "GB". Leave empty for worldwide.

## `timeframe` (type: `string`):

Google Trends time range string, e.g. "now 1-H", "now 7-d", "today 1-m", "today 3-m", "today 12-m", "today 5-y", or a custom range "2020-01-01 2020-12-31".

## `category` (type: `integer`):

Google Trends category ID to narrow results (0 = all categories, the default). Category IDs match the ones used on trends.google.com (e.g. 7 = Finance, 16 = News).

## `hl` (type: `string`):

UI language for the request and for formatted labels/dates in the response, e.g. "en-US", "pt-BR", "es-419".

## `includeRelatedQueries` (type: `boolean`):

Also fetch each keyword's "related queries" panel (top queries + rising/breakout queries), like the bottom of the Google Trends explore page. Turn off to only get the interest-over-time series and finish faster.

## `proxyConfiguration` (type: `object`):

Apify Proxy configuration for the real browser session that loads trends.google.com. Defaults to the RESIDENTIAL proxy group — Google treats datacenter IPs as bots and 429s them almost immediately, while a residential IP paired with a real browser context (cookies, JS, consent) reliably gets through. Leave as-is unless you know what you're doing.

## `timeoutSecs` (type: `integer`):

How long to let the headless browser wait for trends.google.com to load and fire its own internal data requests (interest-over-time + related queries) before giving up (5-120). Slow proxies/regions may need more than the default.

## Actor input object example

```json
{
  "geo": "",
  "timeframe": "today 12-m",
  "category": 0,
  "hl": "en-US",
  "includeRelatedQueries": true,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  },
  "timeoutSecs": 45
}
```

# Actor output Schema

## `dataset` (type: `string`):

Google Trends results. One row per keyword: timeline (interest over time) and top/rising related queries, with geo and timeframe.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("bgfc97/google-trends-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("bgfc97/google-trends-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call bgfc97/google-trends-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,bgfc97/google-trends-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/pxcuIffgZqZZg5Cd9/builds/eO6XNiB6bfLnhpOAf/openapi.json