# Google Trends Scraper & API — Bulk Keywords, Trending Now (`trendpilot_data/google-trends-scraper`) Actor

Bulk Google Trends + full Trending Now (hundreds of trends a day with search volume, % increase, categories, 4h–7d). Interest over time with stats, by state/city/metro, rising queries, comparisons, pasted Trends URLs. Empty results are free.

- **URL**: https://apify.com/trendpilot_data/google-trends-scraper.md
- **Developed by:** [TrendPilot Data](https://apify.com/trendpilot_data) (community)
- **Categories:** SEO tools, Marketing, News
- **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 keyword reports

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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 Scraper & API — Bulk Keywords, Trending Now

Get Google Trends data for hundreds of keywords in one run — **interest over time with ready-made trend stats, interest by country / state / city / US metro, top & rising related queries, keyword comparisons, and live Trending Now searches** — as clean JSON, CSV or Excel.

**You only pay for results with data.** Keywords that are too rare for Google Trends to have data are returned free of charge.

### What you get

| Feature | Details |
|---|---|
| 📈 Interest over time | Full time series (hourly → monthly depending on range) **plus summary stats**: average, peak + date, latest value, % change, and a `rising` / `falling` / `flat` direction. No spreadsheet work needed. |
| 🗺️ Interest by region | Countries, states/provinces, cities, or US metro areas (DMA). |
| 🔎 Related queries | Top and rising related searches, with `Breakout` flags and a direct Google Trends link for each. |
| ⚖️ Compare keywords | Up to 5 terms on the same scale, exactly like typing them into Google Trends. Larger lists are split automatically. |
| 🔥 Trending Now | Every trend Google lists for a country or US state over the **past 4 h, 24 h, 48 h or 7 days** (hundreds per day, not just the top 20): search volume, % increase, start/end time, active flag, category, the related "trend breakdown" searches, and news articles for the newest ~10 trends (the ones Google publishes in its news feed). Filter by category, keep active trends only, sort by volume or recency. |
| 🔗 Paste Google Trends links | Put Explore or Trending Now URLs in `startUrls` — each keeps its own terms, location, dates and filters. |
| 🎛️ All filters | Any location, preset or custom date range, category, and search type (Web, Images, News, Shopping, YouTube). |

### Built for reliability

Google Trends aggressively rate-limits automated traffic. This scraper:

- gives every worker its **own proxy session and cookies**, and on a rate limit **switches to a fresh IP** and retries automatically;
- uses residential proxies by default (Google blocks most datacenter IPs);
- keeps going when one keyword fails, and writes a `SUMMARY` record (succeeded / failed / reasons) to the run's key-value store so nothing fails silently.

### Switching from another Google Trends scraper?

Inputs written for other popular Google Trends scrapers run as-is: `searchTerms`, `isMultiple`, `timeRange`, `customTimeRange`, `startUrls`, `geo`, `category` and `maxRequestRetries` are understood. Fields this scraper doesn't use are ignored. The output format is this scraper's own (see below).

### Use cases

- **SEO & content**: find rising queries and seasonal peaks before you plan content.
- **E-commerce & product research**: spot products that are trending up, and where.
- **Market research & investing**: track brand or category interest over time and across regions.
- **Data pipelines & AI agents**: schedule runs and feed fresh trend data into dashboards, spreadsheets or LLM workflows.

### Input example

```json
{
    "keywords": ["matcha", "cold brew", "chai latte"],
    "geo": "US",
    "timeframe": "today 12-m",
    "includeTimeline": true,
    "includeRegions": true,
    "includeRelatedQueries": true,
    "trendingGeos": ["US", "GB"],
    "trendingHours": "24",
    "trendingCategories": ["Technology", "Business and Finance"],
    "trendingMaxItems": 50
}
```

- `geo`: country/region code (`US`, `GB`, `US-CA`) or empty for Worldwide.
- `timeframe`: `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 set `customTimeframe` to `"2025-01-01 2025-12-31"`.
- `compareKeywords`: `true` to put keywords on one shared scale (groups of up to 5).
- `regionResolution`: `COUNTRY`, `REGION`, `CITY` or `DMA` (auto by default).
- `startUrls`: Google Trends links, e.g. `https://trends.google.com/trends/explore?q=matcha,coffee&geo=US&date=today%205-y` or `https://trends.google.com/trending?geo=GB&hours=168&category=17`.
- `trendingHours`: `4`, `24`, `48` or `168`. `trendingCategories`: names as on Google (Sports, Technology, …). `trendingActiveOnly`, `trendingSort` (`relevance`, `volume`, `recency`, `title`), `trendingMaxItems` per location (default 100, 0 = all), `trendingIncludeNews`.

### Output example

One item per keyword (`type: "keywordReport"`):

```json
{
    "type": "keywordReport",
    "keyword": "matcha",
    "comparedWith": [],
    "geo": "US",
    "timeframe": "today 12-m",
    "stats": {
        "average": 75.4,
        "peakValue": 100,
        "peakDate": "2026-04-12T00:00:00.000Z",
        "latestValue": 56,
        "latestDate": "2026-11-01T00:00:00.000Z",
        "changePercent": -14.2,
        "direction": "falling"
    },
    "interestOverTime": [
        { "date": "2025-11-09T00:00:00.000Z", "formattedTime": "Nov 9 – 15, 2025", "value": 58, "hasData": true, "isPartial": false }
    ],
    "interestByRegion": [
        { "geoCode": "US-HI", "geoName": "Hawaii", "value": 100 },
        { "geoCode": "US-WY", "geoName": "Wyoming", "value": 88 }
    ],
    "relatedQueries": {
        "top": [{ "query": "matcha latte", "value": 100, "formattedValue": "100", "isBreakout": false, "trendsUrl": "https://trends.google.com/trends/explore?q=matcha+latte&date=today+12-m&geo=US" }],
        "rising": [{ "query": "matcha banana bread", "value": 5000, "formattedValue": "Breakout", "isBreakout": true, "trendsUrl": "..." }]
    },
    "regionResolution": "REGION",
    "trendsUrl": "https://trends.google.com/trends/explore?q=matcha&date=today+12-m&geo=US",
    "hasData": true,
    "scrapedAt": "2026-11-10T03:24:23.645Z"
}
```

Trending Now items (`type: "trendingSearch"`):

```json
{
    "type": "trendingSearch",
    "geo": "US",
    "locationName": "United States",
    "hours": 24,
    "rank": 1,
    "title": "kirk cousins",
    "searchVolume": 1000000,
    "approxTraffic": "1M+",
    "increasePercent": 1000,
    "startedAt": "2026-11-10T02:10:00.000Z",
    "endedAt": null,
    "isActive": true,
    "categories": [{ "id": 17, "name": "Sports" }],
    "trendBreakdown": ["kirk cousins", "kirk cousins trade", "vikings trade", "trade deadline"],
    "trendsUrl": "https://trends.google.com/trends/explore?q=kirk+cousins&geo=US&date=now+1-d",
    "news": [{ "title": "...", "url": "https://...", "source": "ESPN", "picture": "https://..." }]
}
```

The dataset has two ready-made table views: **Keyword overview** (one row per keyword with its stats) and **Trending now**.

### Pricing

Pay per result, platform usage included:

- **Keyword report** (one keyword with all selected sections): **$4.50 per 1,000** ($4.00 on Scale, $3.50 on Business plans).
- **Trending search** (one trending item): **$0.80 per 1,000** ($0.70 / $0.60).
- Keywords with no data in Google Trends: **free**.
- Example: 100 keywords with full reports ≈ $0.45. One country's top 100 trends ≈ $0.08.

### Good to know

- Google Trends values are **relative** (0–100), not absolute search volumes. 100 = the peak for that keyword, location and time range.
- Values for the same keyword can shift slightly between runs: Google samples its data.
- Inside a state (e.g. `US-CA`) Google provides metro areas but not cities; a City request there returns metros, with `regionResolution: "DMA"`.
- Keywords whose only data point is the current, unfinished week are treated as "no data" (free).
- Very rare keywords can have a timeline but too little data for a regional breakdown — `interestByRegion` is then an empty list (never a list of zeros).
- Trending Now `searchVolume` is Google's own rounded estimate ("1M+"), not an exact count. If the Trending Now page can't be read, the scraper falls back to Google's RSS feed (top ~20 trends, fewer fields) instead of failing — unless you set a category or active-only filter, which the feed can't honor.
- Google currently does not return "related topics" to automated requests, so this scraper returns related **queries** only.
- Need integration help or found a bug? Open an issue on the Issues tab — issues are answered in writing.

### Legal

This Actor collects only publicly available, aggregated, anonymous data from Google Trends. It does not collect personal data. Make sure your use complies with Google's terms and the laws that apply to you.

# Actor input Schema

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

Search terms to analyze. Each keyword gets its own report (or see 'Compare keywords').

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

Paste links copied from Google Trends. Explore pages (trends.google.com/trends/explore?q=...) keep their own terms, location, time range, category and search type. Trending Now pages (trends.google.com/trending?geo=...) keep their location, time window, category and active-only filter. Other links are skipped with a warning.

## `compareKeywords` (type: `boolean`):

If on, keywords are compared in groups of up to 5 (Google's limit), so values are relative to each other — like typing several terms into Google Trends. If off, each keyword is scaled independently (0–100).

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

Country or region code, e.g. US, GB, DE, US-CA. Leave empty for Worldwide.

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

Preset time range.

## `customTimeframe` (type: `string`):

Exact date range as 'YYYY-MM-DD YYYY-MM-DD', e.g. '2025-01-01 2025-12-31'.

## `category` (type: `string`):

Limit to a Google Trends category. Pick one from the list or type any numeric category ID (subcategories work too, e.g. 1227 for Coffee & Tea).

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

Which Google search property to use.

## `includeTimeline` (type: `boolean`):

Include the time series plus summary stats (average, peak, latest, % change, direction).

## `includeRegions` (type: `boolean`):

Include the breakdown by country / state / city.

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

Include top and rising related searches, with 'Breakout' flags.

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

Granularity of the region breakdown. Auto = countries for Worldwide, states/provinces for a country. Inside a state (e.g. US-CA) Google offers metro areas but no cities — City then falls back to Metro (DMA).

## `includeLowVolumeRegions` (type: `boolean`):

Also return regions with too little search volume (value 0).

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

Country codes (US, GB, IN …) or US states (US-CA, US-NY) to fetch trending searches for: search volume, % increase, start/end time, categories, related "trend breakdown" searches, plus news for the newest ones. Works with or without keywords.

## `trendingHours` (type: `string`):

How far back to look, same as the Trending Now page.

## `trendingCategories` (type: `array`):

Only keep trends in these categories. Empty = all categories.

## `trendingActiveOnly` (type: `boolean`):

Skip trends that have already ended.

## `trendingSort` (type: `string`):

Relevance is Google's own order.

## `trendingMaxItems` (type: `integer`):

Limit per location after filters and sorting (Google lists several hundred trends per day, thousands for 7 days). 0 = no limit. You pay per trend returned.

## `trendingIncludeNews` (type: `boolean`):

Attach news articles and a picture to the trends Google publishes in its news feed — usually the newest ~10 per location; other trends get an empty list. One extra request per location.

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

Interface language for labels, e.g. en-US, de, fr.

## `timezoneOffset` (type: `integer`):

Timezone offset from UTC in minutes, as Google expects it (e.g. 300 for US Eastern standard time, -60 for CET). 0 = UTC.

## `maxConcurrency` (type: `integer`):

Parallel workers, each with its own proxy session. Higher is faster but triggers Google rate limits more often.

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

On rate limits the scraper switches to a fresh IP and retries.

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

Residential proxies are strongly recommended — Google rate-limits datacenter IPs heavily.

## Actor input object example

```json
{
  "keywords": [
    "matcha",
    "coffee"
  ],
  "compareKeywords": false,
  "geo": "",
  "timeframe": "today 12-m",
  "category": "",
  "property": "",
  "includeTimeline": true,
  "includeRegions": true,
  "includeRelatedQueries": true,
  "regionResolution": "",
  "includeLowVolumeRegions": false,
  "trendingHours": "24",
  "trendingActiveOnly": false,
  "trendingSort": "relevance",
  "trendingMaxItems": 100,
  "trendingIncludeNews": true,
  "language": "en-US",
  "timezoneOffset": 0,
  "maxConcurrency": 3,
  "maxRetries": 8,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# Actor output Schema

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

One row per keyword with its trend stats.

## `trending` (type: `string`):

Currently trending searches per country.

## `allResults` (type: `string`):

Every item with full time series, regions and related queries.

## `summary` (type: `string`):

Succeeded/failed jobs and failure reasons.

# 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": [
        "matcha",
        "coffee"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("trendpilot_data/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 = {
    "keywords": [
        "matcha",
        "coffee",
    ],
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    },
}

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

```

## MCP server setup

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