# Google Trends Scraper (`pampa-data/google-trends-scraper`) Actor

Get Google Trends data as clean JSON: interest over time, interest by region, related queries and topics for up to 5 compared terms, plus daily Trending Now searches for any country.

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

## Pricing

$2.00 / 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 Google Trends data as clean, ready-to-use JSON, CSV or Excel. For any search term, or up to 5 terms compared on the same scale, you get:

- **Interest over time**: the 0-100 timeline Google shows on the chart, plus the average per term.
- **Interest by region**: countries, states/regions, cities or US metro areas.
- **Related queries**: top and rising queries, with "Breakout" flags.
- **Related topics** (optional): top and rising topics when Google provides them.

There is also a **Trending Now** mode that returns today's trending searches for any country, with approximate search volume and the news articles behind each trend.

### Why this scraper

- **One result per term or comparison.** Every section for a term comes in a single dataset item, so you pay for one result, not one per data point.
- **Built for Google's rate limits.** Each request uses its own proxy session and cookies. When Google answers with HTTP 429 or a captcha, the scraper drops that session, waits a little longer, and retries with a fresh IP (8 retries by default).
- **No silent junk.** Failed terms are never pushed as empty results you pay for. They are listed in the `FAILED` record of the run's key-value store, with the reason.
- **Clear input errors.** A wrong location code or date range stops the run right away with a message that says what to fix.

### How to use it

1. Add your search terms, one per line. To compare terms, put up to 5 on one line separated by commas: `bitcoin, ethereum`.
2. Pick a location (`US`, `AR`, `US-CA`, or empty for worldwide) and a time range.
3. Click **Start**. A typical term takes 2-3 seconds.

For Trending Now, choose **What to scrape → Trending Now** and list the countries, e.g. `US`, `GB`, `AR`.

#### Input example

```json
{
    "searchTerms": ["yerba mate", "bitcoin, ethereum"],
    "geo": "US",
    "timeRange": "today 12-m",
    "searchProperty": "web",
    "includeInterestOverTime": true,
    "includeInterestByRegion": true,
    "includeRelatedQueries": true
}
```

| Field | What it does |
| --- | --- |
| `searchTerms` | One line per result. Comma-separate up to 5 terms to compare them. |
| `geo` | Country (`US`) or region (`US-CA`) code. Empty = worldwide. |
| `timeRange` | `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`. |
| `customTimeRange` | `YYYY-MM-DD YYYY-MM-DD`, overrides `timeRange`. |
| `searchProperty` | `web`, `images`, `news`, `youtube` or `shopping`. |
| `category` | Google Trends category ID (0 = all). |
| `regionResolution` | `AUTO`, `COUNTRY`, `REGION`, `CITY` or `DMA` (US metros). |
| `mode` | `explore` (default) or `trendingNow`. |
| `trendingGeos` | Countries for Trending Now. |
| `language`, `timezoneOffset` | Language of region names, and the timezone for dates (minutes behind UTC, e.g. 180 for Buenos Aires). |
| `proxyConfiguration` | Apify Proxy by default. Switch to the RESIDENTIAL group if you see many retries. |

#### Output example (explore)

```json
{
    "type": "explore",
    "searchTerms": ["bitcoin", "ethereum"],
    "geo": "US",
    "timeRange": "today 3-m",
    "category": 0,
    "searchProperty": "web",
    "interestOverTime": {
        "averages": { "bitcoin": 31, "ethereum": 2 },
        "timeline": [
            {
                "date": "2026-08-02T00:00:00.000Z",
                "timestamp": 1785628800,
                "formattedTime": "Aug 2, 2026",
                "values": { "bitcoin": 51, "ethereum": 8 },
                "isPartial": false
            }
        ]
    },
    "interestByRegion": {
        "resolution": "REGION",
        "regions": [
            { "geoCode": "US-KS", "geoName": "Kansas", "values": { "bitcoin": 88, "ethereum": 12 } }
        ]
    },
    "relatedQueries": {
        "bitcoin": {
            "top": [{ "query": "bitcoin price", "value": 100, "formattedValue": "100", "isBreakout": false, "link": "https://trends.google.com/trends/explore?q=bitcoin+price&date=today+3-m&geo=US" }],
            "rising": [{ "query": "british man recovers lost bitcoin", "value": 13250, "formattedValue": "Breakout", "isBreakout": true, "link": "https://trends.google.com/trends/explore?q=british+man+recovers+lost+bitcoin&date=today+3-m&geo=US" }]
        }
    },
    "exploreUrl": "https://trends.google.com/trends/explore?date=today%203-m&q=bitcoin%2Cethereum&geo=US",
    "scrapedAt": "2026-11-02T03:58:12.000Z"
}
```

#### Output example (Trending Now)

```json
{
    "type": "trendingNow",
    "rank": 1,
    "geo": "US",
    "title": "scottie barnes",
    "approxTraffic": "500+",
    "approxTrafficNumber": 500,
    "publishedAt": "2026-11-02T03:40:00.000Z",
    "picture": "https://encrypted-tbn0.gstatic.com/images?q=...",
    "pictureSource": "RotoWire",
    "newsItems": [{ "title": "...", "url": "https://www.rotowire.com/...", "source": "RotoWire" }],
    "exploreUrl": "https://trends.google.com/trends/explore?q=scottie%20barnes&geo=US&date=now%201-d",
    "scrapedAt": "2026-11-02T03:58:12.000Z"
}
```

