# Google Trends Scraper — Reliable (`glenn.eugene/google-trends-reliable`) Actor

Google Trends data that actually arrives: interest over time, interest by region, related queries and topics, and trending searches. Built for reliability, with retries and partial results instead of failed runs. Pay per result; the run summary is always free.

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

## Pricing

from $0.20 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
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 — Reliable

Google Trends data that actually arrives.

If you have used Google Trends tools before, you know the pattern: the run starts, Google rate-limits it, and you get an error — or worse, an empty dataset — while still paying for the compute. This actor is built specifically to not do that. It treats reliability as the product:

- **Proper session handling.** Google Trends serves data only to a correctly bootstrapped session (cookies first, then the request token). The actor builds that session the way a browser does, and rebuilds it automatically if Google invalidates it mid-run.
- **Pacing and retries with backoff.** Requests are spaced out, and any rate-limit (HTTP 429), forbidden (403), or server error is retried with growing waits — 5s, 15s, 30s — instead of failing on the first hit.
- **Partial results instead of dead runs.** If one section still cannot be fetched after every retry, the run delivers everything else and tells you exactly which section is missing (see the `run_summary` item). You never pay for an all-or-nothing failure.
- **Optional Apify Proxy support** for large or repeated runs, which keeps success rates high when Google gets aggressive.

### What you get

For 1–5 keywords, in any country (or worldwide), over preset time ranges from the past hour to the past 5 years:

- **Interest over time** — all keywords compared on one shared 0–100 timeline, like Google Trends itself.
- **Interest by region** — per keyword, which regions search most.
- **Related queries** — the top and rising searches related to each keyword.
- **Related topics** — the top and rising topics related to each keyword. (Note: Google sometimes serves no topic rows for a query. When that happens the section returns empty `top`/`rising` lists rather than failing — the data simply is not there.)
- **Trending searches** (optional) — what is trending now in the chosen location, with approximate traffic and the headlines driving it.

### Pricing

**Pay per result.** You are charged one low per-result fee for each dataset item the actor delivers: each interest-over-time item, each by-region item, each related-queries item, each related-topics item, and the trending-searches item. The final `run_summary` item is **always free** — you never pay for the bookkeeping. There is no subscription and no charge for a section that failed: if it is not in your dataset, you did not pay for it.

Apify platform usage (compute) is billed by Apify separately, as with any actor. Enabling Apify Proxy adds Apify's proxy charges.

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `keywords` | array of strings (1–5) | `["coffee"]` | Search terms to look up. Multiple terms are compared on one shared scale. |
| `geo` | string | `US` | Country code, e.g. `US`, `GB`, `DE`; region codes such as `US-CA` work too. Use `Worldwide` (or empty) for worldwide results. |
| `timeframe` | select | Past 3 months | Past hour, past 4 hours, past day, past 7 days, past month, past 3 months, past 12 months, or past 5 years. |
| `category` | integer | `0` | Google Trends category ID. `0` = all categories. |
| `sections` | checkboxes | all four | Interest over time, interest by region, related queries, related topics. |
| `includeTrending` | boolean | `true` | Add a trending-searches item for the location (worldwide runs fall back to US trending). |
| `useProxy` | boolean | `false` | Route requests through Apify Proxy. Recommended for large or repeated runs. |

#### Example input

```json
{
  "keywords": ["coffee", "tea"],
  "geo": "US",
  "timeframe": "today 3-m",
  "category": 0,
  "sections": ["timeseries", "geo", "related_queries", "related_topics"],
  "includeTrending": true,
  "useProxy": false
}
```

### Output

Every run writes these item types to the default dataset:

#### `timeseries` — one item per run

```json
{
  "type": "timeseries",
  "keywords": ["coffee", "tea"],
  "geo": "US",
  "timeframe": "today 3-m",
  "points": [
    { "date": "2026-07-31", "timestamp": 1785456000, "values": { "coffee": 74, "tea": 31 } }
  ]
}
```

`values` maps each keyword to its 0–100 interest index for that date, so compared keywords share one scale.

#### `geo` — one item per keyword

```json
{
  "type": "geo",
  "keyword": "coffee",
  "geo": "US",
  "timeframe": "today 3-m",
  "regions": [ { "region": "Hawaii", "value": 100 } ]
}
```

