# Google Trends Scraper (`atalaia/google-trends`) Actor

Scrape Google Trends: interest over time, interest by region, related queries and related topics for up to 5 compared keywords, any country, time range, category and property (web, YouTube, News, Images, Shopping), plus today's trending searches per country.

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

## Pricing

$2.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

### What does Google Trends Scraper do?

**Google Trends Scraper** extracts data from [Google Trends](https://trends.google.com/trends/explore): **interest over time**, **interest by region**, **related queries** and **related topics** for any keyword, compared with up to 4 others, in any country or region, for any time range, category and search property (web, YouTube, News, Images, Google Shopping). It can also return **today's trending searches** for a country, with their approximate search volume and the news articles behind them.

Enter your keywords, pick a location and time range, click **Start**, and download the data as JSON, CSV, Excel or HTML, or fetch it through the Apify API. Because it runs on the Apify platform, you can schedule it (for example, daily trending searches every morning), call it from your own code and connect it to Make, Zapier or Google Sheets.

### Why use Google Trends Scraper?

- **Market and product research.** Compare the demand for brands, products or categories across countries and over years.
- **SEO and content planning.** Find rising queries (including "Breakout" ones) before they get competitive.
- **Seasonality.** Get the weekly or daily curve of any keyword to plan campaigns and inventory.
- **News and trend monitoring.** Track what a country is searching for today, with the related headlines.

No browser is involved: the Actor calls the same JSON endpoints the Google Trends website uses, which keeps runs fast and inexpensive. Requests are spread across proxy sessions and retried with exponential backoff when Google rate-limits (HTTP 429), switching from datacenter to residential IPs when needed, so a temporary block doesn't fail your run.

### How to scrape Google Trends

1. Open the Actor and go to the **Input** tab.
2. Add up to 5 **keywords** to compare, for example `coffee`, `tea`.
3. Optionally set the **location** (`BR`, `US`, `US-CA`...; empty = worldwide), **time range**, **category** and **search property**.
4. Choose the **sections** you want.
5. Optionally enter a country in **Daily trending searches**.
6. Click **Start**. When the run finishes, open the **Output** tab or export the dataset.

### Input

All fields are optional, but you need at least one keyword or a daily trending country.

| Field | Type | Default | Description |
|---|---|---|---|
| `keywords` | string\[] | none | Keywords to analyze. Up to 5 are compared together (values are relative to each other, like in the Google Trends UI). More than 5 are split into consecutive groups of 5. |
| `geo` | string | `""` (worldwide) | ISO country or region code: `BR`, `US`, `US-CA`, `DE`, `IN`... |
| `timeRange` | string | `today 12-m` | `now 1-H`, `now 4-H`, `now 1-d`, `now 7-d`, `today 1-m`, `today 3-m`, `today 12-m`, `today 5-y`, `all`, or a custom range `YYYY-MM-DD YYYY-MM-DD`. |
| `category` | integer | 0 | Google Trends category ID (0 = all categories). |
| `property` | enum | `""` (web) | `youtube`, `news`, `images` or `froogle` (Google Shopping). |
| `include` | string\[] | `["interestOverTime"]` | Any of `interestOverTime`, `interestByRegion`, `relatedQueries`, `relatedTopics`. |
| `dailyTrending` | string | none | 2-letter country code. Returns today's trending searches in that country. |
| `proxyConfiguration` | object | Apify Proxy (automatic) | Keep the default: the Actor starts on datacenter IPs and moves to residential IPs automatically when Google rate-limits. If you pick specific proxy groups, only those are used. |

Example input:

```json
{
    "keywords": ["coffee", "tea"],
    "geo": "BR",
    "timeRange": "today 12-m",
    "include": ["interestOverTime", "interestByRegion", "relatedQueries"],
    "dailyTrending": "BR"
}
```

### Output

One item **per keyword per section**, plus one item per daily trending search. Values are Google's 0–100 relative scale.

Interest over time (series shortened; `date` is UTC):

```json
{
    "keyword": "coffee",
    "comparedWith": ["tea"],
    "geo": "BR",
    "timeRange": "today 12-m",
    "category": 0,
    "property": "web",
    "section": "interestOverTime",
    "data": [
        { "date": "2025-09-28T00:00:00.000Z", "formattedTime": "Sep 28 – Oct 4, 2025", "value": 71, "hasData": true, "isPartial": false },
        { "date": "2026-09-27T00:00:00.000Z", "formattedTime": "Sep 27 – Oct 3, 2026", "value": 64, "hasData": true, "isPartial": true }
    ],
    "noData": false,
    "scrapedAt": "2026-09-29T14:45:42.688Z"
}
```

Interest by region: `data` is `[{ "geoCode": "BR-SP", "geoName": "State of São Paulo", "value": 100, "hasData": true }, ...]` (countries for worldwide, states/regions for a country, metro areas for a US state). The scale is per keyword, as on the keyword's own Google Trends page.

Related queries: `data` is `{ "top": [{ "query": "coffee shop", "value": 100, "formattedValue": "100", "link": "https://trends.google.com/trends/explore?q=..." }], "rising": [{ "query": "...", "value": 9000, "formattedValue": "Breakout", "link": "..." }] }`.

Related topics: same shape, with `topicId`, `title` and `type` instead of `query`.

Daily trending search:

```json
{
    "section": "dailyTrending",
    "geo": "BR",
    "rank": 1,
    "title": "lesoto x marrocos",
    "approxTraffic": "10000+",
    "approxTrafficMin": 10000,
    "pubDate": "2026-09-29T12:30:00.000Z",
    "picture": "https://encrypted-tbn3.gstatic.com/images?q=...",
    "pictureSource": "Lance!",
    "newsItems": [{ "title": "...", "snippet": null, "url": "https://...", "source": "Lance!", "picture": "https://..." }],
    "scrapedAt": "2026-09-29T14:45:50.828Z"
}
```

When Google has not enough data for a keyword, the item has `"noData": true`, an empty `data` and a `note`. **These items are free.** If a request still fails after all retries, the dataset gets an item like `{ "query": "coffee, tea", "error": "..." }`, also free. The run fails only if every query failed.

### Pricing

This Actor uses **pay-per-event** pricing: **$0.002 per result** (one keyword section, or one daily trending search). There is no start fee, and items without data or with errors are not charged. Example: 5 keywords × 3 sections = 15 results = $0.03.

You can cap spending with the run's **maximum cost** setting: the Actor stops cleanly when the limit is reached.

### Limits and notes

- Values are **relative** (0–100), exactly as Google Trends shows them, not absolute search volumes. Keywords compared in one group share the same scale for interest over time.
- **Related topics:** Google Trends currently answers "not enough data" for related topics on most searches, including on its own website. The Actor requests them and returns them when Google does; otherwise you get a free `noData` item. Google doesn't provide related topics for compared keywords, so the Actor asks for each keyword alone (and stops asking for the rest of the run after 3 empty answers in a row).
- Daily trending searches come from Google's public trending feed: usually the 10–20 most recent trends of the country, not a full-day history.
- Labels and region names are in English.
- Google may change its internal endpoints at any time; the Actor is monitored and updated when that happens.

### FAQ

**Is it legal to scrape Google Trends?** The Actor only collects aggregated, public statistics that Google shows to any visitor. It doesn't collect personal data. Check the rules that apply to your use case.

**Why do my numbers differ slightly from the website?** Google Trends samples its data, so values can shift by a few points between requests or days.

**Can I get more than 5 keywords on the same scale?** Put one common reference keyword in every group of 5 and rescale the groups against it.

# Actor input Schema

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

Search terms to analyze. Up to 5 keywords are compared together in one request, exactly like the Google Trends UI (values are relative to each other). More than 5 are split into consecutive groups of 5. Leave empty if you only want daily trending searches.

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

ISO country or region code, e.g. BR, US, US-CA, DE. Empty = worldwide.

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

One of: now 1-H, now 4-H, now 1-d, now 7-d, today 1-m, today 3-m, today 12-m, today 5-y, all, or a custom range 'YYYY-MM-DD YYYY-MM-DD'.

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

Google Trends category ID (0 = all categories; e.g. 71 = Food & Drink, 7 = Finance).

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

Which Google search to analyze.

## `include` (type: `array`):

Which sections to return for each keyword. Each section is one dataset item per keyword.

## `dailyTrending` (type: `string`):

Optional ISO country code (e.g. BR, US). Returns today's trending searches in that country, one item per trend, with approximate traffic and related news articles.

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

Apify Proxy is used by default. Datacenter proxies work well for Google Trends.

## Actor input object example

```json
{
  "keywords": [
    "coffee",
    "tea"
  ],
  "geo": "",
  "timeRange": "today 12-m",
  "category": 0,
  "property": "",
  "include": [
    "interestOverTime"
  ],
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

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

No description

## `dailyTrending` (type: `string`):

No description

## `runStats` (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": [
        "coffee",
        "tea"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("atalaia/google-trends").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": [
        "coffee",
        "tea",
    ],
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("atalaia/google-trends").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": [
    "coffee",
    "tea"
  ],
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call atalaia/google-trends --silent --output-dataset

```

## MCP server setup

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

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/cEQsk9pMfOMgbTC0W/builds/BEl1dbwb491HMx28F/openapi.json