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

Google Trends data that actually comes back. Google requires a session cookie before serving its Trends endpoints and throttles back-to-back calls — this primes the session and paces requests, so runs succeed instead of returning empty. Interest over time, related queries, regional interest.

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

## Pricing

from $0.70 / 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.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#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 — reliable, structured, no broken runs

Scrape **Google Trends** data at scale: interest over time, related queries, related topics and interest by region, returned as flat tabular rows that drop straight into a spreadsheet, a database or a BI tool. Built for teams who need Google Trends data to arrive **every single run**, not most of the time.

If you have used a Google Trends scraper before and got empty datasets, half-finished runs or cryptic errors, that is the problem this actor exists to solve.

### Why another Google Trends scraper

Google Trends has no official public API. Every scraper talks to the same internal endpoint, which means they mostly differ in one respect: **how they behave when something goes wrong.** Most handle it badly.

Three things break Google Trends scrapers, and all three are handled here:

- **Expired tokens.** Trends issues a short-lived token per request group. When it expires mid-run, most scrapers fail the entire job. This one detects a stale token, silently fetches a fresh one and retries.
- **Rate limiting.** Google throttles hard, especially from datacenter IPs. This actor uses exponential backoff with jitter and rotates to a new residential IP on each retry, rather than surfacing a crash.
- **Missing data for low-volume keywords.** A niche keyword often has no regional breakdown or no related queries. That is normal, and it should not fail your run. Here it does not — you get everything that exists, plus a clear note about what did not.

**Partial success is treated as success.** If four of your five keywords return data, you get four keywords of data and a machine-readable record of the fifth. You are never charged for rows you did not receive.

### What you get

| Dataset | What it contains |
|---|---|
| Interest over time | One row per keyword per date, with the raw 0–100 value, a real ISO timestamp and a flag for partial (still-forming) data points |
| Related queries | Top and rising searches, with breakout terms explicitly flagged |
| Related topics | Top and rising topics, with topic type |
| Interest by region | Per-country or per-subregion values, with a flag showing whether a region had enough data |

Every result is **flat and tabular** — one row per observation. No nested JSON to unpick before you can use it. Export to CSV, JSON, Excel or push straight into your warehouse.

### Common use cases

- **SEO and content planning** — find rising search terms before they peak
- **Market research** — compare brand or product interest across countries and time
- **Trend monitoring** — schedule daily runs and alert on breakout terms
- **Competitive analysis** — track share of search between you and your competitors
- **Demand forecasting** — pull five years of seasonality for planning

### Input

```json
{
  "keywords": ["artificial intelligence", "machine learning"],
  "timeframe": "today 12-m",
  "geo": "US",
  "includeRelatedQueries": true,
  "includeByRegion": true
}
```

**Keywords** — up to five per run. Google Trends compares a maximum of five terms at once; the actor tells you clearly rather than silently truncating.

**Timeframe** — past hour through to all time (2004 onwards), or a custom range like `2025-01-01 2025-12-31`.

**Geo** — an ISO country code such as `US`, `GB` or `AU`. Leave blank for worldwide. Sub-regions work too, for example `US-CA`.

**Compare mode** — on by default, matching how Google Trends works: values are relative to each other. Turn it off to fetch each keyword separately so its values stand alone.

### Output

```json
{
  "type": "interest_over_time",
  "keyword": "artificial intelligence",
  "date": "Jan 1, 2026",
  "isoDate": "2026-01-01T00:00:00.000Z",
  "timestamp": 1767225600,
  "value": 78,
  "isPartial": false
}
```

Note `isPartial`. Google's most recent data point is often still forming and will change. Most scrapers hand it to you as though it were final. This one labels it.

Missing values are returned as `null`, never as `0` — because `0` is a real Google Trends value meaning "no measurable interest", and conflating the two quietly corrupts any analysis built on top.

### Proxies

Residential proxies are strongly recommended and are the default. Google rate limits datacenter IPs aggressively, and datacenter traffic is the single most common cause of failed Trends runs.

### Scheduling

Run it on a schedule to build a time series of your own: daily runs of the same keyword set give you a change log Google Trends itself does not provide, including when a term first goes breakout.

### Notes

Google Trends values are **relative, not absolute**. A value of 100 means peak interest for that keyword within the selected timeframe and region — it is not a volume figure. Comparing runs with different timeframes will not give you comparable numbers.

This actor is unofficial and is not affiliated with, endorsed by, or connected to Google. Please use it only for publicly available data and in line with applicable laws and terms.

# Actor input Schema

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

Up to 5 search terms. Google Trends compares a maximum of 5 at once.

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

How far back to look. Use a preset, or type a custom range like 2025-01-01 2025-12-31.

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

ISO code such as US, GB or AU. Leave blank for worldwide. Sub-regions work too, for example US-CA.

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

Google Trends category to narrow results. 0 means all categories.

## `hl` (type: `string`):

Language code for the results, for example en-US or de-DE.

## `compare` (type: `boolean`):

On: values are relative to each other, which is how Google Trends works by default. Off: each keyword is fetched separately so its values stand alone.

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

Search interest for each keyword over the selected timeframe, one row per keyword per date.

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

Top and rising searches related to your keywords, with breakout terms flagged.

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

Top and rising topics related to your keywords.

## `includeByRegion` (type: `boolean`):

Search interest broken down by country, or by sub-region when a country is selected above.

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

Residential proxies are strongly recommended. Google rate limits datacenter IPs aggressively, and that is the most common cause of failed runs.

## Actor input object example

```json
{
  "keywords": [
    "artificial intelligence",
    "machine learning"
  ],
  "timeframe": "today 12-m",
  "geo": "",
  "category": 0,
  "hl": "en-US",
  "compare": true,
  "includeInterestOverTime": true,
  "includeRelatedQueries": false,
  "includeRelatedTopics": false,
  "includeByRegion": false,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# Actor output Schema

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

Every row from this run as clean JSON — interest over time, related queries, related topics and regional breakdowns.

## `resultsCsv` (type: `string`):

The same rows as a CSV download, ready for a spreadsheet.

## `interestOverTime` (type: `string`):

Search interest per keyword per date, with still-forming data points flagged.

## `relatedQueries` (type: `string`):

Top and rising searches related to your keywords, with breakout terms flagged.

## `relatedTopics` (type: `string`):

Top and rising topics related to your keywords.

## `byRegion` (type: `string`):

Search interest broken down by country, or by sub-region when a country was selected.

## `runSummary` (type: `string`):

Row counts per dataset, and a record of any keyword or breakdown that could not be retrieved. Partial runs still return data — this tells you exactly what is missing.

# 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": [
        "artificial intelligence",
        "machine learning"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("datalayer/google-trends-reliable").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": [
        "artificial intelligence",
        "machine learning",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("datalayer/google-trends-reliable").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": [
    "artificial intelligence",
    "machine learning"
  ]
}' |
apify call datalayer/google-trends-reliable --silent --output-dataset

```

## MCP server setup

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

```

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/21NqgjyKULU6yTR8J/builds/rodWVHz5jujPXlnon/openapi.json