# Google Trends Scraper - Interest, Regions & Rising Queries (`clearscrape/google-trends-keyword-scraper`) Actor

Google Trends for any keywords: interest over time, interest by country/region/metro/city, top and rising related queries. Any geo, timeframe, Web/YouTube/News/Images/Shopping. Compare up to 5 keywords. $1.50 per 1,000 keyword reports, no start fee.

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

## Pricing

from $1.50 / 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?

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 - Interest, Regions & Rising Queries

Pull **Google Trends** data for any list of keywords: **interest over time**, **interest by country / region / metro / city**, and **top and rising related queries**. Any location, any timeframe (past hour to 2004+, or custom dates), and Web, YouTube, News, Images or Google Shopping search. Compare up to 5 keywords like the Trends compare view. **$1.50 per 1,000 keyword reports**, with no start fee and no charge for failed keywords.

### What it does

For every keyword × location × timeframe you get **one report** with everything Google Trends shows for it:

- **Interest over time:** the full 0–100 series (hourly, daily, weekly or monthly depending on the timeframe), with partial-period flags, plus average, latest and peak.
- **Interest by region:** countries for worldwide, states/regions for a country, or force COUNTRY, REGION, DMA (US metros) or CITY.
- **Related queries:** top and **rising** searches. Rising queries are the go-to source for spotting breakout keywords early.
- **Compare mode:** up to 5 keywords in one Trends request, so their values are relative to each other.
- **Search types:** Web, YouTube, News, Images, Google Shopping. Optional category filter (e.g. 71 Food & Drink).
- **Timeframes:** past_hour, past_4_hours, past_day, past_7_days, past_30_days, past_90_days, past_12_months, past_5_years, all, or `YYYY-MM-DD YYYY-MM-DD`.
- **Reliable:** randomised pacing, fresh sessions and backoff on Google's rate limits (HTTP 429), and automatic datacenter-proxy fallback. A missing optional section (e.g. region data for a tiny geo) never loses the rest of the report.

### Use cases

- **SEO and content:** find rising queries before competitors and plan content around seasonality.
- **E-commerce / print-on-demand / Etsy:** validate product ideas and time launches with Shopping and YouTube trends.
- **Market research:** compare brands, products or topics across countries and states.
- **Data science and dashboards:** clean JSON time series ready for pandas, BigQuery or Sheets.
- **AI agents:** one call returns a compact, structured report per keyword.

### Input example

```json
{
  "keywords": ["matcha", "chai latte", "cold brew"],
  "geos": ["US", "AU"],
  "timeframes": ["past_12_months"],
  "searchProperty": "web",
  "includeInterestByRegion": true,
  "includeRelatedQueries": true
}
```

### Output example

```json
{
  "keyword": "matcha",
  "geo": "US",
  "timeframe": "today 12-m",
  "searchProperty": "web",
  "averageInterest": 74.93,
  "latestInterest": 64,
  "peakInterestDate": "2026-04-12T00:00:00Z",
  "interestOverTime": [{ "date": "2025-10-19T00:00:00Z", "formattedTime": "Oct 19 – 25, 2025", "value": 71, "isPartial": false }],
  "interestByRegion": [{ "geoCode": "US-HI", "geoName": "Hawaii", "value": 100 }],
  "regionResolution": "REGION",
  "relatedQueriesTop": [{ "query": "matcha latte", "value": 100, "formattedValue": "100" }],
  "relatedQueriesRising": [{ "query": "strawberry matcha", "value": 350, "formattedValue": "+350%" }],
  "trendsUrl": "https://trends.google.com/trends/explore?date=today%2012-m&geo=US&q=matcha",
  "warnings": [],
  "scrapedAt": "2026-10-18T04:45:00Z"
}
```

### Pricing (pay per event)

- **$1.50 per 1,000 keyword reports** (one report = one keyword × location × timeframe, including every section you select).
- No start fee. Keywords that fail are not charged.
- Compare mode doesn't cost extra: 5 compared keywords = 5 reports.

### FAQ

**Why are values 0–100?** Google Trends normalises interest to the peak within the request. Use compare mode when you need keywords on the same scale.

