# Google Trends Unlimited Compare (`naheal94/google-trends-unlimited-compare`) Actor

Compare unlimited keywords on ONE Google Trends scale (not just 5). Interest over time, related & breakout queries, interest by region, and daily trending searches by country. One result per keyword; errors are never billed.

- **URL**: https://apify.com/naheal94/google-trends-unlimited-compare.md
- **Developed by:** [HyeonWoo Park](https://apify.com/naheal94) (community)
- **Categories:** SEO tools, Marketing, Automation
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $4.00 / 1,000 keyword results

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 Unlimited Compare

Compare **any number of keywords on one Google Trends scale** — not just 5 — and get everything for each keyword in **one result**.

Google Trends compares at most 5 terms, and every comparison is rescaled to its own 0–100 peak, so numbers from different comparisons can't be put side by side. This Actor splits your list into 5-term batches that all share one **anchor keyword**, then rescales every batch to that anchor. Every keyword lands on one comparable scale.

**Accuracy check:** stitched values vs. Google's own 5-term comparison differed by **0.26 points on average (max 0.7 of 100)** in our test (US, 12 months).

### What you get — one result per keyword

| Field | Contents |
|---|---|
| `interestOverTime` | timeline on one scale shared by all keywords, average, anchor |
| `relatedQueries` | top and rising queries, with **Breakout** flags |
| `interestBySubregion` | states / provinces |
| `interestByCity` | cities (with coordinates) |
| `interestByMetro` | US metro areas (DMA) |

Plus `trending_now`: today's trending searches per country, with approximate traffic and news links (one result per country).

You pay **per keyword**, not per data type or per day of the timeline. Pick only what you need in **What to get**.

### Inputs

- **Keywords** — up to 500 per run, all on one scale
- **Google Trends URLs** — paste any `trends.google.com/trends/explore?...` link; its terms, country, time range, category and search type are used as-is
- Country/region, time range (`now 7-d` … `today 5-y`, or `2024-01-01 2024-12-31`), category, search type (web, YouTube, News, Images, Shopping)

```json
{
  "keywords": ["python", "javascript", "rust", "golang", "kotlin", "swift", "typescript"],
  "data": ["interest_over_time", "related_queries", "interest_by_subregion"],
  "geo": "US",
  "timeframe": "today 12-m",
  "startUrls": [{"url": "https://trends.google.com/trends/explore?date=today%203-m&geo=GB&q=tea,coffee"}],
  "trendingGeos": ["US"]
}
```

### Output example

```json
{
  "type": "keyword",
  "keyword": "rust",
  "geo": "US",
  "timeframe": "today 12-m",
  "interestOverTime": {"anchor": "python", "average": 29.9, "timeline": [{"time": "2025-11-09T00:00:00Z", "value": 31.0}]},
  "relatedQueries": {"top": [{"query": "what is rust", "value": 100}], "rising": [{"query": "...", "formattedValue": "Breakout", "breakout": true}]},
  "interestBySubregion": [{"geoCode": "US-WY", "geoName": "Wyoming", "value": 100}],
  "interestByMetro": [{"geoCode": "759", "geoName": "Cheyenne WY-Scottsbluff NE", "value": 100}]
}
```

Values are on the scale of the anchor batch: 100 = that batch's peak; terms more popular than it can exceed 100.

### Reliability and fair billing

- Requests run in parallel (default 5, up to 10), each with its own proxy session, with automatic back-off on Google rate limits. In one test, 192 keywords × (timeline + related queries + subregions) finished in under 9 minutes, twice at the same time. Google does rate-limit heavy, repeated use from the same proxies; when that happens the run slows down and reports what it could not fetch.
- A keyword with **no data at all is never billed**.
- If one part could not be fetched after all retries, the result says so in `incomplete` (e.g. `["relatedQueries"]`) instead of silently leaving it out.
- Every warning and error is listed in the run's **Issues** output (key-value store record `ISSUES`), saved during the run so it survives an abort.

### Tips

- **Anchor choice matters.** Pick a steady, medium-popularity term related to your list.
- Keep the default Apify Proxy for large runs; Google rate-limits heavy use.

### Limits

- Up to 500 keywords per run.
- Related *topics* are not offered: Google currently returns them empty through its public endpoints.
- Google returns no city data for some countries and time ranges; regions without data are left out.
- Values are relative interest (Google Trends), not absolute search volume.

# Actor input Schema

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

Search terms. Any number (up to 500) — all are put on ONE comparable scale, not Google's 5-term limit.

## `startUrls` (type: `array`):

Paste Google Trends explore URLs (trends.google.com/trends/explore?...). Each URL keeps its own terms, country, time range, category and search type.

## `data` (type: `array`):

Everything you pick for a keyword is bundled into ONE result (one charge per keyword).

## `anchor` (type: `string`):

Term shared by every 5-term batch to stitch them together. Pick a steady, mid-popularity term. Default: the first keyword.

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

ISO code like US, KR, GB, US-CA. Empty = worldwide.

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

Google Trends time string, e.g. 'now 7-d', 'today 1-m', 'today 3-m', 'today 12-m', 'today 5-y', '2024-01-01 2024-12-31'.

## `searchProperty` (type: `string`):

Which Google search to measure: web, YouTube, News, Images or Shopping.

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

Google Trends category (0 = all).

## `trendingGeos` (type: `array`):

Country codes for today's trending searches (with approximate traffic and news), e.g. US, KR, JP.

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

Language for query and region names, e.g. en-US, ko, ja.

## `maxConcurrency` (type: `integer`):

How many Google Trends requests run at once (each with its own proxy session). Higher is faster; lower is gentler on rate limits.

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

Google rate-limits heavy use. Apify Proxy keeps large runs reliable.

## Actor input object example

```json
{
  "keywords": [
    "python",
    "javascript",
    "rust",
    "golang",
    "kotlin",
    "swift",
    "typescript"
  ],
  "data": [
    "interest_over_time",
    "related_queries",
    "interest_by_subregion"
  ],
  "geo": "",
  "timeframe": "today 12-m",
  "searchProperty": "web",
  "category": 0,
  "trendingGeos": [],
  "language": "en-US",
  "maxConcurrency": 5,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

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

Dataset items: interest_over_time (shared scale), related_queries, interest_by_region, trending_now.

## `issues` (type: `string`):

Warnings and errors (rate limits, empty data) that were not billed as results.

# 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": [
        "python",
        "javascript",
        "rust",
        "golang",
        "kotlin",
        "swift",
        "typescript"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("naheal94/google-trends-unlimited-compare").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": [
        "python",
        "javascript",
        "rust",
        "golang",
        "kotlin",
        "swift",
        "typescript",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("naheal94/google-trends-unlimited-compare").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": [
    "python",
    "javascript",
    "rust",
    "golang",
    "kotlin",
    "swift",
    "typescript"
  ]
}' |
apify call naheal94/google-trends-unlimited-compare --silent --output-dataset

```

## MCP server setup

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

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/mIyx093n2aENa9na2/builds/eSonSWjPFdzyEcPPm/openapi.json