# Reliable Google Trends API (`eligible_fame/reliable-google-trends`) Actor

Google Trends scraper & pytrends alternative without 429 errors: interest over time, by region, related & rising queries for up to 5 keywords; web, YouTube, News, Images, Shopping. Proxy rotation, retries, ok/partial/failed status. Failed & invalid queries free. MCP-ready.

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

## Pricing

from $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

## Reliable Google Trends API: Google Trends Scraper & pytrends Alternative (No 429 Errors)

**Reliable Google Trends API** gets Google Trends data without the 429 errors: **interest over time, interest by region, related queries and related topics** for up to 5 compared keywords per query. It covers Web Search, YouTube, Google News, Images and Shopping. Use it as a drop-in **pytrends alternative** or a **Google Trends scraper** from Python, Node.js, cURL, n8n, Make or Zapier. Every query comes back with an explicit `ok` / `partial` / `failed` status, never a silent empty row, and **failed queries are free**.

### What does Reliable Google Trends API do?

- **Interest over time:** 0–100 timeline for 1–5 keywords, for any timeframe (`now 7-d`, `today 12-m`, `today 5-y`, `all`, or `2024-01-01 2024-12-31`).
- **Interest by region:** country, region (state), metro (DMA) or city breakdown.
- **Related queries:** top and rising (breakout) searches for each keyword.
- **Related topics:** optional. Google often withholds these from automated sessions, so they're off by default, and the row is marked `partial` if they're missing.
- **Comparisons and filters:** geo (`US`, `GB`, `US-CA` …), category, and property (web / youtube / news / images / froogle).
- **Bulk keywords:** send hundreds of queries in one run. Each one is retried independently.

### Why is it more reliable?

pytrends is archived and often fails with `429 Too Many Requests`. This Actor handles that for you with:

- Cookie warmup and token refresh
- Rotating Apify Proxy sessions, with a new session after each block
- Per-widget retries with backoff
- Automatic residential-proxy fallback when datacenter IPs keep getting blocked

**Measured results (34-query gate runs on the Apify platform, including repeated queries):**

| Mode | Success | Platform cost per run |
|---|---|---|
| Datacenter proxy only | 34/34 (100%) | $0.0017 |
| Datacenter + residential fallback (default) | 34/34 (100%) | $0.0013 |
| Residential forced | 34/34 (100%) | ~$0.0067 |

Local testing also passed: 70 of 70 queries. Every run writes a `RUN_SUMMARY` record to the key-value store with the success rate and the counts of blocks and retries.

### Pricing (pay per event)

- **$0.02** per run start at the default 1 GB memory (Apify charges the start event per GB of memory)
- **$0.002 per successful trend result.** One result is one query with every section you asked for, covering up to 5 compared keywords. That works out to **$2 per 1,000 queries**.
- **Failed queries cost $0.**

You pay only for data you receive. Platform usage is included.

### Quick start

Input:

```json
{
  "searchTerms": ["coffee", "chatgpt, claude, gemini"],
  "geo": "US",
  "timeframe": "today 12-m",
  "property": "web",
  "interestOverTime": true,
  "interestByRegion": true,
  "relatedQueries": true
}
```

Each `searchTerms` entry is one query; separate keywords with commas to compare up to 5. To set different options for each query, use `customQueries`:

```json
{ "customQueries": [ { "keywords": "bitcoin, ethereum", "geo": "GB", "timeframe": "today 5-y", "property": "news" } ] }
```

### Output example

```json
{
  "row_type": "result",
  "status": "ok",
  "keywords": ["coffee"],
  "query": { "geo": "", "timeframe": "today 12-m", "category": 0, "property": "web" },
  "interest_over_time": [
    { "time": "2025-10-12T00:00:00+00:00", "values": { "coffee": 60 }, "is_partial": false }
  ],
  "interest_by_region": [
    { "geo_code": "SG", "geo_name": "Singapore", "values": { "coffee": 100 } }
  ],
  "related_queries": {
    "coffee": {
      "top": [ { "query": "best coffee", "value": 100 } ],
      "rising": [ { "query": "...", "formatted_value": "+2,400%" } ]
    }
  },
  "errors": []
}
```

