# Google Trends Scraper: Timeline, Regions & Related Queries (`datasmithlab/google-trends-scraper`) Actor

Google Trends data without the 429 errors: interest over time, regions, related queries and trending searches for many keywords and countries at once. Comparable multi-keyword charts, hourly to 20-year ranges.

- **URL**: https://apify.com/datasmithlab/google-trends-scraper.md
- **Developed by:** [Datasmithlab](https://apify.com/datasmithlab) (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 $1.50 / 1,000 search term 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/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

Get Google Trends data for many keywords and countries in one run: **interest over time, interest by region, related queries (top and rising) and today's trending searches**. Output is clean JSON, CSV or Excel.

Google rate-limits Trends hard (the famous 429 errors). This actor retries every single request from a fresh IP, so a run finishes with complete data instead of half-empty rows. You pay only for terms that come back with data.

**Typical uses:** keyword and SEO research, content planning, seasonality and demand forecasting, product and market research by country or US state, brand monitoring, spotting breakout queries.

### What you get

| Field | Notes |
|---|---|
| `keyword`, `geo`, `timeRange` | One row per search term and country (`WORLD` for worldwide) |
| `status` | `ok`, `no_data` (Google has no data for the term), `partial` (timeline fine but regions or related queries could not be fetched) or `failed`. Only `ok` rows are charged |
| `average`, `peak` | Interest on Google's 0-100 scale; `peak` has the date and value |
| `timeline[]` | Every data point: `date`, `label`, `value`, plus `isPartial` / `noData` flags |
| `regions[]` | Countries, states, cities or metro areas where the term is searched most (`geoCode`, `geoName`, `value`) |
| `relatedQueries.top[]` / `.rising[]` | Related searches with Google's score or `Breakout` / `+N%` growth, and a link to each |
| `comparedWith` | Other terms in the same comparison group |
| `trendsUrl` | Link to the same chart on trends.google.com |

**Trending mode** returns Google's daily trending searches per country: `rank`, `term`, `approxTraffic`, `publishedAt` and the news stories behind each trend.

### How to use

1. Add **Search terms** and one or more **Countries / regions** (`US`, `DE`, `TR`, or a subregion such as `US-CA`; `WORLD` for worldwide).
2. Pick a **Time range**: from the past hour (minute-level points) to 2004-present, or a custom `YYYY-MM-DD YYYY-MM-DD` range.
3. Turn on **Compare terms** when you want values that are directly comparable. Google scales every chart to 100 for its highest point, so terms are only comparable when they are requested together (groups of up to 5).
4. Run it and download the dataset.

Other filters: Google property (web, news, YouTube, images, shopping), category ID, region detail (countries, states, cities, US metro areas) and interface language.

### Output example

```json
{
  "type": "interest",
  "keyword": "rust",
  "geo": "US",
  "timeRange": "today 12-m",
  "status": "ok",
  "average": 21,
  "peak": { "date": "2026-03-08T00:00:00.000Z", "value": 100 },
  "comparedWith": ["python"],
  "timeline": [{ "date": "2025-10-12T00:00:00.000Z", "label": "Oct 12 – 18, 2025", "value": 18 }],
  "regions": [{ "geoCode": "US-WY", "geoName": "Wyoming", "value": 100 }],
  "relatedQueries": {
    "top": [{ "query": "what is rust", "value": 100, "label": "100", "url": "https://trends.google.com/trends/explore?q=what+is+rust..." }],
    "rising": [{ "query": "rust 1.80", "value": 5000, "label": "Breakout", "url": "https://trends.google.com/trends/explore?q=rust+1.80..." }]
  },
  "trendsUrl": "https://trends.google.com/trends/explore?q=python%2Crust&date=today+12-m&hl=en-US&geo=US",
  "scrapedAt": "2026-10-13T12:00:00.000Z"
}
```

### Pricing

Pay per event: a small start fee per run (charged per GB of memory), a fee per search term result and a smaller fee per trending search. Terms Google has no data for, partial results and failed lookups are free. Proxy costs are included. Higher Apify plans get a lower price per result. Use **Max results** to cap spending.

### Good to know

- Google Trends shows relative interest (0-100), not search volumes. Values from different runs or different groups are not comparable unless the terms were compared together.
- Very specific or low-volume terms often return no data; these rows get `status: no_data` and are not charged.
- **Related topics are not offered**: Google currently returns them empty.
- Region detail depends on Google: US metro areas (`DMA`) and states work well, while city-level data is sparse and worldwide runs return mostly countries.
- Hourly and daily ranges do not include Google's own average, so `average` is computed from the returned points.
- Terms in a group of 5 are comparable only with each other; with more than 5 terms, each group of 5 is scaled separately.
- Trending mode reads Google's public trending feed, which lists about 10-25 searches per country at a time.
- If Google blocks a request the actor retries it from a new IP. Terms that still fail after several rounds are listed in the `SUMMARY` record of the run and returned as `failed` rows.
- Concurrency defaults to 4. Raise it for speed, lower it if you see many retries in the log.
- Only public aggregate data is collected; no personal data. Use the data in line with Google's terms and the laws that apply to you.

# Actor input Schema

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

Interest data for search terms (timeline, regions, related queries), or today's trending searches per country.

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

Keywords or topics to look up. One result row per term and country (or per term when compared). Used in 'Interest' mode.

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

Google Trends scales every chart to 100 for its highest point. When ON, terms are sent to Google in groups of up to 5 so their values are directly comparable. When OFF, each term is scaled on its own.

## `geos` (type: `array`):

Country codes (US, DE, GB, TR...) or subregions (US-CA). Use WORLD for worldwide. In 'Trending' mode each code must be a country.

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

Preset period. Hourly and daily ranges return finer-grained points.

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

Optional. Format: YYYY-MM-DD YYYY-MM-DD (for example 2024-01-01 2024-12-31). Overrides the preset above.

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

Which Google search to measure interest in.

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

Google Trends category number (0 = all categories, 7 = Finance, 3 = Arts & Entertainment...). See the README for common IDs.

## `includeRegions` (type: `boolean`):

Adds the regions (countries, states, metro areas) where each term is searched most.

## `regionResolution` (type: `string`):

Granularity of the regional breakdown. 'Automatic' lets Google choose (countries for worldwide, states for a country).

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

Adds the top and rising related search queries for each term.

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

Language of date labels in the output (for example en-US, de, tr).

## `trendingMax` (type: `integer`):

'Trending' mode only. Google's public feed currently lists about 10-25 searches per country.

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

Hard cap on result rows, to control cost.

## `concurrency` (type: `integer`):

How many lookups run at the same time. Lower this if you see many retries in the log.

## Actor input object example

```json
{
  "mode": "interest",
  "searchTerms": [
    "python",
    "rust"
  ],
  "compare": false,
  "geos": [
    "US"
  ],
  "timeRange": "past-12-months",
  "property": "web",
  "category": 0,
  "includeRegions": true,
  "regionResolution": "AUTO",
  "includeRelatedQueries": true,
  "language": "en-US",
  "trendingMax": 25,
  "maxItems": 1000,
  "concurrency": 4
}
```

# Actor output Schema

## `interest` (type: `string`):

No description

## `trending` (type: `string`):

No description

## `allFields` (type: `string`):

No description

## `summary` (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 = {
    "searchTerms": [
        "python",
        "rust"
    ],
    "geos": [
        "US"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("datasmithlab/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 = {
    "searchTerms": [
        "python",
        "rust",
    ],
    "geos": ["US"],
}

# Run the Actor and wait for it to finish
run = client.actor("datasmithlab/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 '{
  "searchTerms": [
    "python",
    "rust"
  ],
  "geos": [
    "US"
  ]
}' |
apify call datasmithlab/google-trends-scraper --silent --output-dataset

```

## MCP server setup

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