# Google Trends API - Reliable, 5+ Keywords, MCP-ready (`technofystore/google-trends-api`) Actor

Google Trends data as clean JSON/CSV: interest over time, interest by region, related queries & topics, and daily Trending Now. Compare more than 5 keywords on one common scale. Pay per result, failed lookups are never charged.

- **URL**: https://apify.com/technofystore/google-trends-api.md
- **Developed by:** [Joaquin O.](https://apify.com/technofystore) (community)
- **Categories:** SEO tools, AI, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.50 / 1,000 interest over time (per keyword)s

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 — reliable, 5+ keywords, MCP-ready

Get Google Trends data as clean JSON, CSV or Excel — **without pytrends breaking, without the
5-keyword limit, and without paying for failed lookups.**

### What you get

| Data | Description |
|------|-------------|
| **Interest over time** | Time series (0–100) per keyword for any location and time range |
| **Interest by region** | Country, region, city or US metro breakdown |
| **Related queries** | Top and rising queries, including "Breakout" terms |
| **Related topics** | Top and rising topics with Knowledge Graph IDs. *Availability depends on Google: as of Oct 2026 Google often returns no topics; those items come back as `NO_DATA` and are never charged.* |
| **Trending Now** | Today's trending searches per country, with the top news link |

### See it in action

All images below are real output of this Actor.

**12 keywords on one common scale** (anchor keyword: gemini, worldwide, past 12 months)

![12 keywords compared on one scale](https://api.apify.com/v2/key-value-stores/EPBQWqiK03xGT6pcB/records/1-twelve-keywords-one-scale?signature=OQDVFd0YHnh63CrTxJrA)

**Every row documents how it was scaled** — batch, scale factor and precision warning

![Output rows with normalization metadata](https://api.apify.com/v2/key-value-stores/EPBQWqiK03xGT6pcB/records/2-output-with-normalization?signature=1omZdJddAY98VNn5jSR9J)

**Interest by region** (Spain, autonomous communities)

![Interest by region](https://api.apify.com/v2/key-value-stores/EPBQWqiK03xGT6pcB/records/4-interest-by-region?signature=o56xPyAVGz5U2Jf8cGCC)

**Trending Now** per country

![Trending Now](https://api.apify.com/v2/key-value-stores/EPBQWqiK03xGT6pcB/records/5-trending-now?signature=16CKqoM7ufb5bqEAznsz6)

**Reliability** — 10 runs × 20 keywords on Apify

![Load test results](https://api.apify.com/v2/key-value-stores/EPBQWqiK03xGT6pcB/records/3-reliability?signature=6K0TQw0SE8ZSdr10yQCt)

### Why this Actor

- **Compare more than 5 keywords.** Google Trends only compares 5 terms at a time and rescales every
  request. This Actor puts an *anchor keyword* in every batch and rescales all batches to **one common
  scale**, so you can rank 50 keywords against each other. Every result includes the scale factor used.
- **Built for reliability.** Automatic retries with fresh residential sessions when Google rate-limits.
  A run summary (`RUN_SUMMARY`) shows requests, retries and success rate.
- **Fair pricing.** You pay per result. Keywords with no data and failed requests are returned as
  error rows and are **never charged**.
- **AI-agent ready.** Works as a tool through the Apify MCP server, with a clean, predictable output.

### Quick start

1. Add your keywords.
2. Pick data types, location (e.g. `US`, `ES`, `US-CA`) and time range.
3. Click **Start**. Download results as JSON, CSV or Excel, or call the Actor via API.

#### Example input

```json
{
  "keywords": ["python", "javascript", "rust"],
  "dataTypes": ["interestOverTime", "relatedQueries"],
  "geo": "ES",
  "timeRange": "today 12-m"
}
```

#### Example output (one row)

```json
{
  "type": "interestOverTime",
  "keyword": "python",
  "geo": "ES",
  "timeRange": "today 12-m",
  "data": {
    "points": [
      { "date": "2025-10-12T00:00:00Z", "value": 43, "isPartial": false },
      { "date": "2025-10-19T00:00:00Z", "value": 45, "isPartial": false }
    ]
  },
  "normalization": { "method": "none" },
  "error": null
}
```

### Comparing more than 5 keywords

Add up to 50 keywords. Choose an **anchor keyword** with similar popularity to the rest (by default
the first keyword). Each result includes:

| Field | Meaning |
|-------|---------|
| `normalization.anchor` | Keyword used to link batches |
| `normalization.scaleFactor` | Multiplier applied to that batch |
| `normalization.precisionWarning` | `true` when the anchor or keyword values were too small for a precise rescale — pick a different anchor |

The highest value across all keywords and dates is 100.

### Pricing

| Event | Price |
|-------|-------|
| Interest over time, per keyword | $0.005 |
| Interest by region, per keyword | $0.005 |
| Related queries, per keyword | $0.004 |
| Related topics, per keyword | $0.004 |
| Trending Now, per item | $0.0005 |

Example: 200 keywords × interest over time = **$1.00**. Set a maximum spend per run in the Apify
Console; the Actor stops cleanly when it is reached and keeps everything collected so far.

### Use cases

- SEO & content planning: seasonality, rising topics and keyword prioritization by country
- E-commerce & product: detect emerging demand and regional differences
- Research & journalism: comparable historical series with a documented method
- AI agents: give your agent a live view of what people search for right now

### Input parameters

| Parameter | Description |
|-----------|-------------|
| `keywords` | 1–50 search terms |
| `dataTypes` | `interestOverTime`, `interestByRegion`, `relatedQueries`, `relatedTopics` |
| `geo` | ISO code (`US`, `ES`, `US-CA`); empty = worldwide |
| `timeRange` | Past hour → 2004-present, or custom dates |
| `category` / `property` | Google Trends category ID; web, news, images, YouTube or Shopping |
| `anchorKeyword` | Anchor for 5+ keywords |
| `regionResolution` | Country, region, city or US metro |
| `trendingNowGeos` | Country codes for Trending Now |

### Notes and limitations

- Google Trends values are **relative** (0–100), not absolute search volumes.
- Google samples its data: the same query can vary by a few points between requests.
- The last point of a series may be partial (`isPartial: true`).
- This Actor reads publicly available Google Trends pages. It is not affiliated with or endorsed by Google.

### Support

Open an issue in the **Issues** tab — response within 24–48 h on weekdays. Feature requests welcome.

# Actor input Schema

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

Search terms to analyze (1-50). With more than 5 keywords, all values are rescaled to one common scale using an anchor keyword.

## `dataTypes` (type: `array`):

Which Google Trends datasets to return for each keyword. Each data type is billed separately per keyword. Related topics: Google currently often returns no data for it; empty results are never charged.

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

ISO country or subregion code, e.g. ES, US, US-CA, MX. Leave empty for Worldwide.

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

Preset time range. Choose 'Custom' and fill the dates below for a custom range.

## `customStartDate` (type: `string`):

Only used when Time range = Custom. Earliest allowed: 2004-01-01.

## `customEndDate` (type: `string`):

Only used when Time range = Custom.

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

Google Trends category ID. 0 = All categories.

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

Which Google search property to analyze.

## `anchorKeyword` (type: `string`):

Keyword included in every batch to rescale results to one common scale. Pick a term of similar popularity to the others. Empty = first keyword. If it is not in your list it is added internally and not returned or charged.

## `regionResolution` (type: `string`):

Granularity for Interest by region.

## `includeLowSearchVolumeRegions` (type: `boolean`):

Include regions where Google reports low search volume.

## `trendingNowGeos` (type: `array`):

Optional. Two-letter country codes (e.g. US, ES, MX). Adds today's trending searches for each country. Billed per trending item.

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

Interface language for labels, e.g. en-US, es-ES.

## `timezoneOffsetMinutes` (type: `integer`):

Google 'tz' parameter. 0 = UTC. Google uses inverted sign: UTC+2 = -120.

## `failRunOnErrors` (type: `boolean`):

Marks the run as FAILED when at least one result is a real error (RATE_LIMITED, PARSE_ERROR, REQUEST_REJECTED, ANCHOR_ZERO, INVALID_INPUT). NO_DATA rows (insufficient search volume) are expected and do not fail the run. Results are still saved and error items are never charged. Useful for monitoring/alerts.

## `maxRetries` (type: `integer`):

Retries with a fresh proxy session when Google rate-limits.

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

Residential proxies give the best success rate with Google.

## Actor input object example

```json
{
  "keywords": [
    "python",
    "javascript",
    "rust"
  ],
  "dataTypes": [
    "interestOverTime"
  ],
  "geo": "",
  "timeRange": "today 12-m",
  "category": 0,
  "property": "",
  "anchorKeyword": "",
  "regionResolution": "AUTO",
  "includeLowSearchVolumeRegions": false,
  "trendingNowGeos": [],
  "language": "en-US",
  "timezoneOffsetMinutes": 0,
  "failRunOnErrors": false,
  "maxRetries": 6,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# Actor output Schema

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

No description

## `interestOverTime` (type: `string`):

No description

## `trendingNow` (type: `string`):

No description

## `runSummary` (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": [
        "python",
        "javascript",
        "rust"
    ],
    "dataTypes": [
        "interestOverTime"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("technofystore/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": [
        "python",
        "javascript",
        "rust",
    ],
    "dataTypes": ["interestOverTime"],
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("technofystore/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": [
    "python",
    "javascript",
    "rust"
  ],
  "dataTypes": [
    "interestOverTime"
  ],
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}' |
apify call technofystore/google-trends-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,technofystore/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/g996smv4ZBgaaNXwP/builds/Jz0Ah6ewpPn3OCPbc/openapi.json