# Google Trends Scraper - Fast API, No Browser (`leekung125/google-trends-scraper`) Actor

Interest over time, interest by region, related queries and topics, and trending searches from Google Trends. HTTP-only, answers in seconds, charges only for rows delivered.

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

## Pricing

$0.25 / 1,000 result rows

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 — fast API, no browser, pay only for rows

Get **interest over time**, **interest by region**, **related queries** (top + rising), **related topics**
and **trending searches** from Google Trends as clean JSON/CSV — for any keyword, country, time range,
category or search type (web, images, news, YouTube, Shopping).

- **Seconds, not minutes.** Talks to Google Trends' own JSON API over plain HTTP. No headless browser.
- **No empty bills.** You are charged per row that lands in your dataset. A run that returns nothing costs nothing.
- **Fails loudly, never loops.** Rate limits are retried with fresh sessions a fixed number of times, then the run stops with a clear error.
- **Compare mode.** Up to five keywords in one request, values relative to each other like the Compare view.
- Works from the API, schedules, integrations and MCP/AI agents like any Apify Actor.

### What you get

One row per data point, all in the same dataset, with a `type` column you can filter on:

| `type` | one row per | key fields |
|---|---|---|
| `interest_over_time` | time point × keyword | `date`, `timestamp`, `value` (0–100), `is_partial` |
| `interest_by_region` | region × keyword | `geo_code`, `geo_name`, `value`, `resolution` |
| `related_queries` | related search | `query`, `rank_type` (top / rising), `value`, `formatted_value` (e.g. `+500%`), `link` |
| `related_topics` | related topic | `topic_title`, `topic_type`, `topic_mid`, `rank_type`, `value` |
| `trending_now` | trending search today | `query`, `approx_traffic`, `published`, `news[]` |

Sample (`related_queries`, keyword *moissanite ring*, US, 12 months):

```json
{"type":"related_queries","keyword":"moissanite ring","geo":"US","timeframe":"today 12-m","rank_type":"rising","query":"black moissanite ring","value":500,"formatted_value":"+500%","link":"https://trends.google.com/trends/explore?q=black+moissanite+ring&date=today+12-m&geo=US"}
```

### Input

| field | example | notes |
|---|---|---|
| `keywords` | `["moissanite ring", "lab grown diamond"]` | each fetched on its own unless `compare` is on |
| `geo` | `US`, `GB`, `US-CA`, ``(worldwide) | Google Trends location codes |
| `timeframe` | `today 12-m`, `now 7-d`, `today 5-y`, `2025-01-01 2025-06-30` | any Google Trends range |
| `interestOverTime` / `interestByRegion` / `relatedQueries` / `relatedTopics` | `true` | choose sections |
| `trendingNow` | `true` | today's trending searches for `geo`; works with no keywords |
| `compare` | `false` | up to 5 keywords per request, relative values |
| `regionResolution` | `REGION` | `COUNTRY`, `REGION`, `CITY`, `DMA` |
| `category` | `0` | Google Trends category id (18 = Shopping) |
| `property` |`` | `images`, `news`, `youtube`, `froogle` |
| `proxyConfiguration` | Apify residential (default) | Google Trends rate-limits datacenter IPs |

Minimal input:

```json
{ "keywords": ["moissanite ring"], "geo": "US", "timeframe": "today 12-m" }
```

### How many rows to expect

Per keyword with the defaults: ~52 time points (12 months, weekly) + ~50 regions (US states) + up to 50
related queries. So roughly **150 rows per keyword**. Trending now adds ~20 rows.

### Pricing

Pay per result row. No start fee, no charge for empty runs. See the Pricing tab.

### Limits and honesty notes

- Google Trends values are relative (0–100 within the request), not absolute search volumes. That is how Google publishes them.
- Google may show no related topics/queries for low-volume keywords; you get zero rows and pay zero.
- Very long keyword lists trigger Google's rate limiting; the Actor rotates sessions and retries up to `maxRetries`, then stops with an error rather than running forever.
- This Actor reads public Google Trends pages only. No login, no personal data.

### Use cases

Keyword research and SEO seasonality · product demand validation before you build or stock · competitor and brand interest tracking · content calendars from rising queries · market entry (which regions care) · feeding an AI agent with live trend data via MCP.

### Support

Open an issue on the Issues tab. Runs that fail get a clear error message with the failing step.

# Actor input Schema

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

Search terms to look up, one per line. Each keyword is fetched on its own (values 0-100 per keyword) unless Compare mode is on.

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

Country or region code as Google Trends uses it: empty for worldwide, US, GB, DE, US-CA (state), etc.

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

Google Trends time range: 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 a custom range like 2025-01-01 2025-06-30.

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

One row per time point (weekly for 12 months, daily for 3 months, hourly for 7 days).

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

One row per region (countries for worldwide, states/provinces for a country).

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

Up to 25 top and 25 rising related searches per keyword, with the growth figure (for example +500%).

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

Related topic entities per keyword, with type and Knowledge Graph id.

## `trendingNow` (type: `boolean`):

Add today's trending searches for the location (official Google Trends feed), with approximate traffic and news links. Works with an empty keyword list too.

## `compare` (type: `boolean`):

Put up to five keywords in one request so the values are relative to each other, like the Compare view on Google Trends.

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

COUNTRY (worldwide), REGION (states/provinces), CITY, or DMA (US metro areas).

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

Google Trends category id (0 = all categories). For example 18 = Shopping, 12 = Business & Industrial, 45 = Health.

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

Web search (default), or images, news, youtube, froogle (Google Shopping).

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

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

## `timezoneOffset` (type: `integer`):

Minutes behind UTC, as Google Trends counts it (300 = US Eastern in summer... use 0 for UTC).

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

How many fresh sessions to try when Google rate-limits. The run fails loudly after this, it never loops forever.

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

Google Trends rate-limits datacenter IPs quickly. Apify residential proxies are the default and recommended.

## Actor input object example

```json
{
  "keywords": [
    "moissanite ring"
  ],
  "geo": "US",
  "timeframe": "today 12-m",
  "interestOverTime": true,
  "interestByRegion": true,
  "relatedQueries": true,
  "relatedTopics": false,
  "trendingNow": false,
  "compare": false,
  "regionResolution": "REGION",
  "category": 0,
  "property": "",
  "language": "en-US",
  "timezoneOffset": 0,
  "maxRetries": 4,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

## `summary` (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": [
        "moissanite ring"
    ],
    "geo": "US",
    "timeframe": "today 12-m",
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("leekung125/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 = {
    "keywords": ["moissanite ring"],
    "geo": "US",
    "timeframe": "today 12-m",
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("leekung125/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 '{
  "keywords": [
    "moissanite ring"
  ],
  "geo": "US",
  "timeframe": "today 12-m",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}' |
apify call leekung125/google-trends-scraper --silent --output-dataset

```

## MCP server setup

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