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

Interest over time, interest by region, top and rising related queries, and Trending Now from Google Trends. Automatic retries through rate limits, and you only pay for successful results.

- **URL**: https://apify.com/eaglizer\_it/google-trends-scraper.md
- **Developed by:** [Eaglizer IT](https://apify.com/eaglizer_it) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.50 / 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?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Google Trends Scraper

Get Google Trends data for any number of keywords: **interest over time, interest by region, top and rising related queries, and today's Trending Now searches**. Built to keep working when Google rate limits, and **you only pay for results you actually receive**.

### Why this one

- **Built for Google's rate limits.** Google Trends blocks bursts of requests (HTTP 429). This Actor primes every session the way a browser does, rotates to a fresh proxy session when Google pushes back, and retries with backoff. Rate limits are absorbed inside the run instead of failing it.
- **No charge for failures.** A term that still fails after every retry is listed in the `FAILED_TERMS` record and is never written to the dataset, so it is never billed.
- **Compare more than five terms.** Google only compares five keywords at a time. Turn on *Compare terms on one scale* and this Actor anchors every batch on your first term, so 20 or 50 keywords end up on one comparable 0 to 100 scale.
- **Answers, not just numbers.** Every term comes with its average interest, peak, and a `rising`, `falling`, or `flat` trend call with the percent change. It is ready for a spreadsheet, a dashboard, or an AI agent without extra math.
- **Trending Now included.** Daily trending searches for any country, with approximate traffic and the news stories behind them.

### What you can use it for

- **Keyword and content research:** find which topics are rising before you write about them.
- **Product and ecommerce research:** check whether demand is growing or fading before you stock or launch.
- **Local SEO and marketing:** see which states or metro areas search for a service most.
- **Market and investment research:** track interest in brands, tickers, and products over years.
- **AI agents:** one clean JSON object per keyword with a trend verdict included.

### Input

| Field | What it does |
|---|---|
| Search terms | Any number of keywords. One result per term. |
| Location | `US`, `GB`, `DE`, `US-CA`, and so on. Empty means worldwide. |
| Time range | Past hour up to 2004 to present, or a custom start and end date. |
| What to collect | Interest over time, related queries, interest by region. |
| Region detail | Countries, states, US metro areas, or cities. |
| Compare terms on one scale | Put every term on one shared scale, even beyond five terms. |
| Trending Now countries | Optional daily trending searches, for example `US`. |
| Category, search type | Filter by Trends category, or switch to YouTube, News, Images, or Shopping search. |

Example input:

```json
{
  "searchTerms": ["air conditioner repair", "heat pump", "furnace repair"],
  "geo": "US",
  "timeRange": "today 12-m",
  "includeRelatedQueries": true,
  "includeInterestByRegion": true,
  "regionResolution": "REGION"
}
```

### Output

One item per search term:

```json
{
  "type": "searchTerm",
  "searchTerm": "heat pump",
  "geo": "US",
  "timeRange": "today 12-m",
  "averageInterest": 61.4,
  "peakInterest": 100,
  "trendDirection": "rising",
  "changePercent": 18.2,
  "interestOverTime": [
    { "date": "2025-09-07T00:00:00Z", "formattedTime": "Sep 7 - 13, 2025", "value": 54, "isPartial": false }
  ],
  "interestByRegion": [
    { "geoCode": "US-ME", "geoName": "Maine", "value": 100 }
  ],
  "relatedQueries": {
    "top": [{ "query": "heat pump water heater", "value": 100, "formattedValue": "100" }],
    "rising": [{ "query": "heat pump rebate", "value": 350, "formattedValue": "+350%" }]
  },
  "trendsUrl": "https://trends.google.com/trends/explore?q=heat+pump&date=today+12-m&geo=US",
  "scrapedAt": "2026-09-13T21:00:00Z"
}
```

One item per trending search when Trending Now is used:

```json
{
  "type": "trendingNow",
  "geo": "US",
  "rank": 1,
  "title": "example trending search",
  "approxTraffic": "200K+",
  "approxTrafficMin": 200000,
  "publishedAt": "Sun, 13 Sep 2026 14:00:00 -0700",
  "news": [{ "title": "Headline", "url": "https://...", "source": "Publisher" }]
}
```

Export as JSON, CSV, Excel, or HTML, or pull results through the Apify API, webhooks, Make, Zapier, n8n, or Google Sheets.

### Pricing

Pay per result. One search term with every option you enable counts as one result. One trending search counts as one result. Failed terms are never charged. Set a maximum cost per run and the Actor stops cleanly when it is reached.

### Tips

- Values are relative, not search counts. 100 is the peak for that term, place, and time range.
- Very rare terms return zeros. Google needs a minimum search volume to report anything.
- For the fewest retries, keep one run to a few hundred terms and use the default proxy.

### FAQ

**Is scraping Google Trends legal?** This Actor collects publicly available, aggregated, anonymous data that anyone can view on trends.google.com. It does not collect personal data. You are responsible for how you use the results.

**Why do my numbers differ slightly from the website?** Google samples Trends data, so repeated requests can vary by a point or two. Longer time ranges are more stable.

**Something broke?** Open an issue on the Issues tab. Fixes are usually shipped within days.

# Actor input Schema

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

Keywords or phrases to look up. Any number is fine. Each term becomes one result.

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

Country or region code, for example US, GB, DE, or US-CA for California. Leave empty for worldwide.

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

Ignored when both a start date and an end date are set.

## `startDate` (type: `string`):

Optional. Use together with the end date for a custom range.

## `endDate` (type: `string`):

Optional. Use together with the start date.

## `includeInterestOverTime` (type: `boolean`):

The 0 to 100 timeline, plus average, peak, and a rising, falling, or flat trend call.

## `includeRelatedQueries` (type: `boolean`):

Top and rising related searches.

## `includeInterestByRegion` (type: `boolean`):

Where the term is most searched.

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

Only used with interest by region. Leave empty to let Google decide.

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

Off: each term gets its own 0 to 100 scale. On: all terms share one scale so you can rank them. Works beyond Google's five term limit by anchoring every batch on your first term.

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

Optional. Country codes such as US or GB. Returns today's trending searches with approximate traffic and news links. Each trending search is one result.

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

Google Trends category ID. 0 means all categories.

## `searchProperty` (type: `string`):

Which Google search to measure. Web search is what most people want.

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

Interface language for topic names, for example en-US or de.

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

Google rate limits Trends heavily. The default Apify Proxy works for most runs.

## Actor input object example

```json
{
  "searchTerms": [
    "air conditioner repair",
    "heat pump",
    "furnace repair"
  ],
  "geo": "US",
  "timeRange": "today 12-m",
  "includeInterestOverTime": true,
  "includeRelatedQueries": true,
  "includeInterestByRegion": false,
  "compareTerms": false,
  "category": 0,
  "searchProperty": "web",
  "language": "en-US",
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

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

No description

## `failedTerms` (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 = {
    "searchTerms": [
        "air conditioner repair"
    ],
    "geo": "US",
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("eaglizer_it/google-trends-scraper").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": ["air conditioner repair"],
    "geo": "US",
    "proxyConfiguration": { "useApifyProxy": True },
}

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

```

## MCP server setup

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

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/XBlOpOaMrakxFqrr0/builds/42Ovmg3AWuosTF7Oi/openapi.json