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

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

## Pricing

from $10.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 (reliable)

**Google Trends data for your search terms, as clean JSON.** Get interest over time, interest by region, related queries and related topics for one term or for up to five terms compared in one chart. Any term that fails gets an explicit error record, and you are never charged for it.

Use it to track demand for a product category, compare brands, time content and campaigns, or find rising queries in a market.

### Why use it

- **Reliable by design.** Each term (or comparison group) runs in isolation, so one failure never fails the run. When Google rate-limits a request (HTTP 429), the Actor waits as long as Google asks (`Retry-After`), or backs off exponentially, and tries again, up to 3 times per term. Then it writes an `error` record and moves on.
- **You pay only for data.** Only `result` records are charged. Errors, terms with no data and the closing `summary` record are free.
- **Honest about gaps.** If Google does not provide a section for a request, the record says so in `warnings` instead of returning silent empty data.
- **Polite.** The Actor reads `robots.txt` at the start of every run and honours it. It uses only the Trends data API (`/trends/api/...`) and never requests the explore pages. It sends at most one request per second and identifies itself with a descriptive User-Agent.

### Input

| Field | What it does |
|---|---|
| `searchTerms` | **Required.** Terms to look up, e.g. `["web scraping"]`. Topic ids such as `/m/05z1_` also work. |
| `compareMode` | Off (default): one record per term, each scaled 0-100 on its own. On: terms compared in groups of up to 5, one record per group, with values scaled together. |
| `timeRange` | `now 1-H`, `now 4-H`, `now 1-d`, `now 7-d`, `today 1-m`, `today 3-m`, `today 12-m` (default), `today 5-y` or `all`. |
| `customTimeRange` | Exact dates, `"YYYY-MM-DD YYYY-MM-DD"`. Overrides `timeRange`. |
| `geo` | Country or region code (`US`, `GB`, `US-CA`). Empty = worldwide. |
| `category` | Google Trends category id; 0 = all (default). |
| `gprop` | `web` (default), `images`, `news`, `froogle` (Shopping) or `youtube`. |
| `interestOverTime` | Time series. On by default. |
| `interestByRegion` | Interest by subregion. On by default. |
| `relatedQueries` | Top and rising related queries. On by default. |
| `relatedTopics` | Top and rising related topics. Off by default (see Limitations). |
| `hl` | Language for labels and region names, default `en-US`. |
| `tz` | UTC offset in minutes, Google's convention (`300` = UTC-5), default `0`. |

Example:

```json
{"searchTerms": ["web scraping"], "geo": "US", "timeRange": "today 12-m"}
```

### Output

Each dataset item has a `type` field:

- **`result`** is one term or one comparison group, with the sections you asked for.
- **`error`** is one term or group that failed. It has an `error_code` (`invalid_input`, `robots_disallowed`, `robots_unavailable`, `rate_limited`, `blocked`, `consent_required`, `http_error`, `network_error`, `bad_response`, `parse_error`, `no_data` or `skipped`) and a message. You are not charged for it.
- **`summary`** is one per run, with counts, the number of requests made and the duration.

```json
{
  "type": "result",
  "searchTerm": "web scraping",
  "searchTerms": ["web scraping"],
  "comparison": false,
  "geo": "US",
  "timeRange": "today 12-m",
  "timeRangeResolved": "2025-10-25 2026-10-25",
  "category": 0, "gprop": "web", "hl": "en-US", "tz": 0,
  "interestOverTime": {
    "resolution": "WEEK",
    "averages": null,
    "points": [{"time": "2025-10-19T00:00:00Z", "formattedTime": "Oct 19 – 25, 2025", "isPartial": false, "values": {"web scraping": 66}}]
  },
  "interestByRegion": {
    "resolution": "REGION",
    "regions": [{"geoCode": "US-MD", "geoName": "Maryland", "values": {"web scraping": 100}}]
  },
  "relatedQueries": {
    "web scraping": {
      "top": [{"query": "ai web scraping", "value": 100, "formattedValue": "100", "link": "https://trends.google.com/trends/explore?q=ai+web+scraping&date=today+12-m&geo=US"}],
      "rising": [{"query": "...", "value": 11900, "formattedValue": "Breakout", "link": "..."}]
    }
  },
  "warnings": [],
  "exploreUrl": "https://trends.google.com/trends/explore?q=web+scraping&date=today+12-m&hl=en-US&geo=US",
  "scrapedAt": "2026-10-25T09:53:59Z"
}
```

`values` are keyed by search term, so a comparison record holds every term's value in each point and region. Values are Google's relative 0-100 index, not search counts. In a comparison, region values are each term's share in that region. A `null` value means Google has no data for that point.

### Pricing