You can export the data as JSON, CSV, Excel, XML or RSS, or pull it through the API.

### API & integration examples

**Python**

```python
from apify_client import ApifyClient
client = ApifyClient("<APIFY_TOKEN>")
run = client.actor("eligible_fame/reliable-google-trends").call(run_input={
    "searchTerms": ["air fryer, instant pot"], "geo": "US", "timeframe": "today 5-y"})
for row in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(row["status"], row["keywords"], len(row.get("interest_over_time", [])))
```

**Node.js**

```js
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('eligible_fame/reliable-google-trends').call({ searchTerms: ['coffee'], geo: 'GB' });
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items[0].interest_over_time);
```

**cURL (synchronous run that returns dataset items)**

```bash
curl -X POST "https://api.apify.com/v2/acts/eligible_fame~reliable-google-trends/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"searchTerms":["coffee, tea"],"geo":"US","timeframe":"today 3-m"}'
```

**No-code:** use the Apify app in **n8n, Make or Zapier**: Run Actor, then Get dataset items. You can also schedule a daily run in Apify Schedules and use a webhook to send the results to Google Sheets, Slack or your database.

### Use it from AI agents and MCP clients (Claude, Cursor, ChatGPT, n8n AI Agent)

Give an LLM agent fresh Google Trends data through **Apify's MCP server** (`https://mcp.apify.com`). The agent passes keywords, gets back the timeline, regions and rising queries as JSON, and can then reason over them: "is interest in 'air fryer' still growing in the UK?"

**Add only this Actor as an MCP tool** (Claude Desktop, Cursor, VS Code, Windsurf):

```json
{
  "mcpServers": {
    "google-trends": { "url": "https://mcp.apify.com?tools=eligible_fame/reliable-google-trends" }
  }
}
```

On first connection the client opens an Apify sign-in (OAuth). Alternatively add the header `"Authorization": "Bearer <APIFY_TOKEN>"`. With the default server the agent can also find it with `search-actors` ("google trends") and run it via `call-actor`.

**Prompt examples for an agent**

- "Use reliable-google-trends to compare 'chatgpt, claude, gemini' worldwide over today 12-m and summarise who is gaining."
- "Get rising related queries for 'protein coffee' in US over now 7-d and suggest 5 blog titles."

**Tips for agents**

- One query = up to 5 comma-separated keywords. Values are relative (0–100) within that query.
- Switch off sections you don't need (`interestByRegion: false`) for faster runs; the price per successful query stays the same.
- Each row has `status` (`ok` / `partial` / `failed`) and an `errors` list. `failed` rows and `error` rows are free.
- Set `maxTotalChargeUsd` in the MCP `callOptions` to cap spend. Pay-per-event pricing also supports Apify **agentic payments** (e.g. Skyfire).

### Input validation (what you are and aren't charged for)

- Invalid queries (unknown timeframe like "last week", geo written out as "United States", an empty line, a non-object in `customQueries`) produce a free `row_type: "error"` row (`status: "invalid"`) with code `INVALID_QUERY` and a fix-it message. Valid queries in the same run still run.
- If no query is usable, or every output section is switched off, the run stops with `INVALID_INPUT` before any result is charged.
- Common mistakes are fixed automatically: `searchTerms` sent as one text block, more than 5 terms (the first 5 are kept), numbers sent as strings, `keywords` used instead of `searchTerms`.

### Use cases

- SEO and content: find keyword seasonality and rising queries.
- E-commerce and dropshipping: validate products and compare demand across countries.
- Market research and investing: track brand demand and compare competitors.
- Data science: build time-series features for forecasting.
- AI agents: give an LLM fresh Trends data through the API or MCP.

### FAQ

**Is this an official Google Trends API?** No. Google's official Trends API is in invite-only alpha. This Actor reads the same public data you see at trends.google.com.

**Why are values 0–100 and not search volumes?** Google Trends only publishes relative interest. 100 is the peak inside your query's time and geo window. Only compare keywords that were in the same query.

