# Google Trends Batch Scraper - Rising Queries & YouTube Trends (`criatolabs/google-trends-batch-scraper`) Actor

Analyze up to 1,000 keywords in one run with no start fee. Interest over time, 5-term comparisons, rising related queries & topics, interest by region, YouTube/News/Shopping search trends and real-time trending searches.

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

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

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

## 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 Batch Scraper: keywords, comparisons, rising queries and YouTube trends

Analyze **up to 1,000 keywords in a single run**, with **no Actor fee**: you only pay Apify platform usage (about **$0.16 per 1,000 keywords** in our tests, residential proxy included). No Google API key and no proxies for you to manage.

Each keyword returns:

- 📈 **Interest over time**, with a ready-made summary: average, peak, latest value, % change and direction (rising, falling or stable)
- 🚀 **Rising and top related queries and topics**, including the "Breakout" searches SEO teams look for
- ⚖️ **Comparisons of up to 5 terms** on a shared 0–100 scale, just like the Google Trends website
- ▶️ **YouTube, News, Image and Shopping search trends**, not just web search
- 🗺️ **Interest by country, state, city or US metro**
- 🔥 **Real-time trending searches** (top 10 per country), with approximate traffic and related news

### Why this Actor

| | This Actor |
|---|---|
| Keywords per run | Up to 1,000 |
| Actor fee | None, you pay platform usage only |
| Typical cost | ~$0.16 per 1,000 keywords (tested) |
| Comparisons (up to 5 terms) | ✅ |
| Rising / breakout queries | ✅ |
| YouTube / News / Shopping trends | ✅ |
| Success rate | 500/500 keywords in our test run |

**What it costs in practice.** In our test, 500 keywords with related queries ran in 11 minutes for $0.079 of platform usage (compute + residential proxy). Your exact cost depends on your Apify plan.

### Use cases

- **SEO and content.** Find rising queries before they peak and check seasonality before you publish.
- **YouTube creators and agencies.** Set *Search type* to *YouTube Search* to see what people actually search for on YouTube.
- **Market research and e-commerce.** Compare brands or products with Shopping search trends and see where demand is concentrated by region.
- **AI agents and automations.** Every item has flat summary fields (`average`, `changePct`, `direction`, `risingQueries`), so an agent can answer "is X trending?" without parsing a time series.

### Input

```json
{
  "keywords": ["air fryer", "standing desk", "protein coffee"],
  "comparisons": ["chatgpt, claude ai, gemini"],
  "trendingCountries": ["US", "GB"],
  "geo": "US",
  "timeframe": "today 12-m",
  "searchProperty": "web",
  "includeRelated": true,
  "includeRegions": false
}
```

| Field | What it does |
|---|---|
| `keywords` | Analyzes each term on its own 0–100 scale |
| `comparisons` | Each line holds up to 5 comma-separated terms, compared on one scale |
| `trendingCountries` | Returns what's trending right now in each country (US, BR, IN…) |
| `geo` | Country (`US`) or subregion (`US-CA`). Leave empty for worldwide |
| `timeframe` / `customTimeRange` | From the past hour to 2004–present, or a custom range like `2025-01-01 2025-06-30` |
| `searchProperty` | `web`, `youtube`, `news`, `images` or `shopping` |
| `category` | Google Trends category ID (0 = all) |
| `includeRelated` | Adds top and rising related queries and topics |
| `includeRegions` | Adds interest by region (free) |

### Output

One item per keyword, comparison or trending search. A keyword item looks like this:

```json
{
  "type": "keyword",
  "keyword": "air fryer",
  "geo": "US",
  "timeframe": "today 12-m",
  "property": "web",
  "status": "ok",
  "average": 61.4,
  "peak": 100,
  "peakDate": "2025-11-23T00:00:00Z",
  "latest": 58,
  "changePct": 12.5,
  "direction": "rising",
  "risingQueries": ["air fryer recipes chicken", "ninja crispi"],
  "topQueries": ["best air fryer", "air fryer recipes"],
  "timeline": [{ "date": "2024-11-03T00:00:00Z", "values": { "air fryer": 54 }, "isPartial": false }],
  "related": { "air fryer": { "queries": { "top": [], "rising": [] }, "topics": { "top": [], "rising": [] } } },
  "trendsUrl": "https://trends.google.com/trends/explore?q=air+fryer&date=today+12-m&geo=US"
}
```

`status` is one of three values:

- `ok`: data was returned.
- `no_data`: Google has too little search volume for the term.
- `failed`: the request failed after all retries.

### Pricing

This Actor has no fee of its own: you pay only Apify platform usage, meaning compute and residential proxy, which is billed to your Apify account. In our test, 500 keywords with related queries cost $0.079. Use the run options to set a timeout or memory limit if you want to cap a run.

### Tips