Pay per event: **$0.01 per `result` record** ($10 per 1,000 results), plus a $0.00005 start fee per run. You pay nothing for `error` or `summary` records, and there is no extra charge for platform usage. If you set a maximum cost per run, the Actor stops cleanly at that limit and makes no further requests to Google.

### Responsible use

- **Allowed paths only.** The Actor uses the Trends data API, which Google's `robots.txt` allows. It never requests `/explore` or `/trends/explore` pages, which `robots.txt` disallows, and it checks every URL against the live `robots.txt` before requesting it.
- **No circumvention.** It never rotates IP addresses or sessions, uses no headless browser and fakes no browser fingerprint. A captcha, an "unusual traffic" page, a 401 or 403 response or a consent wall stops that term at once, with no retry, and the Actor then skips the rest of the run rather than keep trying. After two terms fail on rate limiting, it skips the remaining terms too.
- **Aggregate data only.** Google Trends data is anonymised, aggregated search interest. It holds no personal data.
- **You are responsible for your use.** Comply with applicable law and with Google's terms. Google Trends data is a sample, normalised to 0-100, so treat it as a relative signal, not as search volume.
- **Contact:** open an issue on the Issues tab of this Actor's page (https://apify.com/reliable-apps/google-trends-reliable/issues).

### Limitations

- **Rate limits.** Google limits how often Trends can be queried, and it limits shared cloud IP addresses most. By design the Actor does not work around this, so large batches can end with `rate_limited` errors. Smaller batches and longer gaps between runs help. You are never charged for those errors.
- **Related topics** are not available in comparison mode, and Google often returns the list empty. In that case the record carries a warning.
- **Comparisons** hold at most 5 terms. Longer lists are split into groups of 5, and values are comparable only within a group.
- Values are relative (0-100) and Google samples them, so two runs can differ slightly.

# Changelog

This Actor's version history is a separate document: https://apify.com/reliable-apps/google-trends-reliable/changelog.md

# Actor input Schema

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

Words or phrases to look up on Google Trends. A Knowledge Graph topic id (such as "/m/05z1\_") also works. Each term produces one result record, unless you turn on comparison mode.

## `compareMode` (type: `boolean`):

Off: each term is looked up on its own, and values are scaled 0-100 per term. On: terms are compared in groups of up to 5 (Google's limit), with one record per group and values scaled together, so they are comparable within the group. Related topics are not available in comparisons.

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

Period to analyse. Use the custom range below for exact dates.

## `customTimeRange` (type: `string`):

Exact dates as "YYYY-MM-DD YYYY-MM-DD" (for example "2024-01-01 2024-06-30"). Overrides the time range above. Data starts in 2004.

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

ISO country code ("US", "GB", "DE") or region code ("US-CA", "GB-ENG"). Leave empty for worldwide.

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

Google Trends category id to narrow the search, for example 5 (Computers & Electronics) or 71 (Food & Drink). 0 means all categories.

## `gprop` (type: `string`):

Which Google search to analyse.

## `interestOverTime` (type: `boolean`):

The 0-100 search-interest time series.

## `interestByRegion` (type: `boolean`):

Interest by subregion (states for a country, countries for worldwide). In comparison mode, each region's share between the terms.

## `relatedQueries` (type: `boolean`):

Top and rising related search queries for each term.

## `relatedTopics` (type: `boolean`):

Top and rising related topics for each term. Not available in comparison mode, and Google often returns this list empty.

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

Language for region names and labels, such as "en-US" or "de".

## `tz` (type: `integer`):

UTC offset in minutes, with Google's sign convention: 0 = UTC, 300 = UTC-5, -60 = UTC+1. Affects hourly and daily ranges.

## Actor input object example

```json
{
  "searchTerms": [
    "web scraping"
  ],
  "compareMode": false,
  "timeRange": "today 12-m",
  "geo": "US",
  "category": 0,
  "gprop": "web",
  "interestOverTime": true,
  "interestByRegion": true,
  "relatedQueries": true,
  "relatedTopics": false,
  "hl": "en-US",
  "tz": 0
}
```

# Actor output Schema

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

One record per search term (or comparison group), plus error and summary records.

# 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": [
        "web scraping"
    ],
    "timeRange": "today 12-m",
    "geo": "US"
};

// Run the Actor and wait for it to finish
const run = await client.actor("reliable-apps/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 = {
    "searchTerms": ["web scraping"],
    "timeRange": "today 12-m",
    "geo": "US",
}

# Run the Actor and wait for it to finish
run = client.actor("reliable-apps/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 '{
  "searchTerms": [
    "web scraping"
  ],
  "timeRange": "today 12-m",
  "geo": "US"
}' |
apify call reliable-apps/google-trends-reliable --silent --output-dataset

```

## MCP server setup

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