**Related topics?** Google does not return related topics to automated clients, so this Actor only offers related queries rather than shipping an empty field.

**Interest by region is empty for some inputs.** For small sub-national locations or very short timeframes, Google often has no regional breakdown (it shows "not enough data" on the website too). The report keeps everything else and notes it in `warnings`.

**I got rate-limited.** Google Trends limits request volume per IP. Keep concurrency at 1–2. The Actor backs off and switches to Apify datacenter proxy automatically. For very large batches, enable Apify Proxy (or the residential fallback).

### Daily health check

A one-keyword self-test runs daily on Apify. If Google changes its Trends API, the Actor gets flagged and fixed quickly.

### Legal and fair-use notes

The Actor uses the public JSON endpoints under `trends.google.com/trends/api/`, the same ones the Trends website loads. They are not disallowed by Google's robots.txt (only the `/explore?` HTML pages are). It collects aggregated, anonymised search-interest data, no personal data. Google's Terms of Service restrict automated access; you are responsible for how you use the data.

# Actor input Schema

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

Search terms to analyse. Each keyword x geo x timeframe gives one report (unless you compare keywords).

## `geos` (type: `array`):

Country or region codes: US, AU, GB, AU-NSW, US-CA... Leave one empty line or 'WORLDWIDE' for worldwide.

## `timeframes` (type: `array`):

past_hour, past_4_hours, past_day, past_7_days, past_30_days, past_90_days, past_12_months, past_5_years, all, or a custom range 'YYYY-MM-DD YYYY-MM-DD'.

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

Which Google search to analyse.

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

Google Trends category (0 = all categories; e.g. 71 Food & Drink, 18 Shopping, 958 Jobs).

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

Query keywords together in groups of up to 5, so values are relative to each other (like the Trends compare view). Each keyword still gets its own report.

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

Add the interest-by-location breakdown.

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

Auto = countries for worldwide, sub-regions for a country. Or force COUNTRY, REGION, CITY or DMA (US metro).

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

Add top and rising related searches - great for keyword research.

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

Interface language for names of regions and topics, e.g. en-US, de, ja.

## `maxResults` (type: `integer`):

Stop after this many keyword reports. 0 = no limit.

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

Parallel requests. Google Trends rate-limits aggressively; 1-2 is safest.

## `requestDelaySecs` (type: `number`):

Average pause before each request (randomised) to stay under Google's rate limit.

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

Retries on rate limits (429) and errors, with backoff and a fresh session.

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

After repeated rate limits, switch to Apify RESIDENTIAL proxy. Off by default.

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

Direct by default. If Google rate-limits, the Actor switches to Apify datacenter proxy automatically.

## Actor input object example

```json
{
  "keywords": [
    "coffee",
    "matcha",
    "chai latte"
  ],
  "geos": [
    "US"
  ],
  "timeframes": [
    "past_12_months"
  ],
  "searchProperty": "web",
  "category": 0,
  "compareKeywords": false,
  "includeInterestByRegion": true,
  "regionResolution": "auto",
  "includeRelatedQueries": true,
  "language": "en-US",
  "maxResults": 0,
  "maxConcurrency": 2,
  "requestDelaySecs": 0.8,
  "maxRetries": 5,
  "residentialFallback": false,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

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

Average, latest and peak interest plus rising queries per keyword.

## `related` (type: `string`):

Top and rising related search queries per keyword.

## `fullRecords` (type: `string`):

Everything incl. the interest-over-time series and interest by region.

## `runStats` (type: `string`):

RUN_STATS record: requests, retries, rate limits and failures.

# 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": [
        "coffee"
    ],
    "geos": [
        "US"
    ],
    "timeframes": [
        "past_12_months"
    ],
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("clearscrape/google-trends-keyword-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": ["coffee"],
    "geos": ["US"],
    "timeframes": ["past_12_months"],
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("clearscrape/google-trends-keyword-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": [
    "coffee"
  ],
  "geos": [
    "US"
  ],
  "timeframes": [
    "past_12_months"
  ],
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call clearscrape/google-trends-keyword-scraper --silent --output-dataset

```

## MCP server setup

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