# Google Trends API: Interest, Regions, Related & Trending (`datafaro/google-trends-api`) Actor

Reliable Google Trends API for AI agents and developers: interest over time, interest by region, related queries and trending searches. Compact JSON with a plain-English summary per keyword. pytrends alternative, MCP-ready.

- **URL**: https://apify.com/datafaro/google-trends-api.md
- **Developed by:** [Datafaro](https://apify.com/datafaro) (community)
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.50 / 1,000 query 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 API: Interest, Regions, Related & Trending (Fast, AI-Ready)

A reliable **Google Trends API** for AI agents and developers. Ask for **interest over time**, interest by country or region, related queries, or what's trending right now. You get compact JSON with a **plain-English summary** for every keyword, so an agent can answer straight from the summary without reading the data points.

- **Built for AI agents.** Six input fields, all with defaults, and errors that say how to fix the input. Works as an **MCP** tool for Claude, Cursor and any MCP client.
- **Small output.** One item per keyword, not one per data point, plus a single `OUTPUT` JSON for fast `run-sync` calls.
- **Reliable.** Residential proxy with session rotation, exponential backoff with jitter, and per-keyword failure isolation. A broken keyword never sinks the run, and you don't pay for it.
- **pytrends alternative.** pytrends was archived in April 2025. This Actor talks to Google Trends directly and needs no Python setup on your side.

### What it does

| `mode` | What you get | Keywords |
|---|---|---|
| `compare` (default) | Interest over time, all keywords on one shared 0–100 scale, with average, peak, trend and % change | 1–5 |
| `by_region` | Interest by region within `geo` (e.g. US states), or by country when `geo` is `""`, each keyword on its own 0–100 scale | 1–5 |
| `related` | Related search queries, both top and rising | exactly 1 |
| `trending_now` | Current trending searches in a country (Google has no worldwide list; empty `geo` shows the US), with approximate traffic and news links | ignored |

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | enum | `compare` | `compare`, `by_region`, `related`, `trending_now` |
| `keywords` | string\[] | `["chatgpt", "claude"]` | 1–5 search terms (exactly 1 for `related`, ignored by `trending_now`) |
| `geo` | string | `""` (worldwide) | Worldwide: `""`, `"WORLD"` or `"worldwide"`. A country: ISO code like `US`. A region: `US-CA`. `trending_now` needs a country; with an empty or worldwide `geo` it shows the US and adds a note. |
| `timeframe` | enum | `past_12_months` | `past_day`, `past_7_days`, `past_30_days`, `past_90_days`, `past_12_months`, `past_5_years` |
| `category` | integer | `0` | Google Trends category ID (0 = all) |
| `property` | enum | `web` | `web`, `youtube`, `news`, `images`, `shopping` |

An empty input `{}` runs the defaults: `chatgpt` vs `claude` worldwide over the past 12 months. Example:

```json
{ "mode": "compare", "keywords": ["claude", "chatgpt"], "geo": "ES", "timeframe": "past_12_months" }
```

Invalid input fails the run immediately with a message you can act on, e.g. `Invalid input. mode "related" takes exactly 1 keyword`. Nothing is charged.

### Output

One dataset item per keyword. For `trending_now` it's one item for the country. Every item has the same envelope:

| Field | Meaning |
|---|---|
| `keyword`, `mode`, `geo`, `timeframe`, `property`, `category` | What was asked |
| `status` | `ok`, `no_data` (Google has too little search volume) or `error` (this item failed) |
| `error` | Why it failed, or `null` |
| `summary` | One sentence answering the question, `"No data"`, or `"Failed: …"` |

`compare` example:

```json
{
  "keyword": "claude", "mode": "compare", "geo": "ES", "timeframe": "past_12_months",
  "property": "web", "category": 0, "status": "ok", "error": null,
  "summary": "Search interest in \"claude\" in ES over the past 12 months is rising, up 64% from the first to the last quarter; it peaked at 100 on 2026-03-08 and averaged 37 on a 0-100 relative scale, ranking 2 of 2 compared keywords by average.",
  "points": [{ "date": "2025-11-16", "value": 3 }, "…", { "date": "2026-11-15", "value": 32, "partial": true }],
  "average": 37,
  "peak": { "date": "2026-03-08", "value": 100 },
  "trend": "rising",
  "change_pct_last_vs_first_quarter": 64
}
```

`trending_now` example (`{"mode": "trending_now", "geo": "US"}`), shortened to one trend:

```json
{
  "keyword": null, "mode": "trending_now", "geo": "US", "timeframe": "past_12_months",
  "property": "web", "category": 0, "status": "ok", "error": null,
  "summary": "Top trending searches in US right now: hacker (500+), milo ventimiglia (500+), sonny gray (2000+), albemarle county public schools (500+), anheuser busch (200+).",
  "trends": [
    {
      "query": "hacker",
      "approx_traffic": "500+",
      "started_at": "2026-11-18T20:40:00Z",
      "top_news_title": "British hacker who stole $11m through text message scheme jailed for six years in US",
      "news": [
        { "title": "British hacker who stole $11m through text message scheme jailed for six years in US", "url": "https://www.bbc.com/news/articles/cm87987w1qz5o", "source": "BBC" },
        { "title": "British hackers face prison for GTA 6 data breach and crypto thefts", "url": "https://techcrunch.com/2026/11/18/british-hackers-face-prison-for-gta-6-data-breach-and-crypto-thefts/", "source": "TechCrunch" }
      ]
    },
    "…"
  ]
}
```

`timeframe`, `property` and `category` don't apply to `trending_now`. They're echoed only to keep every item the same shape.

Mode-specific fields:

- `by_region` → `regions: [{ "geo_code": "SV", "name": "El Salvador", "value": 100 }, …]`, sorted from highest.
- `related` → `related_queries: { top: [{query, value, formatted}], rising: [...] }`. For rising entries, `formatted` is Google's label, e.g. `"+250%"` or `"Breakout"`.
- `trending_now` → `trends: [{ query, approx_traffic, started_at, top_news_title, news: [{title, url, source}] }]`, up to 3 news links per trend. The dataset's **Trending** view shows one row per trending search.

The key-value store record **`OUTPUT`** holds the whole run as one compact JSON: `{ request, notes, counts: {ok, no_data, error}, items }`. `notes` lists any adjustment made to your request. For example, `trending_now` with an empty `geo` gives `["Trending Now has no worldwide view; showing US."]`, and the same note starts each item's `summary`.

#### About the values

Google Trends values are **relative, not absolute search volume**. 100 is the peak popularity within the request: the chosen keywords, place and time range. 50 means half as popular as the peak, and 0 means too little data. In `compare` mode all keywords share one scale, so you can compare them. In `by_region` mode each keyword is scaled on its own. Dates are UTC. `past_day` and `past_7_days` return ISO datetimes, other ranges return dates. The newest point can be incomplete and is marked `"partial": true`, and it's left out of the trend math.

### Pricing

One flat price per query, in any mode:

| Event | Price |
|---|---|
| `query-result`: one query with 1–5 keywords, or one country's trending searches | **$0.0035** |

There's no start fee. You're charged only when the query returns data. If every keyword fails or Google has no data, the run is **free**. A 5-keyword comparison costs the same $0.0035 as a single keyword.

### Use with Claude / MCP

Add this Actor as a tool in any MCP client through the Apify MCP server:

```
https://mcp.apify.com/?tools=<username>/google-trends-api
```

In Claude Desktop / Claude Code, add it as a remote MCP server and authenticate with Apify. Then ask things like *"Is interest in Claude rising in Spain compared to ChatGPT?"* The agent calls the Actor and answers from `summary`.

From code, with the run-sync endpoint, which returns the dataset items directly:

```bash
curl -X POST "https://api.apify.com/v2/acts/<username>~google-trends-api/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"keywords":["claude","chatgpt"],"geo":"ES"}'
```

### FAQ

**Are these real search volumes?** No. Google publishes only relative interest (0–100), and every Google Trends tool returns the same thing. See [About the values](#about-the-values).

**How many keywords per run?** Up to 5. Google compares at most 5 terms on one scale. For more, run the Actor several times. Values are only comparable within one run.

**How reliable is it?** Each request has a 7-second limit. On a rate limit (HTTP 429), a stalled connection or a network error, the Actor switches at once to a fresh residential proxy session that is already warmed up. Server errors are retried with a short backoff. One keyword's failure doesn't affect the others. If every item fails, the run is marked failed instead of returning empty "success". A scheduled self-test checks every mode daily.

**Does it return related topics?** Not in v1. Google returns an empty related-topics list for automated requests, even for popular keywords, so v1 returns related **queries** only (top and rising).

**How fast is it?** In 10 compare runs on Apify, half finished within about 6.5 seconds end to end (start to results, including Actor start-up), and 95% within 8 seconds. When Google rate-limits a request, the Actor switches to a fresh proxy session immediately instead of waiting. Every query is capped at 16 seconds, so a run returns results or a clear error in about 20 seconds at most, well inside the roughly 30 seconds MCP clients wait.

**What are the limits?** Not supported yet: related topics, more than 5 keywords per run, CSV upload, charts, absolute search volume.

# Actor input Schema

## `mode` (type: `string`):

What to fetch: 'compare' = interest over time for 1-5 keywords on one shared 0-100 scale; 'by_region' = interest by country (or by region when geo is set) per keyword; 'related' = related search queries (top and rising) for exactly 1 keyword; 'trending_now' = current trending searches for the country in geo (no keywords; empty or worldwide geo shows the US).

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

1 to 5 search terms, e.g. \["chatgpt", "claude"]. Exactly 1 for 'related'. Ignored by 'trending_now'.

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

Where to measure. Worldwide: leave empty, or send "WORLD" or "worldwide". A country: ISO 3166-1 alpha-2 code like "US" or "ES". A region: "US-CA". 'trending_now' needs a country; if geo is empty or worldwide it shows the US and says so in the output. Default: worldwide.

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

Time window to analyze, ending now. past_day and past_7_days return hourly or finer points; past_5_years returns weekly points.

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

Google Trends category ID to narrow results (e.g. 71 = Food & Drink). 0 means all categories; keep 0 unless you know the ID.

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

Which Google search to measure: 'web' (Google Search), 'youtube', 'news', 'images' or 'shopping'.

## `useApifyProxy` (type: `boolean`):

Operator setting: route requests through Apify residential proxy. Leave on.

## `selfTest` (type: `boolean`):

Operator setting: ignore other fields, run a fixed health check across all modes, and fail the run if anything breaks.

## Actor input object example

```json
{
  "mode": "compare",
  "keywords": [
    "chatgpt",
    "claude"
  ],
  "geo": "",
  "timeframe": "past_12_months",
  "category": 0,
  "property": "web",
  "useApifyProxy": true,
  "selfTest": false
}
```

# Actor output Schema

## `output` (type: `string`):

No description

## `results` (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 = {
    "keywords": [
        "chatgpt",
        "claude"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("datafaro/google-trends-api").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": [
        "chatgpt",
        "claude",
    ] }

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

```

## MCP server setup

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

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/mDj7EyFrcw4XBJBQr/builds/LcKB74USb9hVi1Q3Z/openapi.json
