# Google Trends API — Pay Per Result, No Empty Charges (`greza/google-trends-realtime`) Actor

Google Trends via a resilient API: interest over time, cross-term compare (one 0–100 scale), related, interest by region, realtime trending. Pay per result — never charged for empty data.

- **URL**: https://apify.com/greza/google-trends-realtime.md
- **Developed by:** [Sergei Peleskov](https://apify.com/greza) (community)
- **Categories:** SEO tools, Developer tools, News
- **Features:** Limited permissions
- **Stats:** 10 total users, 4 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 keyword results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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 API — Pay Per Result, No Empty Charges

Google Trends data through a **resilient API**: interest over time, **cross-term compare** (2–5 keywords on one shared 0–100 scale), related queries & topics, interest by region, and **realtime trending**. You pay **per result** — and **never for empty data**.

Built for people who tried the official Google Trends API and hit its walls: alpha status, quotas, Google Cloud auth, and **no recent/realtime data**.

***

### Why this Actor

#### This Actor vs typical / official Trends scrapers

| | This Actor | Typical / official Trends API |
|---|---|---|
| **Pay for empty results** | ❌ Never — empty = `no_data`, not billed | ✅ You pay for the call regardless |
| **Realtime windows** (`now 1-H`…`now 7-d`) | ✅ Yes | ❌ Official alpha has no recent data |
| **Retries + residential rotation** | ✅ Built in — survives the first 429, doesn't fall over | ❌ You handle 429s / IP bans yourself |
| **Cross-term scaling** (up to 5 keywords, one 0–100 scale) | ✅ Yes | ❌ Single-keyword scales only |
| **Related + interest-by-region** | ✅ One Actor, one contract | ⚠️ Fragmented / partial |
| **Pricing** | ✅ Pay-per-event, pay for what you use | ❌ Quota tiers / rental subscription |
| **Platform usage on top** | ✅ Never — all-inclusive | ❌ Compute + proxy billed separately |

Reliability (retries, residential IP rotation, backpressure with `Retry-After`) is handled server-side — you just get **stable results that don't break on the first rate-limit**.

#### Price on the tag vs price on the invoice

Most Trends scrapers charge **$X /1,000 results + Apify platform usage on top** (compute units, proxy, storage). The sticker price is not the final price.

This Actor is **pay-per-event, all-inclusive**: $5.00 /1,000 keyword results already covers residential proxies, retries, and compute. No platform usage line on your bill. Empty results (`no_data`) are never billed.

Run 1,000 keywords, get a predictable invoice. That's the whole pricing model.

***

### Scrape types

Pick one via `scrapeType`:

- **`interestOverTime`** — popularity of each keyword over time (independent 0–100 scale per keyword).
- **`compare`** — 2–5 keywords on **one shared 0–100 scale** (cross-term scaling). One request, one price — comparable numbers across terms.
- **`related`** — top & rising related queries and topics.
- **`interestByRegion`** — geographic breakdown (`COUNTRY` / `REGION` / `CITY` / `DMA`).
- **`trendingNow`** — realtime trending searches for a location.

***

### Input

```json
{
  "scrapeType": "interestOverTime",
  "keywords": ["bitcoin", "ethereum"],
  "geo": "US",
  "timeRange": "today 3-m",
  "category": 0
}
```

| Field | Type | Notes |
|---|---|---|
| `scrapeType` | enum | `interestOverTime` | `compare` | `related` | `interestByRegion` | `trendingNow` |
| `keywords` | string\[] | 1–50; **exactly 2–5 for `compare`**; not required for `trendingNow` |
| `geo` | string | `""` = worldwide, `US`, `US-CA` |
| `timeRange` | enum | `now 1-H`…`now 7-d`, `today 1-m`…`today 5-y`, `all`, `custom` |
| `customTimeRange` | string | when `timeRange=custom`: `YYYY-MM-DD YYYY-MM-DD` |
| `category` | integer | Google category id, `0` = all |
| `resolution` | enum | `interestByRegion` only: `COUNTRY`/`REGION`/`CITY`/`DMA` |

No proxy configuration — residential rotation is included.

***

### Output

One dataset item per keyword × scrape type (compare = one item for the group). Data mirrors the normalized API schema, plus the request fields (`kw`/`keywords`, `geo`, `time`) for easy filtering.

**interestOverTime**

```json
{ "scrapeType": "interestOverTime", "kw": "bitcoin", "geo": "US", "time": "today 3-m",
  "points": [{ "date": "Jun 1, 2026", "value": 52, "isPartial": false }] }
```

**compare** (one shared 0–100 scale, order preserved)

```json
{ "scrapeType": "compare", "geo": "US", "time": "today 3-m",
  "keywords": ["btc", "eth", "doge"],
  "points": [{ "date": "Jun 5, 2026", "isPartial": false,
               "values": { "btc": 100, "eth": 26, "doge": 13 } }],
  "keywords_meta": {} }
```

Low-volume terms come back with `values: 0` and a `keywords_meta[kw]: "low_volume"` flag — the run never fails on them.

**No data / failed** (never billed)

```json
{ "scrapeType": "related", "kw": "asdfqwerzxcv", "geo": "US", "status": "no_data" }
```

***

### Pricing (pay per event)

You are charged **only for delivered non-empty results**:

| Event | When | Price |
|---|---|---|
| `keyword-result` | one keyword returned data (iot / related / region) | $0.005 |
| `compare-result` | one 2–5 keyword comparison returned data (**once, not ×5**) | $0.005 |
| `trending-page` | one realtime trending page returned data | $0.005 |

**Never charged:** empty results (`no_data`), failed requests, or any error. Compare is one event for the whole group — that's the point of batching.

***

### FAQ

**How is this different from the official Google Trends API?**
The official API is alpha: quota-limited, requires Google Cloud auth, and has **no recent/realtime data**. This Actor gives realtime windows (`now 1-H`…`now 7-d`), needs only an Apify token, and bills per delivered result instead of per quota unit.

**Why did I get `no_data` for a keyword?**
Google returned a valid response with no data for that term (too low volume, or no coverage in the geo). It's in the dataset with `status: "no_data"` and is **not billed**.

**What happens under heavy load?**
The backing service applies backpressure (`503` + `Retry-After`); the Actor honors it — waits and retries automatically, so your run doesn't drop requests.

**Can I compare keywords on the same scale?**
Yes — `scrapeType: "compare"` with 2–5 keywords puts them on one shared 0–100 scale (cross-term scaling), so the numbers are directly comparable.

***

### Integrations

Works with the Apify **API**, **n8n**, **Make**, and **MCP** — run it and pull results from the dataset like any Actor.

Example (API run input):

```json
{ "scrapeType": "compare", "keywords": ["btc", "eth", "doge"], "geo": "US", "timeRange": "today 3-m" }
```

***

### Notes for operators

- Requires two **secret environment variables** on the Actor: `GATEWAY_URL` and `GATEWAY_API_KEY` (never in input, never hardcoded).
- Optional env: `ACTOR_CONCURRENCY` (default 8), `GATEWAY_RETRY_503` (default 6).

# Actor input Schema

## `scrapeType` (type: `string`):

Which Google Trends dataset to fetch. `compare` puts 2–5 keywords on ONE shared 0–100 scale (cross-term scaling).

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

Search terms. 1–50 for most types; exactly 2–5 for `compare`. Not required for `trendingNow`.

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

ISO country or region: empty = worldwide, `US`, `US-CA`. Pattern `^$|^[A-Z]{2}(-[A-Z0-9]{1,3})?$`.

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

Realtime windows (`now *`) are supported — unlike the official Trends API. Pick `custom` to supply an explicit date range below.

## `customTimeRange` (type: `string`):

Only used when Time range = `custom`. Format `YYYY-MM-DD YYYY-MM-DD` (e.g. `2026-01-01 2026-03-01`).

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

Google Trends category id. 0 = all categories.

## `resolution` (type: `string`):

Only for `interestByRegion`: granularity of the geo breakdown.

## Actor input object example

```json
{
  "scrapeType": "interestOverTime",
  "keywords": [
    "bitcoin"
  ],
  "geo": "",
  "timeRange": "today 3-m",
  "category": 0,
  "resolution": "COUNTRY"
}
```

# 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"
    ]
};

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

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

```

## MCP server setup

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

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/CZvdrF4zqWMsRftEf/builds/5cWHK9Zs6Ud1uQGC7/openapi.json