**What happens when Google blocks a request?** The Actor rotates to a new proxy session, refreshes tokens and retries. If retries keep failing, it falls back to residential proxies. If a query still fails, it's marked `failed` and you aren't charged.

**Can I migrate from pytrends?** Yes. `build_payload` + `interest_over_time()` becomes `searchTerms` + `interestOverTime`. The timeframe, geo and category (`cat`) values use the same format.

**Does it use captcha solving?** No. It only uses normal proxy rotation and retries.

**Is scraping Google Trends legal?** The Actor collects publicly available, aggregated, non-personal data. You're responsible for how you use it under Google's terms and the laws that apply to you.

# Actor input Schema

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

One query per line. Comma-separate up to 5 terms on a line to COMPARE them (e.g. 'chatgpt, claude, gemini'). Uses the default geo/timeframe/category/property below. Invalid queries (bad timeframe/geo, empty) return a free error row and are never charged.

## `customQueries` (type: `array`):

Optional JSON array for per-query overrides, e.g. \[{"keywords":"bitcoin, ethereum","geo":"US","timeframe":"today 5-y","category":7,"property":"news"}]

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

Country or region code: '' = worldwide, US, GB, US-CA, DE-BY …

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

Trends time syntax: '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 'YYYY-MM-DD YYYY-MM-DD'.

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

Google Trends category ID (0 = all). E.g. 7 Finance, 31 Programming, 71 Food & Drink.

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

Which Google search surface.

## `interestOverTime` (type: `boolean`):

Include the time series.

## `interestByRegion` (type: `boolean`):

Include the regional breakdown.

## `relatedQueries` (type: `boolean`):

Include top & rising related queries.

## `relatedTopics` (type: `boolean`):

Top & rising related topics. NOTE: Google currently withholds topics from automated sessions; when empty the row is marked partial.

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

Granularity for interest by region. Empty = Google's default for the geo.

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

Interface language for labels, e.g. en-US, de.

## `timezoneOffsetMinutes` (type: `integer`):

Google's tz parameter (minutes WEST of UTC; e.g. 0 = UTC, -480 = Singapore).

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

Apify Proxy strongly recommended. Sessions rotate automatically on rate limits.

## `residentialFallback` (type: `boolean`):

After repeated blocks on datacenter IPs, switch new sessions to Apify residential proxy (included in the price).

## `residentialAfterBlocks` (type: `integer`):

Consecutive blocks before switching to residential sessions.

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

Independent sessions working in parallel.

## `maxAttempts` (type: `integer`):

Retries (each on a fresh session) before a section is marked failed.

## `minDelaySecs` (type: `number`):

Polite pacing between requests within a session.

## Actor input object example

```json
{
  "searchTerms": [
    "coffee",
    "chatgpt, claude, gemini"
  ],
  "geo": "",
  "timeframe": "today 12-m",
  "category": 0,
  "property": "web",
  "interestOverTime": true,
  "interestByRegion": true,
  "relatedQueries": true,
  "relatedTopics": false,
  "regionResolution": "",
  "language": "en-US",
  "timezoneOffsetMinutes": 0,
  "proxyConfiguration": {
    "useApifyProxy": true
  },
  "residentialFallback": true,
  "residentialAfterBlocks": 3,
  "maxConcurrency": 3,
  "maxAttempts": 6,
  "minDelaySecs": 1.5
}
```

# Actor output Schema

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

One row per query with interest over time, by region, related queries and topics.

## `allRows` (type: `string`):

Full rows including nested arrays.

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

Success rate, requests, retries and sessions for the run.

# 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": [
        "coffee",
        "chatgpt, claude, gemini"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("eligible_fame/reliable-google-trends").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": [
        "coffee",
        "chatgpt, claude, gemini",
    ],
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("eligible_fame/reliable-google-trends").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": [
    "coffee",
    "chatgpt, claude, gemini"
  ],
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call eligible_fame/reliable-google-trends --silent --output-dataset

```

## MCP server setup

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

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/E2rQQes5vep6dya8q/builds/gbkn1LRCzXzCgxjXu/openapi.json