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

Scrapes Google Trends for any keyword. Extracts the full set of trends-vertical fields: interest-over-time / interest-by-region, related queries / topics / articles, value, percentage, rank, delta, growth rate, breakout flag, suggestions, time range, geo, category, and more.

- **URL**: https://apify.com/searchapi/google-trends-scraper.md
- **Developed by:** [Search API](https://apify.com/searchapi) (community)
- **Categories:** SEO tools, Developer tools, Other
- **Stats:** 11 total users, 4 monthly users, 49.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.99 / 1,000 search results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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

Extract source-backed structured data from [Google Trends Explore](https://trends.google.com/trends/explore): interest over time, interest by region, related queries, and related topics. The Actor does not substitute ordinary Google web results when Trends data is unavailable.

### Modes

- `single`: collect one `query`.
- `batch`: collect `query` plus up to 19 deduplicated `queries` concurrently.
- `dataTypes`: choose any of `interestOverTime`, `interestByRegion`, `relatedQueries`, and `relatedTopics`.

The global `maxItems` limit is divided fairly across queries and available data types. Timeline samples span the complete requested date range, while related-query samples include both top and rising terms when Google exposes them.

### Input

| Field | Purpose | Default |
| --- | --- | --- |
| `query` | Keyword or topic | required |
| `mode`, `queries` | Single or multiple independent searches | `single` |
| `dataTypes` | Structured Trends widgets to collect | all four |
| `geo` | Two-letter country code; empty means worldwide | `US` |
| `language` | Google locale | `en-US` |
| `timeRange` | Preset Google time window | `today 12-m` |
| `startDate`, `endDate` | Optional custom `YYYY-MM-DD` range | — |
| `category` | Google Trends category ID | `0` |
| `searchType` | `web`, `images`, `news`, `shopping`, or `youtube` | `web` |
| `maxItems` | Global record limit | `100` |
| `maxConcurrency` | Parallel query jobs | `2` |
| `maxRequestRetries` | Temporary-error retries | `2` |
| `requestTimeoutSecs` | Per-endpoint timeout | `45` |
| `timezoneOffsetMinutes` | Trends timezone offset | `0` |
| `proxyConfiguration` | Apify or custom proxy configuration | optional |

Example:

```json
{
  "mode": "batch",
  "query": "artificial intelligence",
  "queries": ["machine learning"],
  "dataTypes": ["interestOverTime", "interestByRegion", "relatedQueries"],
  "geo": "US",
  "timeRange": "today 3-m",
  "maxItems": 60,
  "maxConcurrency": 2,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"],
    "countryCode": "US"
  }
}
```

### Output

The dataset schema defines 38 possible fields. Normal records include the shared query, result, and provenance fields, plus only the type-specific values available in the returned Google Trends widget; absent optional values are omitted. Every normal record has at least 21 populated fields, with no placeholder values added to meet that count. Type-specific fields include:

- Timeline: `date`, `formattedTime`, `hasData`, `isPartial`.
- Region: `rank`, `geoCode`, `geoName`. The rank follows the numbered order shown in the Google Trends region panel.
- Related query/topic: `rank`, `rankType`, `growthPercentage`, `isBreakout`, `topicId`, `topicType`.

Optional values not supplied by Google are omitted instead of stored as `null`, empty strings, or fabricated defaults. Widget tokens, request signatures, cookies, proxy credentials, and raw API responses are never stored.

You can download the dataset in various formats such as JSON, HTML, CSV, or Excel.

### Proxy behavior

Direct datacenter traffic can receive HTTP 429. For production Apify Cloud runs, use `RESIDENTIAL` or an authorized custom proxy. The specialized `GOOGLE_SERP` group is suitable for Google Search result pages, but Google Trends widget endpoints return HTTP 400 through that group, so it is not the right transport for this Actor.

The Actor validates status codes and content types before parsing, preserves cookies for each query, retries only temporary failures with bounded backoff, and never attempts to solve CAPTCHA or bypass authentication/access controls.

### Performance

A representative single query with four requested data types completes in a few seconds of application time. A two-query batch normally completes well below three minutes, subject to proxy and target latency.

# Changelog

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

# Actor input Schema

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

Run one keyword or a deduplicated batch of independent keywords.

## `query` (type: `string`):

Keyword or topic to enter in Google Trends.

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

Additional keywords for batch mode. Duplicates are removed.

## `dataTypes` (type: `array`):

Supported values: interestOverTime, interestByRegion, relatedQueries, and relatedTopics, matching the widgets visible on Google Trends Explore.

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

Two-letter country code, or an empty string for worldwide data.

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

Google locale such as en-US.

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

Google Trends time window used when custom dates are not provided.

## `startDate` (type: `string`):

Optional YYYY-MM-DD start. Provide both custom dates.

## `endDate` (type: `string`):

Optional YYYY-MM-DD end. Provide both custom dates.

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

Google Trends category ID. 0 means all categories.

## `searchType` (type: `string`):

Select the Google vertical whose trend interest should be measured.

## `maxItems` (type: `integer`):

Global record limit across every query and data type.

## `maxConcurrency` (type: `integer`):

Independent query jobs processed in parallel.

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

Bounded retries for rate limits, proxy failures, and temporary 5xx responses.

## `requestTimeoutSecs` (type: `integer`):

Maximum seconds for one Trends endpoint request.

## `timezoneOffsetMinutes` (type: `integer`):

Timezone offset in minutes used by Google Trends.

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

Use Residential or custom proxies when direct Trends API traffic is rate-limited. GOOGLE_SERP is attempted through its HTTP transport but is not guaranteed to support Trends widget endpoints.

## Actor input object example

```json
{
  "mode": "single",
  "query": "artificial intelligence",
  "queries": [],
  "dataTypes": [
    "interestOverTime",
    "interestByRegion",
    "relatedQueries",
    "relatedTopics"
  ],
  "geo": "US",
  "language": "en-US",
  "timeRange": "today 12-m",
  "category": 0,
  "searchType": "web",
  "maxItems": 100,
  "maxConcurrency": 2,
  "maxRequestRetries": 2,
  "requestTimeoutSecs": 45,
  "timezoneOffsetMinutes": 0,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "countryCode": "US"
  }
}
```

# 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 = {
    "query": "artificial intelligence",
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ],
        "countryCode": "US"
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("searchapi/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 = {
    "query": "artificial intelligence",
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
        "countryCode": "US",
    },
}

# Run the Actor and wait for it to finish
run = client.actor("searchapi/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 '{
  "query": "artificial intelligence",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "countryCode": "US"
  }
}' |
apify call searchapi/google-trends-scraper --silent --output-dataset

```

## MCP server setup

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