# Google Trends Search Interest Monitor (`codeclouds/google-trends-search-interest-monitor`) Actor

Monitor Google Trends search interest per keyword, geo and time window. Returns time-series data, related queries and rising queries.

- **URL**: https://apify.com/codeclouds/google-trends-search-interest-monitor.md
- **Developed by:** [Dennis](https://apify.com/codeclouds) (community)
- **Categories:** Business, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 keyword monitoreds

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 Search Interest Monitor

Monitor Google Trends search interest for one or more keywords across a geographic region and time window. Each keyword returns a time-series of search-interest values, plus related and rising (breakout) queries. Designed for SEO planning, content strategy, market-trend tracking, competitive-intelligence workflows, and AI-agent pipelines that need structured trend data.

### EU / European Focus (Key Differentiator)

Unlike the generic official Apify actor (US-centric), this actor is optimized for EU markets. Default geo: `NL`. Supported EU geo codes: `NL`, `BE`, `DE`, `FR`, `GB`, `ES`, `IT`, and sub-regions (`NL-UT`, `BE-VLG`, `GB-ENG`). The SEO and content-planning use cases are structured for Dutch/European SEO teams, with Dutch-language keywords in the store listing for local discoverability.

### Portfolio Pipeline Examples (AI-Agent Integration)

This actor is designed to be combined with other CodeClouds actors:

- **Trend + Price Intelligence**: Combine with `[universal-price-monitor]` to detect when a rising search term (e.g., "bitcoin etf") aligns with price shifts.
- **Trend + Regional Targeting**: Combine with `[nl-poi-finder-cbs-buurtverrijking]` to map rising local queries (`"zonnepanelen NL"`) to neighborhood-level business opportunities.
- **Trend + Change Detection**: Combine with `[dataset-diff]` for scheduled monitoring (weekly `previousDatasetId` input) to detect market shifts automatically.
- **Trend + Structured Validation**: Combine with `[url-to-structured-fact]` to validate news articles that reference rising breakout terms.

### When should an AI agent use this?

- "What are the rising search queries for 'bitcoin' in the US over the last 12 months?"
- "Show the search-interest trend for 'climate change' in NL and BE and list related terms."
- "Which keywords are breaking out in Germany for the keyword 'electric vehicles'?"
- "Compare search volume patterns for two competitor brands over time."
- "Generate a weekly trend report with rising queries per monitored keyword."
- "Monitor 'solar panels' in GB and alert when rising queries include new technology terms."

### What this Actor does

This actor connects to the unofficial but widely used Google Trends `explore` endpoint (`trends.google.com/trends/api/*`), the same endpoint leveraged by the open-source `pytrends` library and by several existing Apify Google Trends actors (including the official `apify` actor with 13,451 users). It sends the user-provided keywords together with a geo region and time-range parameter, then parses the JSON response into a clean dataset.

Capabilities:

- **Keyword monitoring**: up to 5 keywords per run (`bitcoin`, `climate change`, etc.).
- **Geographic targeting**: country-level codes (`US`, `NL`, `BE`, `GB`, and others supported by Google Trends).
- **Flexible time windows**: 90 days, 12 months, 5 years, or the full historical range (`all 2004-to-now`).
- **Time-series extraction**: normalized interest scores (0–100 scale) relative to the peak in the selected region/time window.
- **Related queries**: terms that Google associates with the monitored keyword (`relatedQueries`).
- **Rising (breakout) queries**: fast-growing terms linked to the keyword (`risingQueries`).
- **Rate-limit resilience**: if Google returns HTTP 429, the run continues processing remaining keywords; errors are reported per keyword rather than crashing the entire run.
- **No authentication**: no API key, no login, no personal data handled.

The actor uses Node.js native `fetch` (no extra scraping dependencies) and structures output as a flat dataset suitable for downstream analysis, reporting, or AI-agent consumption.

### How it works (technical overview)

1. The actor reads the `INPUT.json` (keywords, geo, timeRange).
2. It builds a Google Trends `explore` payload (`req` parameter) containing the comparison items.
3. It sends the payload to `https://trends.google.com/trends/api/explore` with a standard browser `User-Agent`.
4. It attempts to parse the JSON response for:
   - `timelineData`: historical indexed values per date.
   - `relatedSearches.top`: related queries.
   - `relatedSearches.rising`: rising (breakout) queries.
5. If the endpoint returns HTTP 429 (Too Many Requests), the actor records the error per keyword and continues with the remaining keywords.
6. Each successful result is pushed to the Apify dataset and a `trends-keyword-monitored` event is charged.

Note: the exact response structure can vary because Google does not document this endpoint; the mapping is best-effort based on the `pytrends` precedent and live verification. If a field is missing in the response, a default or empty value is returned.

### Input

| Field | Type | Description |
|---|---|---|
| `keywords` | array (string) | Search terms to monitor. Example: `["bitcoin", "climate change"]`. Maximum 5 terms per run for rate-limit safety; multi-keyword comparison supported. |
| `geo` | string | Geographic region. Default: `NL` (EU focus). Supported: `NL`, `BE`, `DE`, `FR`, `GB`, `ES`, `IT`, `US`, etc. |
| `timeRange` | string | Time window: `today 90-d`, `today 12-m` (default), `today 5-y`, `all 2004-to-now`. |
| `previousDatasetId` | string (optional) | Dataset ID from a previous run for change detection (`newRisingQueries`, `trendShift`). |
| `proxyUrl` | string (optional) | Proxy URL for rate-limit resilience. |
| `retryAttempts` | integer | Retries for 429 errors (default: 2, max: 5). |
| `backoffDelayMs` | integer | Initial backoff delay in ms (default: 1000). |

Example input:

```json
{
  "keywords": ["bitcoin", "electric vehicles"],
  "geo": "US",
  "timeRange": "today 12-m"
}
```

### Output

Each dataset item represents one monitored keyword. The dataset schema is defined in `.actor/dataset_schema.json` and `OUTPUT_SCHEMA.json`.

Fields per item:

- `keyword` (string): the monitored search term.
- `geo` (string): the geographic region applied.
- `timeRange` (string): the time window applied.
- `interestOverTime` (array): time-series points with `date` (YYYY-MM-DD) and `value` (normalized 0–100 interest score).
- `relatedQueries` (array): related search terms with `query` (string) and `value` (normalized score).
- `risingQueries` (array): fast-growing (breakout) search terms with `query` (string) and `value` (normalized score, often >100 for breakout terms).
- `trendDirection` (string): `opkomend`, `stabiel`, or `dalend` — calculated from time-series start vs. end.
- `breakoutSignals`: fast-growing terms (`value > 100`).
- `summary` (string): AI-generated insight summarizing the trend, peak, breakout terms, and reliability.
- `actionableTags` (array): `opkomend`, `dalend`, `breakout_gedetecteerd`, `veel_gerelateerde_termen`.
- `reliabilityScore` (number): 0–1, based on data completeness.
- `regionBreakdown` (optional): region-level values when `geo` is country-level and Google provides sub-region data.
- `relatedTopics` (optional): topic-level related data (`topTopics`).
- `comparisonSummary` (optional): for multi-keyword runs — relative peak score and comparison keyword.
- `newRisingQueries`, `droppedQueries`, `trendShift` (optional): monitoring-mode fields when `previousDatasetId` is set.
- `contentOpportunityScore` (number): 0–100 score for breakout-term intensity.
- `runStatus`: `success`, `partial` (some keywords 429), or `rate_limited`.
- `updatedAt` (string): ISO timestamp of the run.
- `error` (optional, string): present only when a rate limit or network error occurred for this keyword.

Example output item:

```json
{
  "keyword": "bitcoin",
  "geo": "US",
  "timeRange": "today 12-m",
  "interestOverTime": [{ "date": "2026-09-01", "value": 42 }],
  "relatedQueries": [{ "query": "bitcoin price", "value": 95 }],
  "risingQueries": [{ "query": "bitcoin etf", "value": 120 }],
  "updatedAt": "2026-09-20T17:35:00.000Z"
}
```

Because Google Trends provides normalized (relative) scores rather than absolute search volumes, comparing values across different geo regions or time windows requires care. A score of 100 always represents the peak interest in the selected region/time window.

### Use cases (detailed)

#### SEO and content strategy

Content teams can use rising queries (`risingQueries`) to discover emerging topics before they become saturated. For example, if `bitcoin etf` appears as a rising query, that indicates growing user interest in exchange-traded funds linked to cryptocurrency — a signal to publish or update content around that sub-topic.

Related queries (`relatedQueries`) help expand keyword clusters: if a page targets `bitcoin`, adding sections on `bitcoin price` or `bitcoin wallet` (related terms) improves topical relevance and captures long-tail traffic.

#### Competitive tracking

Monitoring competitor brand names alongside your own allows trend comparison over the same time window and region. Because the data is normalized, comparing two keywords within the same run is valid; cross-run absolute comparisons require consistent geo/time settings.

#### Market-intelligence agents

The structured JSON output is designed for consumption by AI agents or downstream automation. An agent can feed `risingQueries` into a content-planning pipeline, combine `interestOverTime` with external data sources, or trigger alerts when a keyword's interest drops or a new breakout term appears.

#### Trend reporting

Scheduled runs (e.g. weekly) with a fixed `timeRange` (`today 12-m`) produce comparable time-series. The dataset can be exported or connected to a BI tool for visual trend analysis.

### Pricing (Pay Per Event)

This actor uses Apify's Pay-Per-Event (PPE) model.

- **Actor Start:** $0.00005 (Apify default — applies once per run, regardless of keyword count).
- **trends-keyword-monitored:** $0.005 per monitored keyword (includes time-series, related queries, rising queries, region breakdown, related topics, comparison summary, AI summary, actionable tags, reliability score, trend direction, breakout signals, monitoring diff fields, run status). Charged only for successful results (`success` or `partial`); `rate_limited` errors are not charged.
- **trends-insight-generated:** $0.01 per keyword (premium event, charged when `summary` and `actionableTags` are present — AI-ready output mode).
- **trends-change-detected:** $0.015 per keyword (premium event, charged when `newRisingQueries` or `trendShift` fields are present — monitoring/change-detection mode).

Underb Bouw:
The pricing is set at a low tier ($0.002 per keyword) to remain competitive against the dominant incumbent (`apify`'s official Google Trends actor, 13,451 users but 3.68★ / 32 reviews) and the high-rated challenger (`data_xplorer`, 1,777 users, 4.88★). The value proposition is stronger output structure (related + rising queries in a single call) and graceful rate-limit handling, not a premium price. If additional signals (e.g. region breakdown or incremental monitoring) are added in a future version, the price can be adjusted.

### Technical details

#### Source endpoint

- URL: `https://trends.google.com/trends/api/explore`
- Method: `GET` with `req` query parameter containing the comparison payload.
- Authentication: none required.
- Rate limits: actively enforced (HTTP 429 observed in live verification on 2026-09-20). The actor handles 429 gracefully by continuing the run.
- Response format: JSON (undocumented, based on `pytrends` analysis and live testing).

#### Dependencies

The actor uses only the `apify` SDK and `zod` for input validation. No external scraping libraries are required. The `fetch` call is made via the native Node.js `globalThis.fetch` (available in Node 18+), keeping the dependency footprint minimal.

#### Error handling strategy

Each keyword is processed independently. If one keyword triggers a rate limit or network failure, the remaining keywords are still processed. Errors are recorded in the dataset (`error` field) rather than causing a complete run failure. This aligns with the portfolio's L04/L06 lessons (per-item error isolation for scraper actors).

### Legal and compliance

Data source: Google Trends (`trends.google.com/trends/api/*`), an unofficial but widely used endpoint. The same endpoint is used by:

- The open-source `pytrends` library (3.7k stars, actively referenced).
- Multiple existing Apify Google Trends actors (including the official `apify` actor with 13,451 users, `data_xplorer` with 1,777 users, `agenscrape` with 1,048 users, and others).

No login, no API key, no personal data, and no business-confidential data is handled. The dataset is purely aggregated, public search-interest statistics.

Juridisch risico: laag. The endpoint is undocumented (a Google Terms of Service grey zone for scraping an internal API), but this is standard practice across the entire market segment. There is no AVG/privacy concern because no individual-level data is processed. The actor does not claim official Google endorsement.

### FAQ (expanded)

**Q: Why does my run report HTTP 429 errors?**
A: Google actively rate-limits requests to the Trends endpoint. The exact rate-limit threshold is not documented. If you encounter frequent 429 errors, reduce the number of keywords per run (maximum is already limited to 5), increase the delay between runs when scheduling, or rotate proxies. The actor continues processing all remaining keywords even when one hits a 429.

**Q: Can I monitor more than 5 keywords?**
A: The input limit is 5 keywords per run. This keeps the payload size manageable and reduces the probability of hitting rate limits. For larger keyword sets, split them into multiple tasks or batches. Each batch will produce its own dataset, which can be merged downstream.

**Q: Does the output include absolute search volume?**
A: No. Google Trends provides normalized interest scores on a 0–100 scale relative to the peak value in the selected region and time window. This means:

- A score of 100 represents the highest search interest in the dataset.
- You cannot derive absolute query counts (e.g. "10,000 searches per day") from this data.
- Cross-region comparisons within the same run are valid, but comparing absolute values across different geo codes requires care because each region's peak is normalized independently.

**Q: What is the difference between related and rising queries?**
A: `relatedQueries` are topics linked to the keyword (e.g. for `bitcoin`, related terms might include `bitcoin price` or `bitcoin wallet`). `risingQueries` are fast-growing or breakout terms linked to the keyword; these often represent emerging trends or news-driven spikes. A rising query value above 100 indicates a breakout term.

**Q: Is this actor suitable for scheduled monitoring?**
A: Yes. The actor is stateless: each run takes the current input and produces a fresh dataset. For scheduled monitoring, you can set up a recurring Apify schedule with the same `INPUT.json`. There is no incremental/change-detection mode in v0.1; comparing results across runs requires external dataset comparison (e.g. with `dataset-diff`).

**Q: Why does the description say the endpoint is "unofficial"?**
A: Google does not document or support the `trends/api/explore` endpoint as a public API. However, it has been reverse-engineered and used by `pytrends` and multiple commercial Apify actors for years without enforcement action. The actor is transparent about this limitation.

**Q: Can I use this actor for commercial SEO reporting?**
A: Yes. The data is public aggregate statistics with no licensing restriction from Google (the ToS grey zone applies to scraping method, not to using aggregated public statistics). The PPE pricing ($0.002 per keyword) makes it cost-effective for regular reporting.

### Related Actors

No other live CodeClouds actor currently provides Google Trends monitoring. Consider pairing this actor with:

- `[url-to-structured-fact](https://apify.com/codeclouds/url-to-structured-fact)` — for validating external sources that reference trend-related news or reports.
- `[dataset-diff](https://apify.com/codeclouds/dataset-diff)` — for detecting changes between two trend runs (e.g. new rising queries or interest-level shifts).
- `[universal-price-monitor](https://apify.com/codeclouds/universal-price-monitor)` — for combining trend data with pricing or market-monitoring pipelines.

Note: link URLs are only included for actors that have a public Store page (`PORTFOLIO_STATUS.md` is the source of truth for live URLs).

***

### Keywords / Zoektermen / Search terms

*English:* google trends, search interest, keyword monitoring, seo tool, trend analysis, rising queries, breakout queries, content planning, market intelligence, competitive tracking, time-series data, normalized interest score, related queries, breakout terms.

*Local context (for Dutch/European discoverability):* zoekinteresse, zoekwoordmonitor, SEO-analyse, trendanalyse, contentplanning, zoekvolume, opkomende zoekopdrachten, gerelateerde zoekopdrachten.

### Changelog

#### 0.1.0 (2026-09-20)

- Initial scaffold: input parsing (`keywords`, `geo`, `timeRange`), rate-limit handling (HTTP 429 graceful continuation), output mapping (`trendResult` with `interestOverTime`, `relatedQueries`, `risingQueries`), basic error isolation per keyword.
- Core logic module (`src/trends.ts`) with payload construction, fetch, and best-effort JSON parsing based on the `pytrends` endpoint pattern.
- Unit tests (3/3 green): normal mapping, 429 rate limit, unknown fetch error.
- Icon (`icon.png` / `icon.svg`): magenta rising line with data points, visually verified, unique hash (not identical to other portfolio actors).
- Store info (`STOREINFO.md`): title, SEO fields, categories, tags, pricing (`trends-keyword-monitored` $0.002), and 1 published task.
- Documentation (`README.md`, `PROJECTINFORMATIE.txt`, `PUBLISHING_INFO.txt`) completed in English with SEO keywords, MCP-oriented use cases, pricing justification, and legal disclaimer.
- Portfolio status updated (`PORTFOLIO_STATUS.md`): `🛠️ In ontwikkeling`.

#### Planned (v0.2 / future)

- Incremental/monitor mode: cross-run change detection (new/rising queries, interest shifts).
- Proactive rate-limit mitigation: backoff/retry and optional proxy rotation.
- Additional geo-level breakdown (`interest_by_region`) support.
- Expanded output: `relatedTopics` (topic-level related data) and `multirange` comparison.

# Actor input Schema

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

Search terms to monitor (e.g. \['bitcoin', 'climate change']).

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

Geographic region code for Google Trends (EU focus: NL, BE, DE, FR, GB, ES, IT, EU-27; or US, CA, AU). Default: NL.

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

Time window for trends data (e.g. 'today 12-m', 'today 5-y', 'today 90-d').

## `previousDatasetId` (type: `string`):

Dataset ID from a previous run for change detection and trend monitoring (e.g. monitoring mode: new rising queries, trend shifts).

## `proxyUrl` (type: `string`):

Optional proxy URL for rate-limit resilience (e.g. https://user:pass@proxy.apify.com).

## `retryAttempts` (type: `integer`):

Number of retries for rate-limited keywords.

## `backoffDelayMs` (type: `integer`):

Initial delay between retries (exponential backoff).

## Actor input object example

```json
{
  "keywords": [
    "bitcoin"
  ],
  "geo": "NL",
  "timeRange": "today 12-m",
  "retryAttempts": 2,
  "backoffDelayMs": 1000
}
```

# Actor output Schema

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

Results stored in the default dataset.

# 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": [
        "bitcoin"
    ],
    "geo": "NL",
    "previousDatasetId": ""
};

// Run the Actor and wait for it to finish
const run = await client.actor("codeclouds/google-trends-search-interest-monitor").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": ["bitcoin"],
    "geo": "NL",
    "previousDatasetId": "",
}

# Run the Actor and wait for it to finish
run = client.actor("codeclouds/google-trends-search-interest-monitor").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": [
    "bitcoin"
  ],
  "geo": "NL",
  "previousDatasetId": ""
}' |
apify call codeclouds/google-trends-search-interest-monitor --silent --output-dataset

```

## MCP server setup

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

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/ja869nTEzQWhpO2Kp/builds/PJZQFFzhyz0WXUM7O/openapi.json