# Google Trends Scraper (fast, no browser) (`paland/google-trends-fast`) Actor

Unofficial Google Trends scraper: interest over time, interest by region and related queries (top + rising) for up to 5 terms, any country and timeframe, as clean JSON. Direct HTTP, no browser, ~1 s per query. Explicit statuses, validated input. Pay only for queries that return data.

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

## Pricing

from $4.00 / 1,000 query with data

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?

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 (fast, no browser)

Extract **Google Trends data** as structured JSON: interest over time, regional breakdown (interest by region / sub-region) and related queries (top and rising), for up to 5 search terms per query, any country or worldwide, any timeframe from the past hour to 2004-present, on web, YouTube, image, news or shopping search.

### Why this Google Trends scraper

- **No headless browser.** Direct HTTP calls to Google Trends: about one second per query and a fraction of the memory of browser-based scrapers.
- **Explicit statuses.** Every query ends as `ok`, `no_data`, `invalid_input` or `error`. You always know why a row is empty.
- **You only pay for data.** Charged once per query that returns a timeline with data. Empty, invalid or failed queries are free.
- **Input validated before Google is called.** Wrong country codes, malformed timeframes, more than 5 terms or forbidden characters are rejected instantly with a readable message, not after a 400 from Google.
- **Rate-limit aware.** Calls are spaced and retried with backoff on Google's 429 responses, so bursts do not fail your run.
- Unicode search terms work: Japanese, Arabic, Cyrillic, accents, emojis, `c#`, `.net`.

### Input

```json
{
  "queries": [
    { "terms": ["laundry detergent"], "geo": "US", "timeframe": "today 12-m" },
    { "terms": ["lessive", "adoucissant"], "geo": "FR", "timeframe": "today 5-y" }
  ],
  "includeGeoBreakdown": true,
  "includeRelatedQueries": true
}
```

| Field | Values |
|---|---|
| `terms` | 1 to 5 search terms per query (Google's comparison limit) |
| `geo` | ISO country code (`US`, `FR`, `DE`), Google sub-region (`US-CA`, `FR-J`), 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 a past range `YYYY-MM-DD YYYY-MM-DD` |
| `category` | Google Trends category id, `0` for all |
| `property` | `""` (web), `youtube`, `images`, `news`, `froogle` (shopping) |

### Output (one record per query)

```json
{
  "status": "ok",
  "terms": ["lessive", "adoucissant"],
  "geo": "FR",
  "timeframe": "today 12-m",
  "note": "values = relative index 0-100 (100 = peak of the series), never an absolute volume",
  "timeline": [
    { "time": 1756598400, "date": "2025-08-31T00:00:00Z", "values": [73, 7], "partial": false }
  ],
  "geo_breakdown": [ { "geo_code": "FR-J", "name": "Île-de-France", "values": [100, 9] } ],
  "related_queries": {
    "top":    [ { "query": "lessive liquide", "value": 100 } ],
    "rising": [ { "query": "lessive enzymatique", "value": 350, "formatted": "+350%" } ]
  },
  "related_topics": "unavailable"
}
```

#### Read this before you compare numbers

Google Trends never returns search volumes. `values` is a **relative index from 0 to 100** where 100 is the peak of the requested series. Comparing two terms in one query puts them on the same scale (`[73, 7]` means the second term gets about a tenth of the first's interest). Comparing values across two separate queries is meaningless.

A query can legitimately return `"status": "no_data"`: the term has too little search volume in that country and timeframe (a French word queried in Italy, a niche term over the past hour, a random string). This is Google's answer, not a failure, and it is not charged.

`related_topics` is reported as `unavailable`: Google currently returns an empty list for topic entities through this channel. It is not advertised and not charged.

### Limits

- Google throttles at roughly one request per second per IP. This Actor spaces its calls accordingly: expect about 1.5 s per query, plus 1 to 2 s when regional breakdown and related queries are requested.
- Up to 5 terms per query (Google limit). Send several queries for more terms.
- Custom date ranges must lie entirely in the past.

### Use cases

Keyword research and SEO seasonality, product launch timing, market sizing by region, brand monitoring, e-commerce demand forecasting, content calendars, academic research on search interest.

### Disclaimer

This is an **unofficial** tool. It is not affiliated with, endorsed by or sponsored by Google. "Google" and "Google Trends" are trademarks of Google LLC, used here only to describe the data source.

# Actor input Schema

## `queries` (type: `array`):

One object per query: {"terms": \["laundry detergent"], "geo": "US", "timeframe": "today 12-m"}. Up to 5 terms per query (Google limit). Fields left out fall back to the defaults below.

## `terms` (type: `array`):

Used only if 'queries' is empty. 1 to 5 terms.

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

ISO 3166-1 alpha-2 ("FR", "US") or Google sub-region ("US-CA", "FR-J"). Empty = worldwide.

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

One of: 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 past range "YYYY-MM-DD YYYY-MM-DD".

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

Google Trends category id (0 = all categories).

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

Google search property: web (default), YouTube, images, news or shopping.

## `includeGeoBreakdown` (type: `boolean`):

Also fetch interest by region / sub-region for each query (one extra call).

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

Also fetch top and rising related queries for each query (one extra call).

## `maxQueries` (type: `integer`):

0 = all.

## Actor input object example

```json
{
  "queries": [
    {
      "terms": [
        "laundry detergent"
      ],
      "geo": "US"
    },
    {
      "terms": [
        "lessive",
        "adoucissant"
      ],
      "geo": "FR",
      "timeframe": "today 5-y"
    }
  ],
  "geo": "",
  "timeframe": "today 12-m",
  "category": 0,
  "property": "",
  "includeGeoBreakdown": true,
  "includeRelatedQueries": true,
  "maxQueries": 0
}
```

# Actor output Schema

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

Every query, including no\_data and invalid\_input records with their reason.

## `resultsWithData` (type: `string`):

Only records with status ok (the ones that are charged).

# 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 = {
    "queries": [
        {
            "terms": [
                "laundry detergent"
            ],
            "geo": "US"
        },
        {
            "terms": [
                "lessive",
                "adoucissant"
            ],
            "geo": "FR",
            "timeframe": "today 5-y"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("paland/google-trends-fast").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 = { "queries": [
        {
            "terms": ["laundry detergent"],
            "geo": "US",
        },
        {
            "terms": [
                "lessive",
                "adoucissant",
            ],
            "geo": "FR",
            "timeframe": "today 5-y",
        },
    ] }

# Run the Actor and wait for it to finish
run = client.actor("paland/google-trends-fast").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 '{
  "queries": [
    {
      "terms": [
        "laundry detergent"
      ],
      "geo": "US"
    },
    {
      "terms": [
        "lessive",
        "adoucissant"
      ],
      "geo": "FR",
      "timeframe": "today 5-y"
    }
  ]
}' |
apify call paland/google-trends-fast --silent --output-dataset

```

## MCP server setup

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

```

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/MJwTNvCqtHdbXysUu/builds/8eYbF1QrbZCNKpLr8/openapi.json