# Google Trends API & Scraper (`whosandrw/google-trends-api`) Actor

Google Trends data as an API: interest over time, by region, related queries and trending searches. Compare unlimited keywords on one scale, many countries per run, CSV export. Residential proxy retries, no failed runs.

- **URL**: https://apify.com/whosandrw/google-trends-api.md
- **Developed by:** [Felipe Moncada](https://apify.com/whosandrw) (community)
- **Categories:** SEO tools, Marketing
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$3.00 / 1,000 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 — Download Google Trends Data (CSV, Excel, JSON)

Get **Google Trends data** without code or rate-limit headaches: **interest over time**, **interest by region**, **related queries (top & rising)** and today's **trending searches** — for any keywords, any country, any time range. Export to **CSV / Excel**, JSON, or call it as a **Google Trends API** from Python, JavaScript, Make, Zapier or Google Sheets.

> 🇪🇸 **¿Hablas español?** [Ver la guía en español ↓](#-google-trends-en-español)

**Why this Actor**

- ✅ **Compare unlimited keywords on one scale.** Google Trends only compares 5 terms at a time, and separate comparisons can't be combined. This Actor puts 10, 50 or 200 keywords on **one comparable 0–100 scale** using an anchor term — something Google Trends itself can't do.
- ✅ **Runs don't fail on rate limits.** Google blocks automated traffic with HTTP 429. Every block is retried from a **new residential IP with fresh cookies**, so your run finishes with data.
- ✅ **Many countries in one run.** Same keywords for US, UK, MX, CO, ES… at once.
- ✅ **Ready-to-use table.** Every run also produces a flat **CSV table** (one row per term × date / region / query) for Excel, Google Sheets or BI tools — at no extra cost.
- ✅ **Paste Google Trends URLs** straight from your browser.
- ✅ **Fair pricing:** pay only for results that contain data. Empty blocks and errors are never charged.

### What data can I get?

| Data | What you get |
|---|---|
| **Interest over time** | Search interest (0–100) per day/week/month for one term or a comparison. `isPartial` marks the current, incomplete period. |
| **Comparable interest for >5 keywords** | The same, for any number of keywords on one shared scale (`interestOverTimeComparable`). |
| **Interest by region** | Interest per country, state/region, city or US metro area (DMA). |
| **Related queries** | Top and rising related searches for each keyword, including **Breakout** queries. |
| **Trending Now** | Today's trending searches for any country, with approximate traffic and related news. |

### Use cases

- **Keyword research & SEO:** find which keywords are growing, seasonal peaks, and rising related queries.
- **Market research:** compare brands, products or competitors across countries.
- **E-commerce & content planning:** time campaigns and content to seasonal demand.
- **Data science & forecasting:** feed Google Trends time series into models and dashboards.
- **Newsrooms & social media:** monitor what is trending right now in each country.

### How to use it (no code)

1. Click **Try for free**.
2. Type your keywords, pick the country (or several), the time range and the data you want.
3. Click **Start**. When the run finishes, open **Output** and download the **Table (CSV)** or the full results as Excel / JSON.
4. Optional: **Schedule** the run (e.g. every Monday) to track trends automatically.

#### Compare more than 5 keywords on one scale

Enable **Compare terms** and add as many keywords as you want:

```json
{
  "searchTerms": ["nike", "adidas", "puma", "new balance", "asics", "reebok", "under armour", "skechers"],
  "compareTerms": true,
  "geos": ["US", "GB", "MX"],
  "timeRange": "today 5-y"
}
```

Keywords are queried in batches of 4 plus an **anchor term** (the first keyword, or the one you choose in *Anchor term*). Each batch is rescaled so the anchor matches across batches, then everything is normalized to 0–100. Tip: choose an anchor with medium, steady popularity. Terms in a batch where the anchor is very small are flagged with `lowPrecision: true`.

#### Trending searches today

```json
{ "mode": "trendingNow", "trendingGeos": ["US", "GB", "IN", "BR", "MX"] }
```

#### From Google Trends URLs

Paste URLs like `https://trends.google.com/trends/explore?q=bitcoin,ethereum&geo=US&date=today%2012-m` in **Google Trends URLs** — terms, country, dates, category and property are read from the URL.

### Use it as a Google Trends API

Python:

```python
from apify_client import ApifyClient

client = ApifyClient("<YOUR_APIFY_TOKEN>")
run = client.actor("whosandrw/google-trends-api").call(run_input={
    "searchTerms": ["bitcoin", "ethereum"], "compareTerms": True, "geo": "US", "timeRange": "today 12-m",
})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item["type"], item.get("term") or item.get("searchTerms"))
```

JavaScript:

```js
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: '<YOUR_APIFY_TOKEN>' });
const run = await client.actor('whosandrw/google-trends-api').call({ searchTerms: ['bitcoin'], geo: 'US' });
const { items } = await client.dataset(run.defaultDatasetId).listItems();
```

It also works with **Make, Zapier, n8n, Google Sheets** and AI agents through Apify's integrations.

### Output example

```json
{
  "type": "interestOverTime",
  "searchTerms": ["bitcoin", "ethereum"],
  "geo": "US",
  "timeRange": "today 12-m",
  "points": 52,
  "data": [
    { "date": "2025-09-28T00:00:00Z", "formattedTime": "Sep 28 – Oct 4, 2025", "isPartial": false,
      "values": { "bitcoin": 45, "ethereum": 9 } }
  ]
}
```

```json
{
  "type": "relatedQueries",
  "term": "bitcoin",
  "top":    [{ "query": "bitcoin price", "value": 100, "formattedValue": "100", "link": "https://trends.google.com/trends/explore?q=bitcoin+price..." }],
  "rising": [{ "query": "british man recovers lost bitcoin", "value": 10850, "formattedValue": "Breakout", "link": "..." }]
}
```

The **Table (CSV)** output has one row per data point with columns `type, geo, timeRange, term, date, value, isPartial, regionCode, regionName, list, query, formattedValue, rank, title, approxTraffic, pubDate`.

### Pricing

**$3 per 1,000 results.** One result = one data block: interest over time for a term or comparison, interest by region, related queries for one keyword, one comparable series, or one trending search. Examples:

- 1 keyword with all data types ≈ 3 results ≈ **$0.009**
- 50 keywords compared on one scale (interest over time) ≈ 50 results ≈ **$0.15**

Set a maximum cost per run in the Apify Console; the Actor stops cleanly when it is reached.

### FAQ

**Why are values between 0 and 100?** Google Trends normalizes interest to the highest point within the selected terms, region and time range. It does not publish absolute search volumes.

**How is this different from pytrends?** pytrends is a Python library you run yourself; it gets blocked by Google's rate limits (HTTP 429) on anything but small jobs. This Actor runs in the cloud with residential proxy rotation, retries, scheduling and exports, and adds unlimited-keyword comparison.

**Can I get related topics?** Google currently returns empty related-topic lists for automated requests, so they are not included (and never charged).

**Is it legal?** The Actor collects publicly available, aggregated Google Trends data and no personal data. You are responsible for complying with Google's terms and your local regulations when using the data.

**Something not working?** Open an issue in the *Issues* tab — it is usually answered within a day.

***

### 🇪🇸 Google Trends en español

**Datos de Google Trends sin programar y sin bloqueos**: interés a lo largo del tiempo, interés por región (país, departamento/estado, ciudad), búsquedas relacionadas (principales y en aumento) y lo más buscado hoy en Google en cualquier país. Descárgalo en **Excel / CSV** o úsalo como **API de Google Trends** desde Python, JavaScript, Make, Zapier o Google Sheets.

**¿Qué es Google Trends?** Es la herramienta de Google que muestra qué tan buscado es un tema en el tiempo y por lugar (en una escala de 0 a 100). Es clave para **investigación de palabras clave (SEO)**, estudios de mercado, e-commerce y contenido.

#### Por qué este Actor

- ✅ **Compara palabras clave ilimitadas en una misma escala.** Google Trends solo compara 5 términos a la vez y las comparaciones separadas no se pueden cruzar. Aquí puedes comparar 10, 50 o 200 palabras en una escala 0–100 (con un término ancla), algo que Google Trends no permite.
- ✅ **No falla por bloqueos.** Cuando Google limita las consultas (error 429), el Actor reintenta desde una nueva IP residencial con cookies nuevas.
- ✅ **Varios países en una sola corrida:** México, Colombia, Argentina, España, Chile, Perú… a la vez.
- ✅ **Tabla lista para Excel** (CSV) con cada dato en una fila, sin costo extra.
- ✅ **Pega URLs de Google Trends** directamente desde tu navegador.
- ✅ **Pagas solo por resultados con datos.** Los bloques vacíos y los errores no se cobran.

#### Cómo usarlo (sin código)

1. Haz clic en **Try for free**.
2. Escribe tus palabras clave, elige el país (o varios) y el período.
3. Para fechas y etiquetas en español, escribe `es-419` (Latinoamérica) o `es` (España) en **Language**.
4. Haz clic en **Start** y, al terminar, abre **Output** y descarga la **Table (CSV)** para Excel o Google Sheets.
5. Opcional: prográmalo con **Schedule** (por ejemplo, cada lunes) para seguir tendencias automáticamente.

Ejemplo: comparar marcas en varios países de Latinoamérica.

```json
{
  "searchTerms": ["mercado libre", "amazon", "temu", "shein", "falabella", "walmart"],
  "compareTerms": true,
  "geos": ["MX", "CO", "AR", "CL"],
  "timeRange": "today 12-m",
  "language": "es-419"
}
```

Lo más buscado hoy en Google:

```json
{ "mode": "trendingNow", "trendingGeos": ["MX", "CO", "AR", "ES", "CL", "PE"] }
```

#### Precio

**US$3 por cada 1.000 resultados.** Un resultado es un bloque de datos (por ejemplo, el interés en el tiempo de una palabra, o una búsqueda en tendencia). Una palabra clave con todos los datos cuesta cerca de **US$0,009**. Puedes fijar un gasto máximo por corrida en la consola de Apify.

#### Preguntas frecuentes

**¿Por qué los valores van de 0 a 100?** Google Trends normaliza el interés al punto más alto dentro de los términos, región y período elegidos. No publica volúmenes absolutos de búsqueda.

**¿En qué se diferencia de pytrends?** pytrends es una librería que corres en tu computador y Google la bloquea (error 429) en cuanto haces varias consultas. Este Actor corre en la nube con rotación de proxies residenciales, reintentos, programación y exportación, y además compara más de 5 palabras en una escala.

**¿Tienes soporte en español?** Sí. Abre un ticket en la pestaña **Issues** en español o en inglés.

# Actor input Schema

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

Explore search terms, or get today's Trending Now searches for one or more countries.

## `searchTerms` (type: `array`):

Keywords to look up in Google Trends. With 'Compare terms' enabled you can add any number of terms (e.g. 50 keywords) and get them on one comparable scale.

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

Paste Google Trends explore URLs (copied from your browser). Terms, country, time range, category and property are read from each URL.

## `compareTerms` (type: `boolean`):

Compare terms on the same 0-100 scale. Up to 5 terms work like the Google Trends compare view. With MORE than 5 terms, the Actor uses an anchor term to put ALL of them on one comparable scale (Google Trends itself cannot do this).

## `anchorTerm` (type: `string`):

Term shared by every batch to rescale them to one scale. Defaults to the first search term. Pick a term with medium, steady popularity for best precision.

## `outputs` (type: `array`):

Each selected block is one result (one dataset item). Empty blocks are never charged.

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

ISO code like US, CO, MX, ES, or a subregion like US-CA. Leave empty for worldwide.

## `geos` (type: `array`):

Run the same terms for several countries in one run, e.g. US, CO, MX, ES. Overrides the single country field. Use an empty line for worldwide.

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

Period to analyze. Ignored when a custom time range is set.

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

Overrides Time range. Format: YYYY-MM-DD YYYY-MM-DD, e.g. 2024-01-01 2024-12-31.

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

Granularity for Interest by region. Leave empty to use Google's default (countries when worldwide, subregions for a country).

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

Google Trends category ID (0 = all categories).

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

Which Google search to use as the source (web, images, news, shopping or YouTube).

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

Used only in Trending Now mode. ISO country codes.

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

Language for dates and labels, e.g. en-US (English), es-419 (Spanish - Latin America), es (Spanish - Spain), pt-BR (Portuguese). / Idioma de fechas y etiquetas: usa es-419 para español latinoamericano.

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

Each retry uses a fresh proxy session and cookies.

## `requestDelaySecs` (type: `number`):

Pause between requests to Google. 1-2 seconds keeps rate limits rare.

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

Residential proxies are recommended: each retry gets a new IP, which is what makes rate limits recoverable. Without a proxy, Google blocks a single IP after roughly 150-200 requests.

## Actor input object example

```json
{
  "mode": "explore",
  "searchTerms": [
    "bitcoin",
    "ethereum"
  ],
  "compareTerms": false,
  "outputs": [
    "interestOverTime",
    "interestByRegion",
    "relatedQueries"
  ],
  "geo": "",
  "timeRange": "today 12-m",
  "category": 0,
  "property": "",
  "trendingGeos": [
    "US"
  ],
  "language": "en-US",
  "maxRetries": 6,
  "requestDelaySecs": 1,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# Actor output Schema

## `table` (type: `string`):

Every data point as one row (term, date, region, value...). Ready for Excel, Google Sheets or BI tools. Included at no extra cost.

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

Full data for every result, including the time series, regions and related queries.

## `overview` (type: `string`):

Compact table: result type, terms, region, time range and number of data points.

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

Trending searches (Trending Now mode): rank, title, approximate traffic and publication date.

# 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 = {
    "searchTerms": [
        "bitcoin",
        "ethereum"
    ],
    "trendingGeos": [
        "US"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("whosandrw/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 = {
    "searchTerms": [
        "bitcoin",
        "ethereum",
    ],
    "trendingGeos": ["US"],
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("whosandrw/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 '{
  "searchTerms": [
    "bitcoin",
    "ethereum"
  ],
  "trendingGeos": [
    "US"
  ],
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}' |
apify call whosandrw/google-trends-api --silent --output-dataset

```

## MCP server setup

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