# Google Trends Scraper Pro (`dami0089/google-trends-scraper-pro`) Actor

Google Trends scraper rapido y confiable: interes por termino, region y tiempo, queries relacionadas y comparacion multi-termino. Sin navegador, menos de 2% de fallas, $0.002 por resultado.

- **URL**: https://apify.com/dami0089/google-trends-scraper-pro.md
- **Developed by:** [Damian Oliva](https://apify.com/dami0089) (community)
- **Categories:** SEO tools, News
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$2.00 / 1,000 trend results

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 Pro: trends by term and region

Scrape public Google Trends data by term, geo and time range: interest over time, interest by region and city, related queries and related topics. The actor uses HTTP requests without a browser or login. Google may rate-limit requests, so residential proxies are recommended for production runs.

### What it does

Google Trends Scraper Pro extracts, for 1 to 20 search terms per run:

- **Interest over time** — daily/weekly time series normalized 0–100, plus the period average.
- **Interest by region** — countries worldwide, or states/subregions when you set a country geo.
- **Interest by city** — city-level interest when a country geo is selected.
- **Related queries** — TOP and RISING (including Breakout queries with their growth rate).
- **Related topics** — TOP and RISING, when Google returns mapped topics for the term.

One dataset item per term. A term with no data is saved with `hasData: false` instead of failing the whole run.

### Why it is more reliable (pure HTTP, no browser)

This actor calls the JSON endpoints used by the Trends frontend (`/trends/api/explore` and `/trends/api/widgetdata/*`):

1. Prime session cookies (cookieless API calls are rejected).
2. `GET /trends/api/explore` with the comparison item → widget tokens.
3. `GET /trends/api/widgetdata/multiline` (time series), `comparedgeo` (regions, cities) and `relatedsearches` (top + rising).
4. Normalize into one item per term.

Resilience is built in: 3 attempts with exponential backoff on 429/5xx/timeouts, session cookie re-priming between retries, rotating residential proxy support, polite spacing between calls, and per-item error isolation — one bad term never kills the run.

### Use cases

- **SEO & Keyword Strategy**: Discover breakout search queries and seasonal search spikes before competitors do.
- **Competitor Benchmarking**: Compare up to 20 brand or product keywords on an aligned 0–100 scale to gauge relative search interest.
- **Geo-Targeted Marketing**: Identify which countries, states, or cities have the highest concentration of search volume for precise ad spend allocation.
- **Content & Trend Forecasting**: Track rising topics and queries over 7 days, 3 months, or 5 years to plan editorial calendars and viral campaigns.
- **AI Agent & LLM Tooling**: Feed real-time aggregate trend data directly into AI assistants and automated research workflows via Apify and MCP.

### Input

| Field | Type | Description |
|---|---|---|
| `searchTerms` | string array (required) | Terms to query, 1–20 per run. |
| `timeRange` | string | `today 3-m` (default), `today 12-m`, `today 5-y`, `all`, `now 7-d`, or a custom `YYYY-MM-DD YYYY-MM-DD` range. |
| `geo` | string | Country code (`US`, `AR`, `ES`) or empty for worldwide. |
| `category` | integer | Numeric Google Trends category (0 = all). |
| `maxItems` | integer | Max results to save (default: 5, 0 = no limit). Caps your spend. |
| `proxyConfiguration` | proxy | Residential rotating proxies recommended. Works without proxy too. |

#### Example input (JSON)

```json
{
    "searchTerms": ["web scraping"],
    "timeRange": "today 3-m",
    "maxItems": 5
}
```

You can pass up to 20 terms sharing the same `timeRange`/`geo`. Google compares at most five terms per request. For larger sets, the actor joins groups using a repeated reference term and rescales the timelines to one 0–100 scale. Each item carries a `comparison` table with every term's average on that scale. If Google does not return enough reference data to align the groups, the actor falls back to per-term series and `comparison` is `null`.

### Output example (real run)

```json
{
    "searchTerm": "web scraping",
    "timeRange": "today 3-m",
    "geo": "",
    "timeline": [
        {
            "time": "1783209600",
            "formattedTime": "Jul 5, 2026",
            "value": 37
        },
        {
            "time": "1783296000",
            "formattedTime": "Jul 6, 2026",
            "value": 33
        },
        {
            "time": "1783382400",
            "formattedTime": "Jul 7, 2026",
            "value": 33
        }
    ],
    "averages": [
        27.8
    ],
    "interestByRegion": [
        {
            "geoCode": "SH",
            "geoName": "St. Helena",
            "value": 100
        },
        {
            "geoCode": "CN",
            "geoName": "China",
            "value": 30
        },
        {
            "geoCode": "NL",
            "geoName": "Netherlands",
            "value": 29
        }
    ],
    "interestByCity": [],
    "relatedQueriesTop": [
        {
            "query": "python web scraping",
            "value": 100,
            "formattedValue": "100"
        },
        {
            "query": "web scraping ai",
            "value": 94,
            "formattedValue": "94"
        },
        {
            "query": "what is web scraping",
            "value": 72,
            "formattedValue": "72"
        }
    ],
    "relatedQueriesRising": [
        {
            "query": "web scraping là gì",
            "value": 200,
            "formattedValue": "+200%"
        }
    ],
    "relatedTopicsTop": [],
    "relatedTopicsRising": [],
    "comparison": null,
    "hasData": true
}
```

Notes: `interestByCity` is populated when a country `geo` is set and Google reports city-level data (low-volume terms legitimately return none). `relatedTopics*` mirrors what Google returns — terms without mapped knowledge graph entities return empty arrays. Empty arrays mean "Google returned nothing", never invented data. `comparison` is `null` on single-term runs; on multi-term runs it lists every term with its average on the shared 0–100 scale, e.g. `"comparison": [{"searchTerm": "web scraping", "average": 62.4}, {"searchTerm": "data extraction", "average": 31.8}]`.

### Pricing

Pay per event, charged only for results actually saved:

| Event | Price |
|---|---|
| `result-item` — one processed term | US$ 0.002 |

Example: 1,000 results ≈ US$ 2.00. `maxItems` caps the run, and the actor also reads your max-charge budget before starting, so a run never spends more than you allowed.

### Comparison with alternatives

This actor calls the public JSON endpoints directly and charges $0.002 per saved result. Google can still rate-limit datacenter endpoints; an Apify residential proxy is recommended in production. Each result includes the fields Google returns for that term: period averages, geographic interest, and TOP and RISING related queries and topics when available.

### FAQ

**Is there an official Google Trends API?** No. Google publishes no official API; this actor uses the same public JSON endpoints the trends.google.com frontend calls. Only public, aggregate trend data is collected.

**What data does it collect?** Public aggregate trend statistics. It does not request account credentials or personal search histories.

**Why is `interestByCity` empty?** City resolution only exists for country geos, and Google reports cities only where search volume is significant. Worldwide runs and niche terms legitimately return `[]`.

**Why is `timeline` empty / `hasData: false`?** Google returned no measurable interest for that range/geo/category. Widen the range or drop the geo filter. A request failure is logged and skipped rather than reported as a no-data result.

**I get many 429s.** Google throttles datacenter IPs. Enable Apify Proxy (residential) in the input — that is exactly what the `proxyConfiguration` field is for.

**How are values normalized?** 0–100 relative to the peak in the requested region and period (100 = peak popularity). On multi-term runs the actor aligns groups of at most five terms to one shared scale when Google supplies overlapping reference data; `comparison` summarizes each term's average on that scale.

### Integrations

Results land in the default dataset: pull them via the Apify API (`/v2/actor-runs/{runId}/dataset/items`), export CSV/JSON, or push them to Make, Zapier, or any webhook. The actor is also MCP-ready, so AI assistants can query Trends through it. One item per term keeps downstream mapping trivial.

# Actor input Schema

## `searchTerms` (type: `array`):

Terminos a consultar, 1 a 20 por corrida.

## `timeRange` (type: `string`):

Rango: 'today 12-m', 'today 3-m', 'today 5-y', 'all', 'now 7-d' o 'YYYY-MM-DD YYYY-MM-DD'.

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

Codigo geo ('US', 'AR', 'ES') o vacio para mundial.

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

Categoria numerica de Google Trends (0 = todas).

## `maxItems` (type: `integer`):

Maximo de resultados a guardar (0 = sin limite). Controla el gasto.

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

Proxy residencial rotado (recomendado: Apify Proxy) para evitar limites 429 de Google.

## Actor input object example

```json
{
  "searchTerms": [
    "web scraping"
  ],
  "timeRange": "today 3-m",
  "geo": "",
  "category": 0,
  "maxItems": 5,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `results` (type: `string`):

All scraped items in the default dataset.

# 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 = {
    "searchTerms": [
        "web scraping"
    ],
    "timeRange": "today 3-m",
    "geo": "",
    "category": 0,
    "maxItems": 5,
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("dami0089/google-trends-scraper-pro").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 = {
    "searchTerms": ["web scraping"],
    "timeRange": "today 3-m",
    "geo": "",
    "category": 0,
    "maxItems": 5,
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("dami0089/google-trends-scraper-pro").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 '{
  "searchTerms": [
    "web scraping"
  ],
  "timeRange": "today 3-m",
  "geo": "",
  "category": 0,
  "maxItems": 5,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call dami0089/google-trends-scraper-pro --silent --output-dataset

```

## MCP server setup

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

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/fAEgEHQB2sM2YbwGF/builds/2NFHWJ3NGNCGP5aXE/openapi.json