#### `related_queries` — one item per keyword

```json
{
  "type": "related_queries",
  "keyword": "coffee",
  "geo": "US",
  "timeframe": "today 3-m",
  "top": [ { "query": "coffee near me", "value": 100 } ],
  "rising": [ { "query": "coffee protein", "value": 4350 } ]
}
```

Rising values are percentage growth; very large growth may appear as a breakout value in the tens of thousands or higher.

#### `related_topics` — one item per keyword

```json
{
  "type": "related_topics",
  "keyword": "coffee",
  "geo": "US",
  "timeframe": "today 3-m",
  "top": [ { "title": "Coffee", "type": "Beverage", "value": 100 } ],
  "rising": []
}
```

As noted above, Google sometimes serves no topic rows; the lists are then empty and the section still counts as delivered.

#### `trending` — one item per run (when enabled)

```json
{
  "type": "trending",
  "geo": "US",
  "items": [
    { "title": "some headline topic", "approx_traffic": "500K+", "published": "2026-10-28T04:00:00+00:00", "news_titles": ["..."] }
  ]
}
```

#### `run_summary` — one item per run, always last, always FREE

```json
{
  "type": "run_summary",
  "succeeded": ["timeseries", "geo", "related_queries", "related_topics", "trending"],
  "failed": [],
  "duration_s": 24.61
}
```

`succeeded` and `failed` list section names. If a section is in `failed`, its items are absent from the dataset and you were not charged for them — everything else in the run is complete and usable.

### Tips

- Start with the defaults. Turn on **Use Apify Proxy** when you run many keywords, short timeframes (past hour/day), or scheduled frequent runs.
- Comparing keywords (2–5 at once) is the cheapest way to get relative interest: one timeseries item covers all of them on a shared scale.
- For worldwide runs, the trending block falls back to US trending searches, since there is no single worldwide trending feed.

# Actor input Schema

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

Google Trends category ID. 0 means all categories.

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

Country code to localize results, e.g. US, GB, DE (region codes such as US-CA also work). Enter "Worldwide" or leave empty for worldwide results.

## `includeTrending` (type: `boolean`):

Add one trending-searches item for the chosen location (worldwide runs fall back to US trending searches).

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

1 to 5 search terms to look up on Google Trends. With more than one term, interest over time compares them on one shared scale, exactly like Google Trends itself.

## `sections` (type: `array`):

Which data sections to include. Every section that succeeds produces dataset items. A section that still fails after retries is named in the run_summary item instead of failing the whole run.

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

Time range the trend data covers.

## `useProxy` (type: `boolean`):

Route requests through Apify Proxy. Recommended for large or repeated runs: Google rate-limits aggressive traffic, and fresh proxy IPs keep success rates high. Apify Proxy usage is billed by Apify on top of this actor's per-result price.

## Actor input object example

```json
{
  "category": 0,
  "geo": "US",
  "includeTrending": true,
  "keywords": [
    "coffee",
    "tea"
  ],
  "sections": [
    "timeseries",
    "geo",
    "related_queries",
    "related_topics"
  ],
  "timeframe": "today 3-m",
  "useProxy": false
}
```

# 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 = {
    "category": 0,
    "geo": "US",
    "includeTrending": true,
    "keywords": [
        "coffee"
    ],
    "sections": [
        "timeseries",
        "geo",
        "related_queries",
        "related_topics"
    ],
    "timeframe": "today 3-m",
    "useProxy": false
};

// Run the Actor and wait for it to finish
const run = await client.actor("glenn.eugene/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 = {
    "category": 0,
    "geo": "US",
    "includeTrending": True,
    "keywords": ["coffee"],
    "sections": [
        "timeseries",
        "geo",
        "related_queries",
        "related_topics",
    ],
    "timeframe": "today 3-m",
    "useProxy": False,
}

# Run the Actor and wait for it to finish
run = client.actor("glenn.eugene/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 '{
  "category": 0,
  "geo": "US",
  "includeTrending": true,
  "keywords": [
    "coffee"
  ],
  "sections": [
    "timeseries",
    "geo",
    "related_queries",
    "related_topics"
  ],
  "timeframe": "today 3-m",
  "useProxy": false
}' |
apify call glenn.eugene/google-trends-reliable --silent --output-dataset

```

## MCP server setup

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