# Google Trends Scraper & Reliable Trends API (`zenomastro/google-trends-reliable`) Actor

Extract Google Trends keyword interest, regions, related searches, topics, and Trending Now data with bounded retries and normalized output.

- **URL**: https://apify.com/zenomastro/google-trends-reliable.md
- **Developed by:** [Rosario Vitale](https://apify.com/zenomastro) (community)
- **Categories:** Developer tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.25 / 1,000 google trends result rows

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 Reliable API

Fast, structured Google Trends data for SEO, research, content discovery, and market analysis.

This Actor supports two workflows:

- **Keyword analysis** — compare up to five terms and extract interest over time, interest by region, related queries, and related topics.
- **Trending now** — fetch current Google trending searches for a selected country.

The Actor is designed to **finish cleanly instead of hanging**. Temporary Google errors use bounded retries, request timeouts, cookie warm-up, and optional proxy rotation.

### Why use this Actor?

Many Google Trends scrapers fail in ways that waste time: endless retries, empty runs with no explanation, inconsistent output, or rate-limit errors.

This Actor is built around predictable behavior:

- Strict input validation before any expensive work starts
- Bounded retries for HTTP 403/408/429/5xx responses
- Configurable per-request timeout
- Cookie/session warm-up before Google Trends API calls
- Optional Apify/custom proxy support
- Normalized dataset rows for JSON, CSV, Excel, and API use
- Clean success with zero rows when Google legitimately returns an empty section
- No browser required for the normal data path

### Keyword analysis

Example input:

```json
{
  "mode": "explore",
  "keywords": ["bitcoin", "ethereum"],
  "geo": "US",
  "timeRange": "today 3-m",
  "property": "",
  "includeInterestOverTime": true,
  "includeInterestByRegion": true,
  "includeRelatedQueries": true,
  "includeRelatedTopics": true
}
```

Supported Google properties:

- Web Search
- Image Search
- News Search
- YouTube Search
- Google Shopping

Common time ranges include `today 3-m`, `today 12-m`, `today 5-y`, and `all`. Custom Google Trends date ranges can also be supplied.

### Trending now

Example input:

```json
{
  "mode": "trending",
  "geo": "US",
  "trendingLimit": 50
}
```

Trending rows include the search term, approximate traffic, publication time, source URL, image when available, and related news items.

### Output

The default Dataset uses normalized row types:

- `interest_over_time` — one row per time point with values for each compared keyword
- `interest_by_region` — one row per region with values for each compared keyword
- `related_query` — top/rising related searches
- `related_topic` — top/rising related topics when Google provides them
- `trending` — current trending searches

Google may legitimately omit related topics or other optional sections for some terms. That is treated as a valid empty result, not as a failed run.

### Reliability controls

Use `requestTimeoutSecs` and `retries` to control how aggressively the Actor waits for Google. Defaults are intentionally conservative: 20 seconds per request and 3 attempts.

If Google rate-limits your traffic, enable `proxyConfiguration`. The Actor can rotate through multiple Apify/custom proxy sessions between retries.

### Important notes about Google Trends data

Google Trends values are normalized interest scores, typically on a 0–100 scale. They are **not absolute monthly search volumes**.

Comparing multiple keywords in one request is usually preferable to running separate requests because Google normalizes the compared terms against the same time/geo context.

Google Trends is an external service with undocumented internal endpoints. This Actor uses defensive parsing and bounded failures, but Google can change its responses without notice.

### Good use cases

- SEO keyword comparison
- Content and editorial research
- Brand or product demand tracking
- Regional market research
- YouTube search trend analysis
- News/topic discovery
- Scheduled trend monitoring
- Data pipelines through the Apify API

### Support

If a run fails, include the run ID, input, and the final error message. Do not include private API tokens or proxy passwords in issue reports.

# Actor input Schema

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

Analyze keywords or fetch current trending searches.

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

One to five terms to compare in Google Trends Explore.

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

Country/region code such as US, IT, GB. Leave blank for worldwide Explore data.

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

Examples: today 3-m, today 12-m, today 5-y, all, or a custom date range.

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

Google Trends category ID. Use 0 for all categories.

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

Search surface to analyze.

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

Google Trends interface locale, for example en-US or it-IT.

## `timezoneMinutes` (type: `integer`):

Timezone offset in minutes used by Google Trends.

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

Return the time series.

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

Return regional interest data.

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

Return top and rising related searches.

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

Return top and rising related topics.

## `maxRelated` (type: `integer`):

Maximum top/rising related items returned per widget.

## `trendingLimit` (type: `integer`):

Maximum Trending Now rows.

## `requestTimeoutSecs` (type: `integer`):

Maximum seconds per Google request before retrying.

## `retries` (type: `integer`):

Maximum attempts for temporary Google errors.

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

Optional proxy rotation for rate-limited requests. Direct access is used by default.

## Actor input object example

```json
{
  "mode": "explore",
  "keywords": [
    "bitcoin",
    "ethereum"
  ],
  "geo": "US",
  "timeRange": "today 3-m",
  "category": 0,
  "property": "",
  "language": "en-US",
  "timezoneMinutes": 0,
  "includeInterestOverTime": true,
  "includeInterestByRegion": true,
  "includeRelatedQueries": true,
  "includeRelatedTopics": true,
  "maxRelated": 25,
  "trendingLimit": 50,
  "requestTimeoutSecs": 20,
  "retries": 3,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

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

No description

# 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("zenomastro/google-trends-reliable").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("zenomastro/google-trends-reliable").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 zenomastro/google-trends-reliable --silent --output-dataset

```

## MCP server setup

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

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/xfyDZYtaNo07Mq0wF/builds/QNEIddIlZGRD47Ob6/openapi.json