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

Google Trends data without the 429 errors: interest over time, interest by region, related queries and related topics for up to 5 compared terms, any country, time range, category or Google property (Web, YouTube, News, Images, Shopping).

- **URL**: https://apify.com/potato_44/google-trends-scraper.md
- **Developed by:** [Streamline Data](https://apify.com/potato_44) (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 $6.00 / 1,000 search term 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 without the 429 "too many requests" errors**: interest over time, interest by region, city and metro area, related queries and related topics — for any keyword, country, time range, category or Google property (Web, YouTube, News, Images, Shopping).

### Why this scraper

- **Built to beat Google's rate limits** — paced requests, automatic session refresh and fallback routing, so runs finish instead of dying on 429s.
- **Pay only for results** — one charge per search term returned; failures are free.
- **Compare up to 5 terms** on the same scale, exactly like the Trends website: just write `bitcoin, ethereum` on one line.
- **Everything in one result** — timeline, average interest, regional/city/metro breakdown and top + rising related queries/topics per term.
- **No charge for empty results** — terms with too little search volume come back as `no_data`, free.

### Input

| Field | Description |
|---|---|
| `searchTerms` | One query per line; comma-separate up to 5 terms to compare them |
| `geo` | Country/region code (`US`, `AU`, `GB`, `US-CA`…), empty = worldwide |
| `timeRange` | Past hour → 2004-present presets |
| `customTimeRange` | `2024-01-01 2024-06-30` (overrides `timeRange`) |
| `category` | Trends category ID (0 = all) |
| `gprop` | Web, YouTube, News, Images or Google Shopping search |
| `interestOverTime`, `interestByRegion`, `relatedQueries`, `relatedTopics` | Choose what to fetch (on by default) |
| `interestByCity`, `interestByMetro` | City (with coordinates) and US metro (DMA) breakdowns (off by default) |

### Output (one item per line of search terms)

```json
{
  "searchTerms": ["bitcoin", "ethereum"],
  "geo": "AU",
  "timeRange": "today 3-m",
  "interestOverTime": [{"time": 1791676800, "date": "Oct 11 – 17, 2026", "values": {"bitcoin": 17, "ethereum": 2}, "isPartial": true}],
  "interestByRegion": [{"geoCode": "AU-WA", "geoName": "Western Australia", "values": {"bitcoin": 92, "ethereum": 8}}],
  "averages": {"bitcoin": 51.1, "ethereum": 7.6},
  "relatedQueries": {"bitcoin": {"top": [{"query": "bitcoin price", "value": 100}], "rising": [{"query": "...", "formattedValue": "Breakout"}]}}
}
```

Notes: Google only returns related topics when a line contains a single term. Times are in UTC (`time` is a Unix timestamp). Values are Google's 0–100 relative scale; like the Trends website, numbers can vary by a few points between requests because Google samples its data.

### Pricing

Pay per event: one charge per search-term line successfully returned. No charge for failures.

### Use cases

SEO keyword research, content planning, market and product research, seasonality analysis, ad timing, and feeding trend data into AI agents (works with the Apify MCP server).

# Actor input Schema

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

Explore mode. One query per line. To compare terms on the same scale (like the Trends website), put up to 5 on one line separated by commas, e.g. "bitcoin, ethereum". Can be left empty if you only want Trending now.

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

Two-letter country code (US, AU, GB...) or region code (US-CA, AU-NSW). Leave empty for worldwide.

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

Preset range, or a custom one as "YYYY-MM-DD YYYY-MM-DD" in the field below.

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

Overrides Time range. Format: "2024-01-01 2024-06-30".

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

Google Trends category ID (0 = all categories).

## `gprop` (type: `string`):

Which Google search to measure: Web (default), YouTube, News, Images or Shopping.

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

Search interest timeline (0-100) for each term.

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

Breakdown by state/province of the selected country, or by country when worldwide.

## `interestByCity` (type: `boolean`):

City-level breakdown with coordinates (needs a country in 'Country / region'). Adds one extra Google request per line.

## `interestByMetro` (type: `boolean`):

US Nielsen DMA metro breakdown. Adds one extra Google request per line.

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

Top and rising related search queries for each term.

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

Google only provides related topics when a line has a single term.

## `trendingCountries` (type: `array`):

Two-letter country codes, e.g. US, AU, GB. Leave empty to skip Trending now.

## `trendingHours` (type: `string`):

How far back to look for trending searches.

## `trendingCategories` (type: `array`):

Only keep trends in these categories. Leave empty for all.

## `trendingActiveOnly` (type: `boolean`):

Skip searches that have stopped trending.

## `maxTrendingPerCountry` (type: `integer`):

Highest search volume first.

## Actor input object example

```json
{
  "searchTerms": [
    "bitcoin, ethereum",
    "solar panels"
  ],
  "geo": "",
  "timeRange": "today 12-m",
  "category": 0,
  "gprop": "",
  "interestOverTime": true,
  "interestByRegion": true,
  "interestByCity": false,
  "interestByMetro": false,
  "relatedQueries": true,
  "relatedTopics": true,
  "trendingHours": "24",
  "trendingActiveOnly": false,
  "maxTrendingPerCountry": 100
}
```

# Actor output Schema

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

One item per search-term line (interest over time, by region, related queries/topics) and one per Trending now search.

# 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": [
        "bitcoin, ethereum",
        "solar panels"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("potato_44/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": [
        "bitcoin, ethereum",
        "solar panels",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("potato_44/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": [
    "bitcoin, ethereum",
    "solar panels"
  ]
}' |
apify call potato_44/google-trends-scraper --silent --output-dataset

```

## MCP server setup

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