- Google Trends values are relative: 100 means peak popularity for that term in that period. Use `comparisons` when you need terms on the same scale.
- For hourly timeframes (`now 1-H`, `now 4-H`), data points are minutes.
- Large batches run in parallel with automatic IP rotation. The run summary (`RUN_SUMMARY` in the key-value store) shows how many blocks were handled.

### More YouTube and trends tools from Criato Labs

- [YouTube Channel & Video Scraper](https://apify.com/criatolabs/youtube-channel-scraper): channel profiles, videos, Shorts and keyword search
- [YouTube Comments Scraper](https://apify.com/criatolabs/youtube-comments-scraper): comments and replies from any video or Short
- [YouTube Transcript Scraper](https://apify.com/criatolabs/youtube-transcript-scraper): transcripts of videos or whole channels

### FAQ

**Is scraping Google Trends legal?** This Actor only reads publicly available, aggregated and anonymized search-interest data. It collects no personal data. Check your local regulations and Google's terms for your use case.

**Why do some keywords return `no_data`?** Google only shows terms with enough search volume. Try a broader location or a longer time range.

**Can I use it from an AI agent?** Yes, through the Apify MCP server. Each item has flat summary fields that an agent can read directly.

# Actor input Schema

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

Each keyword is analyzed on its own 0-100 scale. Up to 1,000 terms per run, all in a single run.

## `comparisons` (type: `array`):

Each line is compared on a shared 0-100 scale, exactly like the Google Trends website. Example: 'iphone, samsung galaxy, pixel'.

## `trendingCountries` (type: `array`):

Two-letter country codes (US, BR, GB, IN...). Returns the top trending searches right now in each country (up to 10 per country), with approximate traffic and related news.

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

Country (US, BR) or subregion (US-CA, BR-SP) for keywords and comparisons. Leave empty for worldwide.

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

Period for keywords and comparisons.

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

Format: 'YYYY-MM-DD YYYY-MM-DD', e.g. '2025-01-01 2025-06-30'.

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

Which Google search to measure. 'YouTube Search' shows what people search for on YouTube.

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

Google Trends category (0 = all categories). Examples: 3 = Arts & Entertainment, 5 = Computers & Electronics, 7 = Finance, 45 = Health, 71 = Food & Drink.

## `includeRelated` (type: `boolean`):

Adds the 'Top' and 'Rising' related queries and topics for each term (the breakout searches SEO teams look for).

## `maxRelatedPerList` (type: `integer`):

Limit for each of the top/rising lists.

## `includeRegions` (type: `boolean`):

Adds interest by country/state/city (free, no extra charge).

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

Granularity for 'Include interest by region'. Automatic picks country (worldwide), state (country) or city (subregion).

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

Language for topic names and labels, e.g. en-US, pt-BR, es-ES.

## `maxTrendingPerCountry` (type: `integer`):

Google's real-time trending feed lists up to 10 current trends per country.

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

Google limits each IP to a handful of Trends queries. Residential proxy is the default (tested: 500 keywords, 0 failures). The Actor rotates IPs automatically.

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

How many queries run in parallel, each on its own IP.

## `maxRequestsPerIp` (type: `integer`):

Google starts blocking an IP after roughly 10-15 queries.

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

How many times a blocked request is retried on a fresh IP before the term is marked as failed (failures are free).

## Actor input object example

```json
{
  "keywords": [
    "chatgpt",
    "claude ai",
    "gemini"
  ],
  "comparisons": [
    "chatgpt, claude ai, gemini"
  ],
  "geo": "",
  "timeframe": "today 12-m",
  "searchProperty": "web",
  "category": 0,
  "includeRelated": true,
  "maxRelatedPerList": 25,
  "includeRegions": false,
  "regionResolution": "AUTO",
  "language": "en-US",
  "maxTrendingPerCountry": 10,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  },
  "maxConcurrency": 8,
  "maxRequestsPerIp": 8,
  "maxRetries": 8
}
```

# Actor output Schema

## `overview` (type: `string`):

Interest over time, summary (average, peak, change %, direction), related and rising queries/topics and regions for each keyword or comparison.

## `trending` (type: `string`):

Real-time trending searches per country with approximate traffic and related news.

## `runSummary` (type: `string`):

Counts of ok / no data / failed jobs, IP rotations and blocks handled.

# 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 = {
    "keywords": [
        "chatgpt",
        "claude ai",
        "gemini"
    ],
    "comparisons": [
        "chatgpt, claude ai, gemini"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("criatolabs/google-trends-batch-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 = {
    "keywords": [
        "chatgpt",
        "claude ai",
        "gemini",
    ],
    "comparisons": ["chatgpt, claude ai, gemini"],
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("criatolabs/google-trends-batch-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 '{
  "keywords": [
    "chatgpt",
    "claude ai",
    "gemini"
  ],
  "comparisons": [
    "chatgpt, claude ai, gemini"
  ],
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}' |
apify call criatolabs/google-trends-batch-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,criatolabs/google-trends-batch-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/P2bsqOe2JYkxSr7dA/builds/dxcugKJ3rFmGffVVK/openapi.json