# Google Trends Intelligence (`skootle/google-trends-intelligence`) Actor

Google Trends interest over time and related queries with trend direction, momentum, volatility, source proof, API output, scheduling, monitoring, and integrations.

- **URL**: https://apify.com/skootle/google-trends-intelligence.md
- **Developed by:** [Skootle](https://apify.com/skootle) (community)
- **Categories:** SEO tools, AI, Automation
- **Features:** Limited permissions
- **Stats:** 4 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.40 / 1,000 google trends intelligence records

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 Intelligence

Built by [Skootle](https://skootle.com) for decision-ready trend data.

![Google Trends Intelligence hero](https://raw.githubusercontent.com/kesjam/skootle-actors-assets/main/heroes/google-trends-intelligence.png)

### Fast answer: what this Actor is for

Google Trends Intelligence turns one to five Google Trends queries into structured timeline, related-query, and summary records. It helps SEO, content, product, and research teams distinguish a real low-data result from a blocked source before they use a trend signal in a decision.

- Run it in the Apify UI for a bounded demand or content-research pull.
- Schedule it or call it by API for recurring trend monitoring.
- Send the dataset to a spreadsheet, webhook, or an automation that consumes typed records and source links.

### TL;DR

Provide keywords, a geography, and a time window. The Actor returns `TREND_POINT`, `RELATED_QUERY`, and `SUMMARY` records with normalized fields, a source URL, retrieval time, and an `agentMarkdown` explanation. Google Trends values are relative indexes, not search-volume counts. The latest verified Cloud run before this documentation update, run `ywvdKNw0LMgXfnfik`, succeeded on 2026-09-10 using build `xab6roYMTXB8o8PKS`.

Try a small dataset first. If it helps, leave an honest review. Use the Issues tab for reproducible bugs.

### What does Google Trends Intelligence do?

A manual Google Trends workflow requires opening charts, changing the comparison, copying points, and separately reading related queries. This Actor writes one dataset instead. Filter `recordType` to use the shape you need:

- `TREND_POINT`: one row for a keyword and time bucket, including interest, rolling average, and partial-bucket status.
- `RELATED_QUERY`: a ranked top or rising related search, including a numeric growth value when Google publishes one.
- `SUMMARY`: one decision record per keyword, including direction, momentum, volatility, coverage, and source outcome.

Every record includes a stable `recordId`, `schemaVersion`, `sourceName`, `sourceQueryUrl`, `trendsUrl`, `retrievedAt`, `fieldCompletenessScore`, and `agentMarkdown`.

### Why use Google Trends data?

Google Trends is useful for the shape and timing of interest in an exact query, geography, and time window. It is not an absolute-search-volume source. A buyer can use the output to compare terms in one request, inspect related demand, create a trend chart, or provide a traceable input to an automation. Keep the query context fixed when comparing runs because changing the timeframe, geography, property, or comparison set can change the relative 0 to 100 index.

### Who needs this?

- SEO and content teams choosing topics from recent search-interest and related-query signals.
- Product and brand teams monitoring a fixed set of demand terms over time.
- Researchers building a traceable trend dataset with source links and timestamps.
- Analysts who need to separate a genuine no-match from an unavailable source.
- AI-agent and automation workflows that need typed numeric fields plus a concise `agentMarkdown` summary.

### How to use Google Trends Intelligence

1. Open the Input tab.
2. Add one to five `keywords` and choose a `geo` and `timeframe`.
3. For a first run, use one or two keywords, `today 3-m`, and `maxRelatedQueries: 10`.
4. Start the run, then export the dataset or schedule the same bounded input.
5. Filter `SUMMARY` for one decision row per keyword. Keep `TREND_POINT` rows for charts and `RELATED_QUERY` rows for query research.
6. Before acting on a result, check `sourceStatus`, `zeroMatch`, `dataCoveragePct`, `isPartialBucket`, and the included source link.

### How much does Google Trends Intelligence cost?

This Actor uses pay-per-result pricing with an Actor start fee and a charge for emitted dataset records. The current price shown in the Store Pricing tab is authoritative. The local pricing configuration for this build declares a $0.01 start fee and $0.003 per dataset-item event. Actual totals depend on records emitted and retries. The Actor's configured default run options have a 600-second timeout; check the live Console before relying on any run cap or price display.

#### ROI example

A conservative first-run budget is one keyword, `today 3-m`, `maxRelatedQueries: 10`, with both result types enabled. That produces a bounded dataset you can evaluate before scheduling a wider comparison. The value decision is whether the returned source-backed signal changes a research or monitoring workflow, not a claimed conversion or labor result.

### Source, permissions, and legal use

The Actor reads public Google Trends web endpoints. It does not require a Google account and does not access a logged-in, paid, or private Google surface. It uses a residential proxy configuration for reliable retrieval and fails loudly when it cannot read trustworthy source data. It is not affiliated with, endorsed by, or sponsored by Google.

Google Trends values are sampled relative indexes, not absolute volumes. Review your intended use, applicable law, and source terms before redistributing data. Do not treat a source block as a demand signal, and independently verify material findings.

### Examples

#### Example 1: Compare two demand terms in the United States

```json
{
  "keywords": ["artificial intelligence", "machine learning"],
  "geo": "US",
  "timeframe": "today 3-m",
  "maxRelatedQueries": 10
}
```

Use `SUMMARY` to compare the two trend directions under the same scale.

#### Example 2: Weekly content research for one term

```json
{
  "keywords": ["cold plunge"],
  "geo": "US",
  "timeframe": "today 3-m",
  "maxRelatedQueries": 25,
  "includeInterestOverTime": true,
  "includeRelatedQueries": true
}
```

Use `RELATED_QUERY` rows for top and rising query research, then preserve `trendsUrl` with any downstream recommendation.

#### Example 3: Trend chart without related queries

```json
{
  "keywords": ["electric vehicle"],
  "geo": "US-CA",
  "timeframe": "today 12-m",
  "includeInterestOverTime": true,
  "includeRelatedQueries": false
}
```

Use `TREND_POINT` rows for the chart and `SUMMARY` for the partial-bucket and direction fields.

#### Example 4: YouTube-search interest comparison

```json
{
  "keywords": ["home gym", "pilates"],
  "geo": "GB",
  "timeframe": "today 3-m",
  "property": "youtube",
  "maxRelatedQueries": 10,
  "proxyCountryCode": "GB"
}
```

Keep the property, geography, timeframe, and comparison set unchanged when comparing this result with a later run.

### Input parameters

| Field | Type | Default | Description |
|---|---|---|---|
| `keywords` | array of strings | required | One to five terms, each 1 to 100 characters. Multiple terms share one comparison scale. |
| `geo` | string | `US` | Google Trends geography, such as `US`, `GB`, or `US-CA`. Empty means worldwide. |
| `timeframe` | enum | `today 3-m` | One of `now 1-H`, `now 4-H`, `now 1-d`, `now 7-d`, `today 1-m`, `today 3-m`, `today 12-m`, `today 5-y`, or `all`. |
| `category` | integer | `0` | Google Trends category ID, from 0 through 1500. |
| `property` | enum | empty | Search surface: empty for web, or `images`, `news`, `froogle`, or `youtube`. |
| `maxRelatedQueries` | integer | `25` | Maximum rows from each top and rising list per keyword, from 0 through 50. |
| `includeInterestOverTime` | boolean | `true` | Return timeline points and compute time-series metrics. |
| `includeRelatedQueries` | boolean | `true` | Return top and rising related-query records. |
| `language` | string | `en-US` | Google Trends interface locale. |
| `proxyCountryCode` | string | `US` | Two-letter residential proxy exit country. |
| `maxRetriesPerRequest` | integer | `4` | Retry attempts per upstream request, from 1 through 8. |

### Google Trends Intelligence output format

| Field | Type | Description and buyer use |
|---|---|---|
| `recordType` | string | `TREND_POINT`, `RELATED_QUERY`, or `SUMMARY`, for safe downstream routing. |
| `recordId` | string | Stable record identity for deduplication. |
| `schemaVersion` | string | Schema version for downstream pinning. |
| `keyword`, `geo`, `timeframe`, `property` | string | Query context that must be retained with the result. |
| `interestValue`, `dateIso`, `isPartialBucket` | number, string, boolean | Timeline value and whether the bucket is still filling. |
| `relatedQuery`, `listType`, `growthPct`, `isBreakout` | mixed | Related-query result and Google-published growth context. |
| `direction`, `momentumPct`, `volatility`, `dataCoveragePct` | mixed | Summary fields for a trend decision, not absolute demand. |
| `sourceStatus`, `zeroMatch`, `notes` | mixed | Distinguishes a usable no-match from an unavailable source. |
| `sourceQueryUrl`, `trendsUrl`, `retrievedAt` | string | Provenance and the human-readable Google Trends chart. |
| `agentMarkdown` | string | A concise source-backed explanation for an agent or automation. |

### Sample record

This redacted `TREND_POINT` is from successful Cloud run `uXDXfIcTY1DVyr1Hi` on 2026-09-09, dataset `rBbfPkUAQd0RqyFHD`. URL query parameters are omitted only for readability.

```json
{
  "recordType": "TREND_POINT",
  "recordId": "gtrends:point:artificial-intelligence:US:2026-06-09:1780963200",
  "schemaVersion": "1.0.0",
  "queryLabel": "artificial intelligence vs machine learning | US | today 3-m",
  "keyword": "artificial intelligence",
  "geo": "US",
  "timeframe": "today 3-m",
  "dateIso": "2026-06-09",
  "interestValue": 51,
  "isPartialBucket": false,
  "rollingAverage7": 51,
  "sourceStatus": "ok",
  "zeroMatch": false,
  "fieldCompletenessScore": 90,
  "sourceName": "Google Trends public web endpoints",
  "trendsUrl": "https://trends.google.com/trends/explore?q=artificial+intelligence&date=today+3-m&geo=US",
  "retrievedAt": "2026-09-09T10:35:01.702Z"
}
```

### During the Actor run

The Actor gets a session, requests Google Trends widget data, normalizes the returned records, and writes a machine-readable `RUN_REPORT` plus the default dataset. A blocked or malformed upstream response is retried within `maxRetriesPerRequest` and then fails the run rather than emitting an empty dataset. A genuine low-volume no-match emits a `SUMMARY` with `zeroMatch: true` and `sourceStatus: "ok"`. The trailing partial bucket is emitted for visibility but excluded from summary statistics.

### FAQ

#### How is this different from a chart-only Google Trends workflow?

The Actor returns typed records, source URLs, retrieval timestamps, and a run-level source outcome so the result can be exported or consumed by an automation. It does not convert the relative Google Trends index into search volume.

#### Why does this cost what it costs?

The Store charges for the Actor start and emitted dataset records. Result volume grows with timeline buckets, related-query limits, and the number of keywords. Start with a bounded input and check the live Pricing tab before scaling a scheduled workflow.

#### How reliable is it for recurring work?

The latest observed Cloud evidence before this update includes successful runs on 2026-09-10 using build `xab6roYMTXB8o8PKS`. Reliability for a future source request is not guaranteed. The Actor records a source status and fails loudly instead of silently turning an unavailable source into zero demand.

#### Will source changes break it?

Google can change its public response behavior. If the Actor cannot produce trustworthy data, it fails the run with a classified source error rather than returning a plausible empty result. Recheck the run report and source links after an upstream failure.

#### Can I use it with an API, spreadsheet, or AI workflow?

Yes. Export the default Apify dataset or consume it through the Apify API. Use `recordType` to route the three record shapes and retain source fields with any derived output.

#### What is the cheapest safe way to try it?

Run one keyword with `today 3-m`, `maxRelatedQueries: 10`, and a fixed geography. Verify that the dataset has `sourceStatus: "ok"` before broadening the input or adding a schedule.

### Maintenance status

- Last verified: 2026-09-11
- Verified behavior: local tests, typecheck, build, and offline smoke passed before this information-page update. The latest observed successful Cloud run was `ywvdKNw0LMgXfnfik`, completed 2026-09-10 with build `xab6roYMTXB8o8PKS`.
- Maintenance promise: no response-time or future-maintenance promise is made here. Use the Issues tab with a run ID and reproducible input for a defect report.

### Why choose Google Trends Intelligence?

- Returns three typed record shapes for timeline, related-query, and summary use cases.
- Separates a genuine no-match from an unavailable source with `zeroMatch` and `sourceStatus`.
- Keeps source URLs and retrieval timestamps on every record for downstream verification.
- Use it for relative interest and query discovery, not as an absolute-search-volume source.

### Other Skootle Actors you might want to check

- [Website SEO Audit Intelligence](https://apify.com/skootle/website-seo-audit-intelligence) to evaluate a site after a demand hypothesis is selected.
- [Website Tech Stack Intelligence](https://apify.com/skootle/website-tech-stack-intelligence) to add technology and integration context to website research.
- [Federal Contract Intelligence](https://apify.com/skootle/usaspending-contract-intelligence) to pair public-sector demand research with award and agency evidence.

### Support and contact

File bugs or feature requests through the Actor's Issues tab. Include the run ID, input, and the field or behavior that looks wrong. Do not include private data or credentials in an issue.

# Actor input Schema

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

One to five search terms. Multiple terms are normalized against the same comparison scale.

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

Google Trends geo code, such as US, GB, US-CA, or an empty string for worldwide.

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

Google Trends time window.

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

Google Trends category ID. Use 0 for all categories.

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

Search surface. An empty value means web search.

## `maxRelatedQueries` (type: `integer`):

Maximum rows from each of the top and rising lists, per keyword.

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

Return normalized timeline points and compute time-series metrics.

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

Return top and rising related searches for each keyword.

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

Google Trends interface locale.

## `proxyCountryCode` (type: `string`):

Two-letter country code for the residential proxy exit.

## `maxRetriesPerRequest` (type: `integer`):

Bounded retry count for transient and blocked responses.

## Actor input object example

```json
{
  "keywords": [
    "artificial intelligence",
    "machine learning"
  ],
  "geo": "US",
  "timeframe": "today 3-m",
  "category": 0,
  "property": "",
  "maxRelatedQueries": 25,
  "includeInterestOverTime": true,
  "includeRelatedQueries": true,
  "language": "en-US",
  "proxyCountryCode": "US",
  "maxRetriesPerRequest": 4
}
```

# Actor output Schema

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

No description

## `runReport` (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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("skootle/google-trends-intelligence").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("skootle/google-trends-intelligence").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 '{}' |
apify call skootle/google-trends-intelligence --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,skootle/google-trends-intelligence"
        }
    }
}
```

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/EfqQ3udyvtb1m4lXm/builds/Z1JRKTZ350SUITsJS/openapi.json