# Google Trends Scraper | Interest & Related Queries (`gridforge/google-trends-scraper`) Actor

Extract Google Trends interest over time, regional interest, and top or rising related queries for keyword lists. Choose location, time range, category, and search type. $0.01 per successful keyword with all selected reports included, plus a small run-start fee. Export JSON, CSV, or Excel.

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

## Pricing

from $10.00 / 1,000 keyword processeds

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 & Related Queries

Turn a keyword list into Google Trends data for SEO research, seasonal planning, and regional demand analysis. Get **interest over time**, **interest by region**, and **top and rising related queries**, with a per-keyword charge rather than a per-row charge.

**Price:** $0.01 per successful keyword, including all selected reports, plus the configured run-start fee. See the pricing details below.

### Quick start

1. Add one or more keywords.
2. Choose a country or region, timeframe, category, and search type.
3. Enable the reports you need. Only interest over time is enabled by default.
4. Start the Actor and inspect the output. Download the dataset as JSON, CSV, or Excel, or retrieve it through the Apify API.

#### Example input

```json
{
  "keywords": [
    "pull up bar",
    "resistance bands"
  ],
  "geo": "US",
  "timeframe": "today 12-m",
  "category": 0,
  "property": "",
  "includeInterestOverTime": true,
  "includeRegions": true,
  "includeRelatedQueries": true
}
```

This example requests all three supported report groups for two keywords in the United States. It is an input example, not a recorded run or performance benchmark.

### What can I extract?

| Report | What it contains |
|---|---|
| Interest over time | Dated search-interest values on Google's relative 0-100 scale |
| Interest by region | Regional interest values and region identifiers, when available |
| Related queries | Top related searches and rising searches, including formatted growth values when supplied |

Each selected report can produce multiple dataset rows. Useful fields include `keyword`, `geo`, `timeframe`, and `type`; report-specific fields include `date`, `timestamp`, `value`, `region`, `regionCode`, `query`, and `formattedValue`.

Not every field applies to every row. Treat related-query scores, growth percentages, and timeline indices as different measures.

### Input reference

| Field | Default | Purpose |
|---|---|---|
| `keywords` | Required | Array of search terms; each is fetched independently |
| `geo` | Empty | Empty means worldwide; country codes such as `US` and region codes such as `US-NY` |
| `timeframe` | `today 12-m` | Select one of the supported time windows |
| `category` | `0` | Google Trends category; `0` means all categories |
| `property` | Empty | Web search; alternatives: `images`, `news`, `youtube`, `froogle` (Shopping) |
| `includeInterestOverTime` | `true` | Request timeline rows |
| `includeRegions` | `false` | Request regional rows |
| `includeRelatedQueries` | `false` | Request top and rising related-query rows |
| `proxyConfiguration` | Apify proxy enabled | Proxy configuration used by the Actor |

Supported timeframe values: `now 1-H`, `now 4-H`, `now 1-d`, `now 7-d`, `today 1-m`, `today 3-m`, `today 12-m`, `today 5-y`, and `all`.

### Pricing and billing unit

- **$0.01 per keyword that returns data** ($10 per 1,000 successful keywords).
- All selected reports for that keyword are included in that keyword event. The number of timeline or region rows does not multiply this event charge.
- The current pricing configuration also includes a **$0.00005 Actor Start event**. Its event definition scales with Actor memory in GB, with a minimum of one event. At the default 1 GB, this is $0.00005 per run.
- Failed keywords do not incur a successful-keyword event charge. The start event can still apply, so a failed run is not necessarily free.
- Example at 1 GB: two successful keywords have $0.02005 in configured event charges. This arithmetic is not a measured invoice. Check the live Pricing tab before running; the authenticated console currently shows that users do not pay platform usage costs.

### Interpretation and limitations

**These are relative interest indices, not absolute monthly search volumes.** Every keyword is fetched on its own scale. A value of 100 for one keyword cannot be read as the same search volume as 100 for another keyword. This Actor does not perform a shared-scale, side-by-side keyword comparison.

Low-volume searches can return little or no data. Available granularity depends on Google's response and the selected timeframe. Search data and related queries can change between runs.

The Actor retries transient request failures, but upstream rate limits or changes can still prevent collection. No guaranteed success rate, latency, or unlimited throughput is claimed.

The supported reports are timelines, regional interest, and related queries. This listing does not promise related topics, Trending Now, search-volume estimates, or other unlisted features.

### Use from an API or schedule

Use the Actor's **API** tab for current request examples and your Apify account token. An Apify token is needed for authenticated API execution; you do not supply a Google API key in this Actor's input. Apify schedules can run repeated checks; each scheduled run follows the live pricing rules.

Not affiliated with or endorsed by Google.

### Output example (illustrative)

```json
{"keyword":"pull up bar","geo":"US","timeframe":"today 12-m","type":"interest_over_time","date":"Oct 4, 2026","timestamp":1791072000,"value":72}
```

This illustrates the row shape, not a recorded observation or forecast.

### FAQ

**Can I compare keyword volumes directly?** No. Each keyword is independently normalized to 0-100; these are not absolute search volumes.

**Does every keyword cost more when I enable regions and queries?** The successful-keyword event includes all selected reports; the separate start event still applies.

**Is a failed run free?** Failed keywords have no successful-keyword charge, but the configured run-start event can still be charged.

# Actor input Schema

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

Search terms to look up. Each keyword is fetched on its own (0-100 scale per keyword).

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

Two-letter country code like US, GB, DE, or US-NY for a state. Leave empty for worldwide.

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

How far back to look.

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

Google Trends category number. 0 = all categories.

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

Which Google search to measure.

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

Add the 0-100 interest timeline for each keyword.

## `includeRegions` (type: `boolean`):

Add interest by country or sub-region.

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

Add top and rising related searches.

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

Google limits repeated requests; the Actor rotates proxy sessions automatically.

## Actor input object example

```json
{
  "keywords": [
    "pull up bar",
    "resistance bands"
  ],
  "geo": "",
  "timeframe": "today 12-m",
  "category": 0,
  "property": "",
  "includeInterestOverTime": true,
  "includeRegions": false,
  "includeRelatedQueries": false,
  "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 = {
    "keywords": [
        "pull up bar",
        "resistance bands"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("gridforge/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": [
        "pull up bar",
        "resistance bands",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("gridforge/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": [
    "pull up bar",
    "resistance bands"
  ]
}' |
apify call gridforge/google-trends-scraper --silent --output-dataset

```

## MCP server setup

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