# Google Trends Scraper & API — Rising Queries, Regions (`engineertsaistudio/google-trends-reliable-scraper`) Actor

Google Trends data for any keyword: interest over time, by country/region/city/metro, top and rising (Breakout) related queries and topics. Compare up to 5 terms. Failed keywords are free.

- **URL**: https://apify.com/engineertsaistudio/google-trends-reliable-scraper.md
- **Developed by:** [Studio EngineerTsai](https://apify.com/engineertsaistudio) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 keyword reports

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?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Google Trends Scraper & API — Rising Queries, Regions

Get **Google Trends data for any keyword** as JSON, CSV or Excel: **interest over time**, **interest by
region** (country, state, city or US metro), **related queries** (top and rising, including "Breakout")
and **related topics**. One keyword = one complete report row.

**Choose this Actor when** you need all four Google Trends sections for a list of keywords in one run,
on a schedule, without handling Google's rate limits yourself — and you only want to pay for reports
that actually came back.

**Not the right fit when** you need absolute search volumes (Google Trends publishes relative 0–100
interest only) or the "Trending now" daily feed (this Actor analyses keywords you supply).

### Use cases

- **SEO and content planning** — find rising queries and Breakout terms before they peak.
- **Product and market research** — compare brands or products over time and across countries.
- **E-commerce** — see seasonality in Google Shopping searches (`searchProperty: "froogle"`).
- **YouTube and news topics** — switch `searchProperty` to `youtube` or `news`.
- **Analytics and investing** — use relative search interest as an alternative data signal.
- **Automation** — schedule weekly runs and push rows to Google Sheets, Slack, Make, Zapier or n8n.

### How failures are handled

Google Trends rate-limits aggressively. On HTTP 429 or a server error the Actor switches to a new
session and a new residential IP and backs off exponentially before retrying. A keyword that still
fails after all retries is saved with `status: "error"` and an `error` message so you can see it — and
it is **not charged**.

### Input example

```json
{
  "keywords": ["n8n", "zapier"],
  "compareKeywords": true,
  "geo": "US",
  "timeRange": "today 12-m",
  "searchProperty": "",
  "regionResolution": "REGION",
  "includeRelatedQueries": true,
  "includeRelatedTopics": true
}
```

| Input | What it does | Example |
|---|---|---|
| `keywords` | Terms to look up (required) | `["n8n", "zapier"]` |
| `compareKeywords` | Put up to 5 keywords on one shared scale, like the Trends compare view | `true` |
| `geo` | Country or region code; empty = worldwide | `US`, `TW`, `US-CA` |
| `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` | `today 12-m` |
| `customTimeRange` | Overrides `timeRange` | `2025-01-01 2025-06-30` |
| `searchProperty` | empty = web, `images`, `news`, `froogle` (Shopping), `youtube` | `news` |
| `category` | Google Trends category ID, 0 = all | `0` |
| `regionResolution` | `COUNTRY`, `REGION`, `CITY`, `DMA`, or empty = automatic | `REGION` |
| `includeInterestOverTime` / `includeInterestByRegion` / `includeRelatedQueries` / `includeRelatedTopics` | Switch sections on or off | `true` |
| `language` | Language for topic names | `en-US`, `zh-TW` |

Residential proxy is on by default; Google blocks datacenter IPs quickly.

### Output example (shortened)

```json
{
  "keywords": ["n8n"],
  "geo": "US",
  "timeRange": "today 12-m",
  "property": "web",
  "status": "ok",
  "interestOverTime": [
    { "date": "…", "timestamp": 1757808000, "values": { "n8n": 41 }, "isPartial": false }
  ],
  "interestByRegion": [
    { "geoCode": "US-CA", "geoName": "California", "values": { "n8n": 100 } }
  ],
  "relatedQueries": {
    "top": [{ "query": "…", "value": 100, "formattedValue": "100" }],
    "rising": [{ "query": "…", "value": 4250, "formattedValue": "Breakout" }]
  },
  "relatedTopics": {
    "top": [{ "title": "…", "type": "Topic", "mid": "…", "value": 100, "formattedValue": "100" }],
    "rising": []
  }
}
```

### Pricing

**$5 per 1,000 successful keyword reports**.

One report = one keyword (or one compare group of up to 5 keywords) with all sections you switched on.
Failed keywords are free. Platform usage and residential proxy are included — nothing is billed on top.
Example: 250 keywords = $1.25. Set a maximum cost per run for a hard cap.

### FAQ

**Are the values search volumes?** No. Google Trends reports relative interest (0–100) within the chosen
time range and location.

**Why do numbers differ slightly between runs?** Google samples its data; small differences are normal,
especially for low-volume keywords.

**What does "Breakout" mean?** A related query grew by more than 5,000% in the period; `value` holds the
growth number and `formattedValue` shows "Breakout".

**Do compared keywords cost more?** No. A compare group of up to 5 keywords is one report.

**Can I get city or US metro (DMA) data?** Yes — set `regionResolution` to `CITY` or `DMA`.

**Is scraping Google Trends legal?** The Actor collects aggregated, anonymous statistics that Google
publishes publicly and no personal data. You are responsible for using the data in line with applicable
laws and Google's terms.

**Something not working?** Open an issue on the Issues tab and include your run ID.

# Actor input Schema

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

Search terms to look up. Each keyword becomes one report unless 'Compare keywords' is on.

## `compareKeywords` (type: `boolean`):

Put keywords into the same chart (up to 5 per report), like Google Trends' compare view. Values are then relative to each other.

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

Two-letter country code (e.g. US, GB, TW) or region code (e.g. US-CA). Leave empty for worldwide.

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

Period to analyze. Ignored when a custom time range is set.

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

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

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

Which Google search surface to analyze.

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

Google Trends category ID. 0 = all categories.

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

Relative search interest (0-100) for each week/day/hour in the time range.

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

Relative search interest broken down by country, region, city or metro area.

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

Geographic level for interest by region. Automatic picks the next level below Location.

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

Top and rising search queries related to each keyword.

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

Top and rising topics related to each keyword.

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

Language code for topic names, e.g. en-US, zh-TW, de-DE.

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

Google rate-limits datacenter IPs. Residential proxy is recommended for reliability.

## Actor input object example

```json
{
  "keywords": [
    "n8n",
    "zapier"
  ],
  "compareKeywords": false,
  "geo": "",
  "timeRange": "today 12-m",
  "searchProperty": "",
  "category": 0,
  "includeInterestOverTime": true,
  "includeInterestByRegion": true,
  "regionResolution": "",
  "includeRelatedQueries": true,
  "includeRelatedTopics": true,
  "language": "en-US",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# 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 = {
    "keywords": [
        "n8n",
        "zapier"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("engineertsaistudio/google-trends-reliable-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": [
        "n8n",
        "zapier",
    ],
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("engineertsaistudio/google-trends-reliable-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": [
    "n8n",
    "zapier"
  ],
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}' |
apify call engineertsaistudio/google-trends-reliable-scraper --silent --output-dataset

```

## MCP server setup

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