# Google Trends Scraper (`trendcraft/google-trends-scraper`) Actor

Interest over time, interest by region, related queries and trending-now searches from Google Trends. Compare up to 5 keywords on the same scale.

- **URL**: https://apify.com/trendcraft/google-trends-scraper.md
- **Developed by:** [TrendCraft](https://apify.com/trendcraft) (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 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

## Google Trends Scraper

Get **Google Trends data as clean JSON** — no API key, no browser, no code. This Actor collects:

- 📈 **Interest over time** — the 0–100 search interest for every hour, day, week or month in your time range
- 🗺️ **Interest by region** — countries, states, cities or US metro areas (DMA)
- 🔎 **Related queries** — the top and fastest-rising ("Breakout") searches for each keyword
- 🔥 **Trending now** — today's trending searches in any country, with traffic estimates and news links
- ⚖️ **Keyword comparison** — up to 5 keywords on the same scale, exactly like the Google Trends website

### Why use this Google Trends Scraper?

Google Trends has no official public API. This Actor talks to the same endpoints the Trends website uses, retries automatically with a fresh session and IP when Google rate-limits, and returns structured data you can download as JSON, CSV or Excel, or send to Google Sheets, Make, Zapier or n8n.

**You only pay for successful results.** If Google blocks a keyword after all retries, no result is saved and you are not charged for it.

### Use cases

- **SEO & content planning** — find rising queries before your competitors write about them
- **Market research** — compare brands, products or categories across countries and time
- **E-commerce** — spot seasonal demand (e.g. "halloween costumes", "air fryer") months ahead
- **Finance & crypto** — track public attention on stocks, coins and events
- **AI agents & dashboards** — feed fresh trend data into LLM workflows via the Apify API or MCP

### How to use it

1. Enter one or more **search terms**.
2. Turn on **Compare terms on one chart** if you want them on the same 0–100 scale (groups of up to 5).
3. Choose a **country or region code** (empty = worldwide) and a **time range**.
4. Optionally add country codes under **Trending now** (e.g. `US`, `GB`, `DE`).
5. Click **Start** and download your data from the **Output** tab.

### Input example

```json
{
    "searchTerms": ["chatgpt", "claude", "gemini"],
    "compareTerms": true,
    "geo": "US",
    "timeframe": "today 3-m",
    "regionResolution": "REGION",
    "trendingNowGeos": ["US"]
}
```

### Output example

Each search returns one item with all the data you selected:

```json
{
    "type": "search",
    "searchTerms": ["chatgpt", "claude", "gemini"],
    "geo": "US",
    "timeframe": "today 3-m",
    "interestOverTime": [
        {
            "date": "2026-10-19T00:00:00Z",
            "label": "Oct 19, 2026",
            "isPartial": true,
            "values": { "chatgpt": 85, "claude": 24, "gemini": 38 }
        }
    ],
    "interestByRegion": [
        { "geoCode": "US-CA", "name": "California", "values": { "chatgpt": 59, "claude": 17, "gemini": 24 } }
    ],
    "relatedQueries": {
        "gemini": {
            "top": [{ "query": "gemini ai", "value": "100" }],
            "rising": [{ "query": "gemini argon 4", "value": "Breakout" }]
        }
    }
}
```

Trending-now items look like this:

```json
{
    "type": "trendingNow",
    "geo": "US",
    "rank": 1,
    "title": "world series",
    "approxTraffic": "2000+",
    "publishedAt": "Mon, 19 Oct 2026 12:40:00 -0700",
    "news": [{ "title": "...", "url": "https://...", "source": "ESPN" }]
}
```

### How much does it cost?

You pay per result saved to the dataset: one result per keyword (or per comparison group of up to 5 keywords), and one result per trending search. The current price is shown on the **Pricing** tab. Set **Maximum cost per run** in the run options and the Actor stops cleanly when it is reached.

### Tips

- **Time range:** past hour / 4 hours / day give minute or hourly points; 7 days gives hourly; 30–90 days gives daily; 12 months and 5 years give weekly; 2004–present gives monthly.
- **Values are relative**, not absolute search volume: 100 is the peak of the chart, 50 is half as popular. Compare terms together if you need them on the same scale.
- **Category ID:** open Google Trends, pick a category, and copy the number after `cat=` in the URL.
- **Large lists:** hundreds of keywords are fine — the Actor works through them one by one and handles rate limits for you.

### FAQ

**Is scraping Google Trends legal?**
This Actor only collects publicly available, aggregated and anonymous statistics. You are responsible for using the data in line with applicable laws and Google's terms.

**Why is "related topics" not included?**
Google currently returns empty related-topics data for automated requests. Related queries are included.

**Something is broken or you need a feature?**
Open an issue on the **Issues** tab — we read every one.

# Actor input Schema

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

Keywords to look up on Google Trends.

## `compareTerms` (type: `boolean`):

On: terms are compared in groups of up to 5 (same 0-100 scale, like the Trends website). Off: each term gets its own scale.

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

Empty = worldwide. Examples: US, GB, DE, US-CA, TR.

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

Period the data covers. Shorter ranges give hourly or daily points.

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

Which Google search to measure: web, images, news, shopping or YouTube.

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

0 = all categories. Use the number from the Trends website URL (cat=...).

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

Search interest on a 0-100 scale for each date in the time range.

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

Search interest on a 0-100 scale for each country, state or city.

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

Default: countries for worldwide, sub-regions for a country.

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

Top and fastest-rising searches related to each term.

## `trendingNowGeos` (type: `array`):

Country codes for today's trending searches with news links (e.g. US, GB). Leave empty to skip.

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

Language for labels and region names, e.g. en-US, de, tr.

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

Google limits requests per IP. Apify Proxy is recommended.

## Actor input object example

```json
{
  "searchTerms": [
    "chatgpt",
    "claude"
  ],
  "compareTerms": false,
  "geo": "",
  "timeframe": "today 12-m",
  "searchProperty": "",
  "category": 0,
  "interestOverTime": true,
  "interestByRegion": true,
  "regionResolution": "",
  "relatedQueries": true,
  "trendingNowGeos": [],
  "language": "en-US",
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

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

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

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

```

## MCP server setup

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