# Google Trends Scraper (`lomo-dev/google-trends-scraper`) Actor

Google Trends interest over time, interest by region and related queries (top + rising) for Web, YouTube, News, Images or Shopping. Compare up to 5 terms or run many separately, with retries, session rotation and visible failures.

- **URL**: https://apify.com/lomo-dev/google-trends-scraper.md
- **Developed by:** [Lomo Dev](https://apify.com/lomo-dev) (community)
- **Categories:** SEO tools, Marketing
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.30 / 1,000 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

**Get interest over time, interest by region, related queries and related topics from Google Trends** — with session rotation, retries, and honest handling of Google’s scraper limitations.

Compare up to 5 terms on one chart or run many terms one by one.

[![Actor](https://apify.com/actor-badge?actor=lomo-dev/google-trends-scraper)](https://console.apify.com/actors/689tj7DP1H1DJl2zn)

***

### 🚀 Why this Actor

- **Retries that recover** — exponential backoff + session/IP rotation on 429/403/5xx
- **Honest about Google limits** — reports `googleUserType` and moves suspected “Breakout” decoys into `suspectedDecoys`
- **Failures are visible** — failed queries still produce a row with `status: "failed"`
- **One clean row per query** with every section keyed by search term
- Supports Web, YouTube, News, Images, Shopping

***

### 📥 Input

| Field | Default | Description |
|-------|---------|-------------|
| `searchTerms` | required | Keywords / topics |
| `mode` | `separate` | `separate` or `compare` (max 5 terms) |
| `geo` | `""` (worldwide) | e.g. `US`, `GB`, `US-CA` |
| `timeframe` | `today 12-m` | `now 1-H` … `today 5-y`, `all`, or custom range |
| `category` | `0` | Google Trends category ID |
| `property` | `web` | web / youtube / news / images / shopping |
| `outputs` | interestOverTime, interestByRegion, relatedQueries | relatedTopics is opt-in |
| `risingFilter` | `strict` | Moves suspected decoys aside |
| `regionResolution` | `AUTO` | COUNTRY / REGION / DMA / CITY |
| `proxyConfiguration` | Apify Proxy | Recommended |

#### Example input

```json
{
  "searchTerms": ["web scraping"],
  "mode": "separate",
  "geo": "US",
  "timeframe": "today 12-m",
  "property": "web",
  "outputs": ["interestOverTime", "interestByRegion", "relatedQueries"],
  "proxyConfiguration": { "useApifyProxy": true }
}
```

***

### 📤 Output

One dataset item per query with:

- `status` (`ok` / `failed`)
- `interestOverTime`
- `interestByRegion`
- `relatedQueries` (top + rising + suspectedDecoys)
- `relatedTopics` (when available)
- `googleUserType`, `warnings`, `trendsUrl`, `scrapedAt`

***

### Example output

Sample rows from a real owner run (public scrape data):

```json
[
  {
    "status": "ok",
    "searchTerms": [
      "web scraping"
    ],
    "geo": "US",
    "timeframe": "today 12-m",
    "category": 0,
    "property": "web",
    "trendsUrl": "https://trends.google.com/trends/explore?date=today%2012-m&q=web%20scraping&geo=US&hl=en-US",
    "averages": null,
    "scrapedAt": "2026-11-06T17:03:02.452Z",
    "interestOverTime": [
      {
        "date": "2025-11-02T00:00:00.000Z",
        "timestamp": 1762041600,
        "formattedTime": "Nov 2\u2009\u2013\u20098, 2025",
        "values": {
          "web scraping": 79
        },
        "isPartial": false
      },
      {
        "date": "2025-11-09T00:00:00.000Z",
        "timestamp": 1762646400,
        "formattedTime": "Nov 9\u2009\u2013\u200915, 2025",
        "values": {
          "web scraping": 75
        },
        "isPartial": false
      },
      {
        "date": "2025-11-16T00:00:00.000Z",
        "timestamp": 1763251200,
        "formattedTime": "Nov 16\u2009\u2013\u200922, 2025",
        "values": {
          "web scraping": 76
        },
        "isPartial": false
      }
    ],
    "interestByRegion": [
      {
        "geoCode": "US-MD",
        "geoName": "Maryland",
        "values": {
          "web scraping": 100
        }
      },
      {
        "geoCode": "US-WY",
        "geoName": "Wyoming",
        "values": {
          "web scraping": 82
        }
      },
      {
        "geoCode": "US-KS",
        "geoName": "Kansas",
        "values": {
          "web scraping": 37
        }
      }
    ],
    "relatedQueries": {
      "web scraping": {
        "top": [
          {
            "query": "web data scraping",
            "value": 100,
            "formattedValue": "100",
            "link": "https://trends.google.com/trends/explore?q=web+data+scraping&date=today+12-m&geo=US"
          },
          {
            "query": "ai web scraping",
            "value": 89,
            "formattedValue": "89",
            "link": "https://trends.google.com/trends/explore?q=ai+web+scraping&date=today+12-m&geo=US"
          }
        ],
        "rising": [
          {
            "query": "best pizza near me",
            "value": 350,
            "formattedValue": "+350%",
            "link": "https://trends.google.com/trends/explore?q=best+pizza+near+me&date=today+12-m&geo=US"
          },
          {
            "query": "email marketing for restaurants",
            "value": 150,
            "formattedValue": "+150%",
            "link": "https://trends.google.com/trends/explore?q=email+marketing+for+restaurants&date=today+12-m&geo=US"
          }
        ]
      }
    }
  }
]
```

### 💰 Pricing (Pay-per-event)

| Event | Price |
|-------|-------|
| Actor start | **$0.0005** per start, charged once per GB of run memory |
| Dataset result | **$0.0003** per query row written |

**Memory:** the default is **512 MB**, which bills a single start event.

Example: 1 search term at default memory ≈ $0.0005 + $0.0003 ≈ **$0.0008**. Ten terms ≈ $0.0005 + 10 × $0.0003 ≈ **$0.0035**.

***

### ⚙️ Memory limits

- Min: **512 MB**
- Max: **2048 MB**

***

### 📝 Limits (as of 2026)

- Related topics are usually empty for non-logged-in sessions
- Rising queries may still contain some decoys — treat as directional
- Use Apify Proxy for large batches

This Actor only uses public, non-logged-in Google Trends data.

# Actor input Schema

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

Keywords or topics to look up. In 'separate' mode each term is queried on its own (any number). In 'compare' mode up to 5 terms are compared on one chart, like the Google Trends compare box.

## `mode` (type: `string`):

How search terms are grouped into Google Trends queries.

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

Country or region code, e.g. US, GB, US-CA. Empty = worldwide.

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

Google Trends time string: '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 custom range 'YYYY-MM-DD YYYY-MM-DD'.

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

Google Trends category ID (0 = all categories).

## `property` (type: `string`):

Which Google search property to measure.

## `outputs` (type: `array`):

Sections to collect for every query. Note: Google currently withholds related topics from non-logged-in clients (empty lists, flagged with a warning), so it is off by default.

## `risingFilter` (type: `string`):

Google mixes unrelated 'Breakout' rising queries into responses for automated sessions. Strict moves Breakout queries with no overlap with your term into suspectedDecoys (kept, not deleted).

## `regionResolution` (type: `string`):

Granularity for interest by region. AUTO uses Google's default (countries worldwide, subregions inside a country). DMA only works for US.

## `includeLowVolumeRegions` (type: `boolean`):

Include regions with too little data (value 0).

## `language` (type: `string`):

Interface language for topic names, e.g. en-US, de, fr.

## `maxRetries` (type: `integer`):

Retries with exponential backoff and session/IP rotation when Google rate-limits (HTTP 429) or errors.

## `delayBetweenQueriesMs` (type: `integer`):

Pause between Google Trends queries to stay under rate limits.

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

Apify Proxy is recommended on the platform. Datacenter works for most runs; residential improves reliability at volume.

## Actor input object example

```json
{
  "searchTerms": [
    "web scraping",
    "data extraction"
  ],
  "mode": "separate",
  "geo": "",
  "timeframe": "today 12-m",
  "category": 0,
  "property": "web",
  "outputs": [
    "interestOverTime",
    "interestByRegion",
    "relatedQueries"
  ],
  "risingFilter": "strict",
  "regionResolution": "AUTO",
  "includeLowVolumeRegions": false,
  "language": "en-US",
  "maxRetries": 6,
  "delayBetweenQueriesMs": 1500,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `trends` (type: `string`):

All query results (interest over time, regions, related queries/topics) stored 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",
        "data extraction"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("lomo-dev/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 = {
    "searchTerms": [
        "web scraping",
        "data extraction",
    ],
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("lomo-dev/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 '{
  "searchTerms": [
    "web scraping",
    "data extraction"
  ],
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call lomo-dev/google-trends-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,lomo-dev/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/689tj7DP1H1DJl2zn/builds/GQLaOEKaIShgUkbac/openapi.json