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

Scrape Google Trends: interest over time, interest by region, related queries (top and rising), related topics and daily trending searches by country. Compare up to 5 terms. Clean JSON, retries and residential proxy built in. No login.

- **URL**: https://apify.com/uber\_byte/google-trends-scraper.md
- **Developed by:** [Marlon Lee](https://apify.com/uber_byte) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $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

## Google Trends Scraper

Get Google Trends data as clean JSON: interest over time, interest by region (country, state, metro or city), related queries (top and rising, including "Breakout"), related topics, and the Trending now searches for any country. SEO specialists, marketers, analysts and researchers use it to track keyword demand without copying charts by hand. Compare up to 5 keywords on one scale, or run hundreds of keywords one by one, across Web, YouTube, News, Image and Shopping search. You need no Google account or API key.

### What you get

One dataset item per term per data type:

| dataType | What it contains |
|---|---|
| `interestOverTime` | Full timeline: `date` (ISO, UTC), `value` 0-100, `hasData`, `isPartial`, plus Google's `average` |
| `interestByRegion` | Regions sorted by interest: `geoCode`, `geoName`, `value` 0-100 (and `coordinates` for cities) |
| `relatedQueries` | `top` and `rising` lists: `query`, `value`, `formattedValue` (for example `+1,350%`), `isBreakout`, `link` |
| `relatedTopics` | Same as related queries, with `topic`, `topicType` and `topicMid` |
| `trendingNow` | One item per trending search: rank, `title`, `approxTraffic` (for example 2000), `startedAt`, picture and related `news` articles |

Every explore item also records the term, location, time range, category, property and, for compared terms, the other terms in the comparison.

### Use cases

- **Keyword research and SEO:** find rising queries around a topic before they peak.
- **Seasonality planning:** pull 5-year timelines to time campaigns, stock and content.
- **Regional targeting:** see which states, metros or cities search most for a product.
- **Brand and competitor tracking:** compare up to 5 brands on one 0-100 scale on a schedule.
- **News and content desks:** collect Trending now searches with their news articles for several countries each hour.

### How to use the Google Trends scraper

1. Open the Actor in Apify Console.
2. Choose a mode: **Explore search terms** or **Trending now**.
3. In Explore mode, enter search terms and turn on **Compare terms** if you want them on one scale. Set the location, time range, category and Google property.
4. Pick the outputs you want (interest over time, by region, related queries, related topics) and the region resolution. In Trending now mode, list the country codes.
5. Click **Start**, then download the results as JSON, CSV, Excel or HTML, or read them through the Apify API.

### Input example

```json
{
  "searchTerms": ["bitcoin", "ethereum"],
  "compareTerms": true,
  "geo": "US",
  "timeRange": "today 3-m",
  "property": "web"
}
```

Time ranges: `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 such as `2024-01-01 2024-06-30`. Properties: `web`, `youtube`, `news`, `images`, `froogle` (Shopping). Region resolution: `AUTO`, `COUNTRY`, `REGION`, `DMA` or `CITY`.

Trending now: `{ "mode": "trendingNow", "trendingGeos": ["US", "GB", "DE"] }`.

### Output example

Interest over time:

```json
{
  "term": "bitcoin",
  "geo": "US",
  "timeRange": "today 3-m",
  "category": 0,
  "property": "web",
  "comparedWith": ["ethereum"],
  "dataType": "interestOverTime",
  "average": 57,
  "points": 93,
  "timeline": [
    { "date": "2026-06-29T00:00:00.000Z", "timestamp": 1782691200, "formattedTime": "Jun 29, 2026", "value": 94, "hasData": true, "isPartial": false }
  ],
  "scrapedAt": "2026-09-29T19:43:25.630Z"
}
```

Related queries:

```json
{
  "term": "bitcoin",
  "dataType": "relatedQueries",
  "top": [{ "query": "bitcoin price", "value": 100, "formattedValue": "100", "isBreakout": false, "link": "https://trends.google.com/trends/explore?q=bitcoin+price&date=today+3-m&geo=US" }],
  "rising": [{ "query": "british man recovers lost bitcoin", "value": 10750, "formattedValue": "Breakout", "isBreakout": true, "link": "..." }]
}
```

Trending now:

```json
{ "dataType": "trendingNow", "geo": "DE", "rank": 10, "title": "enteignung", "approxTraffic": 1000, "approxTrafficText": "1000+", "startedAt": "2026-09-29T18:50:00.000Z", "news": [{ "title": "...", "url": "https://www.welt.de/...", "source": "WELT" }] }
```

### Pricing

You pay per result saved, with no monthly rental. One result is a whole data type for one term, so a full 12-month timeline counts once. Empty results aren't charged: if Google has no data for a term, you get a log warning and no dataset item. Retries never charge twice, because the Actor skips results it already saved. Set a maximum spend per run and the Actor stops once it reaches that limit.

### FAQ

**Is it legal to scrape Google Trends?**
The Actor collects public, aggregated Google Trends data without logging in, and no personal data. Google's terms govern automated access, so review them for your use case. You're responsible for how you use the data.

**Will Google block it? Which proxy should I use?**
Google Trends answers HTTP 429 "Too Many Requests" quickly, the main reason Trends scrapers fail. The Actor follows the same flow as the open-source `pytrends` and `google-trends-api` libraries: it gets an `NID` cookie from trends.google.com, calls the explore endpoint for widget tokens, then fetches each widget. Each session keeps its own cookie and a sticky proxy IP. On a 429 or a "sorry" page, it retires the session and retries on a new IP and cookie with exponential backoff (up to 60 seconds), up to 10 times by default. Use residential proxy, the default. Google blocks datacenter IPs quickly, and each request is only a few KB.

**Can I get absolute search volume?**
No. Google Trends doesn't publish it.

**How do I compare more than 5 terms?**
Google allows at most 5 per comparison. Put one common anchor term in each group of 5 and rescale the groups against it.

**What are the limits?**

- Values are relative 0-100 indexes, not search volumes. Values from separate runs, or from terms not compared together, aren't on the same scale.
- Related topics are often empty. In our tests in September 2026, Google's API returned an empty related topics list for every query we tried (web and YouTube, several time ranges), and it doesn't offer related topics at all when terms are compared. The option is off by default.
- Trending now returns about 10 searches per country. It uses Google's public Trending now RSS feed, which lists only the current top searches, not the full list or the historical archive.
- Low-volume terms may have no data. The Actor skips them with a warning.
- Google can still block a run. Retries with new IPs fix almost all 429s, but heavy blocking can make some terms fail. The log names them.
- Google can change these internal endpoints without notice.

# Actor input Schema

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

Mode.

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

Keywords to look up (Explore mode). Each term runs on its own unless "Compare terms" is on.

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

Query all terms together (max 5) so values are on one shared 0-100 scale, like the Trends compare view.

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

Country or region code, e.g. US, GB, US-CA. Empty = worldwide.

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

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 "2024-01-01 2024-06-30".

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

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

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

Google property.

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

Interest over time.

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

Interest by region.

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

Related queries (top + rising).

## `includeRelatedTopics` (type: `boolean`):

In our tests (Sep 2026) Google returned empty related topics through its API for every query, so this is off by default. Empty results are never charged.

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

Region resolution.

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

Include low search volume regions.

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

Country codes for Trending now mode, e.g. US, GB, DE.

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

Interface language (hl), affects formatted labels and topic names.

## `maxRequestRetries` (type: `integer`):

Each retry uses a fresh session and proxy IP, with exponential backoff.

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

Residential proxy is strongly recommended: Google blocks datacenter IPs quickly (HTTP 429).

## Actor input object example

```json
{
  "mode": "explore",
  "searchTerms": [
    "bitcoin",
    "ethereum"
  ],
  "compareTerms": false,
  "geo": "",
  "timeRange": "today 12-m",
  "category": 0,
  "property": "web",
  "includeInterestOverTime": true,
  "includeInterestByRegion": true,
  "includeRelatedQueries": true,
  "includeRelatedTopics": false,
  "regionResolution": "AUTO",
  "includeLowSearchVolumeRegions": false,
  "trendingGeos": [
    "US"
  ],
  "language": "en-US",
  "maxRequestRetries": 10,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# Actor output Schema

## `results` (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": [
        "bitcoin",
        "ethereum"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("uber_byte/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": [
        "bitcoin",
        "ethereum",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("uber_byte/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": [
    "bitcoin",
    "ethereum"
  ]
}' |
apify call uber_byte/google-trends-scraper --silent --output-dataset

```

## MCP server setup

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