### Pricing

You pay per result saved to the dataset: one result per search term or comparison line, and one per trending search. Failed terms are not charged. Set a maximum cost per run in the run options and the scraper stops cleanly when it is reached, keeping everything collected so far.

### Good to know

- **Values are relative.** Google scales every timeline so the highest point is 100. Values from different runs or comparison groups are not on the same scale; compare terms by putting them on the same line.
- **Low-volume terms** can return empty sections. That is Google having too little data, not an error.
- **Related topics** are often empty for automated requests at the moment, so they are off by default.
- **Trending Now** comes from Google's public RSS feed, which lists the top recent trends per country (usually 10-20).

### Use cases

- Find seasonal demand before launching products or ads.
- Track brand or competitor interest over time and by state.
- Discover rising keywords for SEO and content ideas.
- Feed daily trending topics into newsletters, dashboards or AI agents.

### Legal

This Actor collects aggregated, anonymous statistics that Google publishes on Google Trends. It does not collect personal data. Use the data in line with Google's terms and the laws that apply to you.

### Feedback

Found a bug or need a field? Open an issue on the Actor's Issues tab and it will be looked at quickly.

# Changelog

This Actor's version history is a separate document: https://apify.com/pampa-data/google-trends-scraper/changelog.md

# Actor input Schema

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

<b>Explore</b> returns interest over time, by region, and related queries/topics for your search terms. <b>Trending Now</b> returns today's trending searches for one or more countries.

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

One line per result. Put up to 5 terms on one line, separated by commas, to compare them on the same scale (e.g. <code>bitcoin, ethereum</code>). Each line is one dataset item.

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

Country code (<code>US</code>, <code>AR</code>, <code>DE</code>) or region code (<code>US-CA</code>, <code>AR-B</code>). Leave empty for worldwide.

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

Preset time range. Ignored if a custom time range is set.

## `customTimeRange` (type: `string`):

Optional. Two dates separated by a space: <code>2024-01-01 2024-06-30</code>. Overrides the preset time range.

## `searchProperty` (type: `string`):

Which Google property to measure.

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

Google Trends category ID, e.g. 0 = all categories, 7 = Finance, 71 = Food & Drink, 958 = Jobs. You can read the ID from the <code>cat=</code> parameter of a Trends URL.

## `includeInterestOverTime` (type: `boolean`):

Timeline of search interest (0-100).

## `includeInterestByRegion` (type: `boolean`):

Search interest per country, region, city or metro.

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

Level of detail for interest by region. Auto = countries for worldwide, regions/states for a country. Metro (DMA) works only for the US.

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

Also return regions with low search volume.

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

Top and rising related search queries for each term.

## `includeRelatedTopics` (type: `boolean`):

Top and rising related topics for each term. Off by default: Google currently returns empty topic lists for most automated requests, so this often adds requests without adding data.

## `trendingGeos` (type: `array`):

Only for Trending Now mode. Country codes, e.g. <code>US</code>, <code>AR</code>, <code>GB</code>. Defaults to the Location field, or US.

## `maxTrendingItems` (type: `integer`):

0 = all items in the feed.

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

Language for names of regions and topics, e.g. <code>en-US</code>, <code>es-AR</code>.

## `timezoneOffset` (type: `integer`):

Minutes behind UTC, as Google expects it: 0 = UTC, 180 = UTC-3 (Buenos Aires), 300 = UTC-5 (New York, standard time), -60 = UTC+1.

## `maxConcurrency` (type: `integer`):

How many terms to scrape in parallel. Keep it low to avoid Google rate limits.

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

Retries per term when Google rate-limits a request. Each retry uses a new proxy session and waits longer.

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

Google rate-limits shared IPs. The default Apify Proxy works for most runs; switch to the RESIDENTIAL group if you see many retries.

## Actor input object example

```json
{
  "mode": "explore",
  "searchTerms": [
    "yerba mate",
    "bitcoin, ethereum"
  ],
  "geo": "",
  "timeRange": "today 12-m",
  "searchProperty": "web",
  "category": 0,
  "includeInterestOverTime": true,
  "includeInterestByRegion": true,
  "regionResolution": "AUTO",
  "includeLowVolumeRegions": false,
  "includeRelatedQueries": true,
  "includeRelatedTopics": false,
  "trendingGeos": [
    "US"
  ],
  "maxTrendingItems": 0,
  "language": "en-US",
  "timezoneOffset": 0,
  "maxConcurrency": 3,
  "maxRetries": 8,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `exploreResults` (type: `string`):

One item per search term or comparison: interest over time, by region, related queries and topics.

## `trendingNow` (type: `string`):

One item per trending search, with approximate traffic and news links.

## `allResults` (type: `string`):

No description

## `failedTargets` (type: `string`):

Terms or countries that could not be scraped after all retries (not charged).

# 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": [
        "yerba mate",
        "bitcoin, ethereum"
    ],
    "trendingGeos": [
        "US"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("pampa-data/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": [
        "yerba mate",
        "bitcoin, ethereum",
    ],
    "trendingGeos": ["US"],
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("pampa-data/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": [
    "yerba mate",
    "bitcoin, ethereum"
  ],
  "trendingGeos": [
    "US"
  ],
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call pampa-data/google-trends-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,pampa-data/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/qLliBHfuV16vuSE7P/builds/iWMFjfbX2eSLPGG0n/openapi.json