# Google Trends Scraper: Interest, Regions & Related Queries (`zaiq/google-trends-scraper`) Actor

Google Trends timelines, regions, top and rising queries and topics. Compare up to 5 keywords, filter by category, country, dates and search property. Each row includes a plain verdict. Partial data stays available; unavailable sections are free notes.

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

## Pricing

from $0.63 / 1,000 trends results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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: timelines, regions and related searches

![Google Trends Scraper: Interest, Regions & Related Queries](https://api.apify.com/v2/key-value-stores/4VJNANhwKgqPpXtAi/records/hero-google-trends-scraper.jpg)

Get a full Google Trends timeline, regional scores, or a top-and-rising related-search list in each result row. The first column gives a plain summary. Compare up to five terms on one timeline scale, with country, date, category and search-property filters.

Enter `air fryer` and start. A delivered section costs **$0.0007 per row** ($0.70 per 1,000), the same price on every Apify plan. One timeline row contains every returned time point. Missing data and refused requests appear as free notes. No Google account or API key is needed.

### What you get

| Field | What it holds |
|---|---|
| `verdict`, `status` | A one-line result, with ok, partial or a free-note status |
| `interest_over_time` | Every returned point, UTC time, source date label, 0–100 score, data-availability and partial-period flags; average, peak and recent change |
| `interest_by_region` | All returned regions, codes, ranks and scores. Individual interest and shared comparison maps have explicit normalization labels |
| `related_queries` | Top and rising searches, source values, formatted growth, Breakout flags, ranks and source links |
| `related_topics` | Top and rising topics when Google supplies them, including topic IDs, names and types |
| Comparison context | Term, comparedWith, comparisonId, country, timeframe, category, search property, language, timezone and source URL |
| `resultId` | Stable identity within the same input and comparison; already delivered rows are skipped on restart |
| `SUMMARY` | Rows, free notes, incomplete sections, requests, traffic, routes and spending-limit status |

### What people use it for

- **Content planning:** Find rising queries and compare the recent interest in topics you cover
- **Seasonality:** Use five-year or custom-date timelines to see when interest usually peaks
- **Regional demand:** Compare relative interest by country, state, city or US metro area when Google provides it
- **Product and competitor research:** Keep up to five search terms on one timeline scale
- **Video and news research:** Measure YouTube, news, images or shopping searches separately from web searches
- **Scheduled reporting:** Save periodic snapshots in a dataset and join them using the comparison context

### How to use it

1. Use the prefilled search term, or enter up to 25 search terms or topic IDs.
2. Choose a country and period. Leave Country empty for worldwide data; use Custom timeframe for exact dates.
3. Keep the sections you need selected. Compare together batches terms in groups of up to five.
4. Start the Actor. Read the Result and Status columns, then expand a row or export JSON for the nested lists.

### Input

| Field | Example | Notes |
|---|---|---|
| `searchTerms` | `["air fryer"]` | Up to 25 distinct terms. Empty input runs the prefill. Google topic IDs are accepted |
| `compareTogether` | `true` | Up to 5 terms per timeline scale; false gives every term its own comparison |
| `country` | `US` | Country code, region such as US-CA, or empty for worldwide. UK is accepted as GB |
| `period` | `year` | hour, 4hours, day, week, month, 3months, year, 5years or all |
| `timeframe` | `2025-01-01 2025-03-31` | Optional exact dates, overriding Period. Dates start in 2004 and cannot be in the future |
| `category` | `0` | Google Trends category ID: 0 is all categories; 71 Food & Drink, 45 Health, 20 Sports |
| `source` | `web` | web, youtube, news, images or shopping |
| `includeTimeline`, `includeRegions` | `true` | Keep the complete source lists in one row per term and section |
| `includeRelatedQueries`, `includeRelatedTopics` | `true` | Top and rising lists. Unavailable sections are free |
| `regionMode` | `individual` | Individual: each term’s own regional scale. Compared: one shared map showing shares among the compared terms |
| `regionResolution` | `AUTO` | COUNTRY, REGION, CITY or DMA. AUTO follows Google’s own resolution for the requested geography. |
| `language`, `timezone` | `en-US`, `0` | Language for source labels and timezone offset in minutes. UTC+2 uses -120. Output timestamps are UTC |

### Output

Each result is one row in the run's dataset (download it as JSON, CSV, Excel, XML or HTML, or read it through the API). An example row (values shortened):

```json
{
  "verdict": "25 top and 25 rising related queries returned.",
  "kind": "related_queries",
  "term": "air fryer",
  "country": "US",
  "period": "year",
  "timeframe": "today 12-m",
  "source": "web",
  "category": 0,
  "status": "ok",
  "top": [
    {
      "query": "air fryer chicken",
      "value": 100,
      "shown": "100",
      "rank": 1,
      "breakout": false,
      "link": "https://example.invalid/trends/top/1"
    },
    {
      "query": "example brand air fryer",
      "value": 63,
      "shown": "63",
      "rank": 2,
      "breakout": false,
      "link": "https://example.invalid/trends/top/2"
    }
  ],
  "rising": [
    {
      "query": "laptop stand",
      "value": 14950,
      "shown": "Breakout",
      "rank": 1,
      "breakout": true,
      "link": "https://example.invalid/trends/rising/1"
    },
    {
      "query": "noise cancelling headphones",
      "value": 14000,
      "shown": "Breakout",
      "rank": 2,
      "breakout": true,
      "link": "https://example.invalid/trends/rising/2"
    }
  ],
  "sourceUrl": "https://example.invalid/trends/comparison"
}
```

This example comes from the real 25 October 2026 prefill run. Names, handles and site addresses have been replaced where present; numeric values are unchanged. Lists are shortened to two entries each. The full row contained 25 top and 25 rising queries. SUMMARY records every incomplete section, retry and charge. A source can return unexpected related searches; these are preserved as supplied.

### Pricing

- **$0.0007 per delivered Trends result row** ($0.70 per 1,000; a term with its timeline, regions and related queries is three rows, $0.0021), the same price on every Apify plan.
- One row contains one term’s full timeline, region list, related-query list or related-topic list. Time points and entries inside that row do not each incur another charge.
- One term with all four sections costs $0.01 in result charges. A missing section is not charged.
- Free note rows explain invalid input, missing widgets, insufficient data, source refusals and the spending limit.
- Apify’s **$0.00005 start charge** counts towards the buyer’s **Maximum cost per run**.

What typical jobs cost at the list price:

| Job | Cost |
|---|---|
| 1 term, timeline only | $0.00075 including the start charge |
| 1 term with timeline, regions and related queries | $0.00215 including the start charge |
| 5 compared terms, those three sections each | $0.01055 including the start charge |
| 25 terms, timelines only | $0.01755 including the start charge |

Set Maximum cost per run to control spending. At $0.00075, one result row can fit after Apify’s $0.00005 start charge. The Actor checks the remaining budget before fetching more data, retains completed rows and writes free notes for unfinished sections. There is no separate charge for retries.

### Tips

- Turn off sections you do not need: each delivered section is a separate result row.
- Use Compare together when comparing terms; independent runs have separate scales.
- Use the same comparison group and timeframe when tracking repeated snapshots, and keep their collection dates.
- Use a Google topic ID to disambiguate a topic, and retain its returned ID when saving results.

### Use it through the API

**Python**

```python
from apify_client import ApifyClient

client = ApifyClient("<YOUR_APIFY_TOKEN>")
run = client.actor("zaiq/google-trends-scraper").call(run_input={"searchTerms": ["air fryer"], "country": "US", "period": "year"})
for row in client.dataset(run.default_dataset_id).iterate_items():
    print(row)
```

**JavaScript**

```js
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: '<YOUR_APIFY_TOKEN>' });
const run = await client.actor('zaiq/google-trends-scraper').call({"searchTerms": ["air fryer"], "country": "US", "period": "year"});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
```

**HTTP (one call, results back)**

```bash
curl -X POST 'https://api.apify.com/v2/acts/zaiq~google-trends-scraper/run-sync-get-dataset-items?token=<YOUR_APIFY_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"searchTerms": ["air fryer"], "country": "US", "period": "year"}'
```

### Integrations and schedules

- **Schedules:** run it every hour, day or week from the Apify Console (Schedules) and keep a history of results.
- **Make, Zapier, n8n, Google Sheets, Slack, Airtable:** connect it through Apify's integrations, or send each finished run to a **webhook**.
- **Datasets:** results stay in the run's dataset; export them or read them by API whenever you need them.

### Use it with AI agents (MCP)

Add Apify's MCP server (`https://mcp.apify.com`) to Claude, ChatGPT, Cursor, VS Code or any MCP client. The agent can find this Actor and run it for you: ask it for "compare interest in coffee and tea in the UK over five years". AI agents can also pay for runs directly through Apify's agentic payments.

### Limits

- Google Trends reports relative interest, not absolute search volume. Scores from different comparisons, countries or timeframes are not directly comparable.
- The source chooses time granularity and may sample or revise historical values. The newest time point can be partial; recent-change calculations exclude partial points.
- Google may omit related topics, related queries or fine-grained regions. A section can be empty even when the same term has a timeline. Empty data is retried on available cloud routes and then reported without a result charge.
- A comparison contains at most five terms. Larger inputs are separate groups of five, each with its own scale. There are at most 25 distinct terms per run.
- A direct request is tried first, followed by datacenter and fresh residential sessions when needed. Rate limits have backoff; repeated refusals stop further requests. No login or CAPTCHA is used.
- A run stops after 150 source requests, including retries and session initialization, and reports unfinished sections.
- Individual region mode matches the existing output: 100 is a term’s highest regional interest. Compared mode shows the relative share of the selected terms within each region. The two maps answer different questions.
- When a source record is malformed, usable records stay available and the row is marked partial. SUMMARY lists the skipped records.
- CSV exports contain nested lists inside cells; use JSON when consuming every point, region or related item.
- Breakout flags recognize the source labels observed in English, German, Portuguese and Japanese. An unknown translated growth label keeps its original shown text and has breakout: null; unclassifiedGrowthCount reports these entries.

### FAQ

**What is one charged result?**

One term and one delivered section. A timeline with 260 weekly points is one row, not 260 charged rows. Top and rising results for a section share one row.

**Why did my run return free note rows?**

Google did not supply a requested section, refused the request, or the spending limit prevented more work. Read status and note. Existing successful sections stay in the dataset.

**Does a successful Actor run mean every section was returned?**

No. SUMMARY.complete and the row statuses distinguish complete delivery from partial data or source refusal.

**Are these search volumes?**

No. The values are normalized source scores. A zero can mean very low measured interest; missing or suppressed source data is identified separately.

**Can I get daily values for five years?**

Google chooses the resolution for each requested range. This Actor does not splice differently normalized windows into a misleading daily series. Use shorter custom date ranges if daily data is required.

**How does the verdict measure change?**

For timelines, it compares the mean of the last three complete available periods with the preceding three. It reports no percentage when there are too few points or the preceding mean is zero. A period can be hourly, daily, weekly or monthly.

**What happens after an Actor restart?**

Rows already delivered in the same dataset are not written or charged again. Completed sections are skipped before source requests. An unfinished section can be retried. Separate scheduled runs create fresh snapshots.

**Do category and country alter the keywords?**

No. They filter the source request. Exact input terms and the returned comparison context remain visible.

**Do I need a Google login or my own proxy?**

No. The Actor uses public signed-out data and its own configured cloud routes. It does not accept account passwords or proxy logins.

**Can an earlier free note remain after a restart?**

Yes. Datasets keep their history. A free note includes relatedResultId; a later data row with that resultId resolves the section. Read the latest SUMMARY for the restart’s outcome.

### Related Actors from Zaiq

- [google-trending-now-scraper](https://apify.com/zaiq/google-trending-now-scraper): current trending searches by country
- [google-news-scraper](https://apify.com/zaiq/google-news-scraper): news coverage around a search trend

### Support

Questions, a site that changed, or a field you need? Open an issue on this Actor's **Issues** tab: we answer there, usually within a day.

***

Also found as: google trends scraper, google trends api, interest over time, interest by region, related queries, rising searches, Google Trends Python.

# Actor input Schema

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

1–25 distinct search terms or Google topic IDs. Up to 5 share a comparison scale. An empty list uses air fryer for a working first run.

## `compareTogether` (type: `boolean`):

Put up to 5 terms on one scale, as on trends.google.com. Off: each term gets its own 0-100 scale.

## `country` (type: `string`):

Two-letter country (US, GB, DE, ZA, IN, BR), region (US-CA), or an empty string for worldwide. The country is a data filter, not a proxy location.

## `period` (type: `string`):

The time range.

## `source` (type: `string`):

Which Google searches to measure.

## `includeTimeline` (type: `boolean`):

One row per term with every point of the timeline (0-100).

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

One row per term with each region's 0-100 score (states, provinces, or countries when worldwide).

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

One row per term with the top and rising searches (with growth such as +250% or Breakout).

## `includeRelatedTopics` (type: `boolean`):

One row per term with the top and rising topics.

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

Optional override for Period: YYYY-MM-DD YYYY-MM-DD, or now 7-d, today 1-m, today 3-m, today 12-m, today 5-y, all. Dates must be from 2004 through today.

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

Google Trends category ID. 0 = all categories; 71 = Food & Drink, 45 = Health, 20 = Sports. An unavailable category produces a free note.

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

Language of source labels and related topics, such as en-US, de, fr or pt-BR. Keywords are sent exactly as entered.

## `timezone` (type: `integer`):

Google Trends timezone parameter in minutes: UTC is 0. This follows JavaScript getTimezoneOffset (UTC+2 is -120). Timestamps in output are always UTC.

## `regionMode` (type: `string`):

Individual keeps each term on its own regional 0–100 scale. Compared uses one shared map request for up to 5 terms and returns each term’s share within a region. The normalization is labelled on each row.

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

Automatic follows the resolution supplied by Google, usually countries worldwide and states/regions within a country. Explicit detail levels may have insufficient source data, which is free.

## Actor input object example

```json
{
  "searchTerms": [
    "air fryer"
  ],
  "compareTogether": true,
  "country": "US",
  "period": "year",
  "source": "web",
  "includeTimeline": true,
  "includeRegions": true,
  "includeRelatedQueries": true,
  "includeRelatedTopics": true,
  "timeframe": "",
  "category": 0,
  "language": "en-US",
  "timezone": 0,
  "regionMode": "individual",
  "regionResolution": "AUTO"
}
```

# Actor output Schema

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

Dataset: the results.

## `summary` (type: `string`):

What each input returned, and notes.

# 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": [
        "air fryer"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("zaiq/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": ["air fryer"] }

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

```

## MCP server setup

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