# Google Trends Interest & Related Query Scraper (`vexaloom-labs/google-trends-interest-and-related-query-scraper`) Actor

Get interest-over-time, interest-by-region, and related topics/queries for any keyword, location, time range and Google surface, with side-by-side comparison for up to five keywords.

- **URL**: https://apify.com/vexaloom-labs/google-trends-interest-and-related-query-scraper.md
- **Developed by:** [vexaloom-labs](https://apify.com/vexaloom-labs) (community)
- **Categories:** SEO tools, Automation, Social media
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.99 / 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 Interest & Related Query Scraper

Pull Google Trends data without an API key: interest over time, interest by region, related
queries, and the Trending Now feed — for any keyword, location, time window and Google surface,
cookielessly and with no proxy setup.

### What this actor does

- **Interest mode** returns the same Explore view you see on trends.google.com: a 0-100 interest
  timeline, an interest-by-region breakdown, related topics (when Google serves them) and top and
  rising related queries, plus derived metrics (`averageInterest`, `latestInterest`, `peakInterest`,
  `peakDate`, `trendChangePercent`, `trendDirection`).
- **Comparison mode** puts up to five terms on one shared 0-100 scale and also returns per-term
  region breakdowns and per-term related queries, so you can see how each term ranks.
- **Trending mode** returns what is spiking in a country right now: rank-ordered items with the
  Google-reported volume bucket, growth percentage, start time and related terms, optionally with
  matching news headlines and links. Filter by any of Google's 18 trending categories.
- Works with **any country plus 3,400+ states, regions and metros**, all nine preset time windows
  (including real-time `now` ranges) and custom date ranges down to the hour, 1,100+ categories,
  and all five Google surfaces (Web, Images, News, Shopping, YouTube).
- Every row links straight back to Google Trends via `exploreUrl` or `trendingUrl` for a manual
  spot-check, and every row is tagged with `recordType` (`interest` or `trending`).

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | string (select) | `interest` | `interest` = Explore keyword analysis; `trending` = Trending Now for a country. |
| `searchTerms` | array of strings | – | Keywords to analyze (mode=interest). Each term becomes its own row, or compare up to five together. |
| `compareMode` | boolean | `false` | Compare all terms on one shared 0-100 scale in a single row (maximum 5 terms). |
| `startUrls` | array of requests | – | Optional Google Trends links (explore, embedded-chart `embed/explore` and Trending Now URLs, including `www.google.com/trends/...` redirect links). URL settings override the fields above. |
| `geo` | string (select) | Worldwide | Country, state/region or metro to analyze. Trending Now uses the country part. |
| `timeRange` | string (select) | `today 12-m` | Interest time window: `now 1-H` … `all`, or `custom` with `customDateRange`. |
| `customDateRange` | string | – | Used when `timeRange` is `custom`: `YYYY-MM-DD YYYY-MM-DD` or `YYYY-MM-DDTHH YYYY-MM-DDTHH`. |
| `category` | string (select) | `0` (All categories) | Google Trends category filter (mode=interest). |
| `searchType` | string (select) | Web Search | Google surface: Web, Images, News, Shopping or YouTube (mode=interest). |
| `geoResolution` | string (select) | Auto | Breakdown level for interest by region; applied when the location supports it. |
| `trendingHours` | string (select) | `24` | Trending window: past 4, 24 or 48 hours, or past 7 days (mode=trending). |
| `trendingCategory` | string (select) | All categories | Filter trending items to one of Google's 18 trending categories (mode=trending). |
| `includeTrendingNews` | boolean | `true` | Attach matching news headlines, links and sources to trending items (mode=trending). |
| `maxItems` | integer (1-10000) | `100` | Cap on dataset records per run (one per interest row or trending item). |

#### Example: one keyword over the last 12 months

```json
{ "mode": "interest", "searchTerms": ["tesla"], "geo": "US", "timeRange": "today 12-m" }
```

#### Example: compare three brands worldwide over five years

```json
{
  "searchTerms": ["tesla", "ford", "toyota"],
  "compareMode": true,
  "geo": "",
  "timeRange": "today 5-y",
  "category": "47"
}
```

#### Example: Trending Now in Germany, last 24 hours

```json
{ "mode": "trending", "geo": "DE", "trendingHours": "24", "includeTrendingNews": true, "maxItems": 100 }
```

#### Example: scrape pasted Google Trends links

```json
{
  "startUrls": [
    { "url": "https://trends.google.com/trends/explore?q=pizza&geo=US&date=today%203-m" },
    { "url": "https://trends.google.com/trending?geo=GB&hours=48" }
  ]
}
```

### Output

Every row carries `recordType`, `geo`, `geoName` and `scrapedAt`.

**Interest rows:** `searchTerms`, `timeRange`, `timeRangeLabel`, `category`, `categoryName`,
`searchType`, `searchTypeLabel`, `exploreUrl`, `interestOverTime` (points with `date`,
`formattedTime`, `value` — or `values[]` per term in comparison mode — and `isPartial` on the
current period), `averageInterest`, `latestInterest`, `peakInterest`, `peakDate`,
`trendChangePercent`, `trendDirection`, `interestByRegion`, `relatedTopics`, `relatedQueries`.
`trendDirection` compares the last quarter of the window with the first (rising at +10% or more,
falling at -10% or less). Comparison rows add `interestByRegionPerTerm` and `relatedQueriesPerTerm`.

**Trending rows:** `rank`, `title`, `hours`, `hoursLabel`, `startedAt`, `endedAt`, `volume`,
`volumeText`, `growthPercent`, `relatedTerms`, `news` (when `includeTrendingNews` is on),
`trendingUrl`.

A query that Google cannot serve (no data for the keyword) is logged and skipped; empty fields are
omitted rather than written as nulls.

### FAQ

**What do the 0-100 interest numbers mean?** They are Google's relative interest scores, normalised
to 100 at the peak of the requested window and location — never absolute search counts. Google does
not publish absolute volumes; for Trending Now, `volume` is Google's own bucket estimate.

**Do I need an API key, cookies or a proxy?** No. The actor works anonymously with no setup; when a
request is rate-limited it waits and retries on its own, and only switches connection path if a
block persists.

**Why is `relatedTopics` sometimes missing?** Related topics come from a separate Google widget
that currently returns no data for most queries on Google Trends itself; the field appears whenever
Google serves any. Related queries are unaffected.

**How many terms can I compare at once?** Five, Google Trends' own limit. Additional terms are
trimmed. To cover more keywords, run them independently (`compareMode` off) — each becomes its own
row on its own 0-100 scale.

**Does Trending Now work for states or cities?** No. Google only publishes the trending list at
country level; a state or metro location is mapped to its country.

**Why would a niche keyword show a flat or sparse timeline?** Google returns points only where it
has enough search data. Very rare terms yield mostly empty values; the actor reports exactly what
Google sends.

**Why are trending news links only on some rows?** Google's Trending RSS feed highlights about ten
stories per country rather than every trending item, and those stories can sit anywhere in the
Trending Now list. Small record caps may cover none of them; raise `maxItems` to cover more of
the list.

**What does `maxItems` count?** One `interest` row counts as one record and each `trending` item as
one record. The run stops cleanly once the limit is reached.

**What are the limits of a custom date range?** Google Trends data starts in 2004 (earlier dates are
clamped to 2004), the end date cannot be in the future, and hourly ranges are limited to about seven
days. Longer windows automatically switch to weekly or monthly points.

**Is this affiliated with Google?** No. This is an independent tool and is not affiliated with,
endorsed by, or sponsored by Google.

### Use cases

- **SEO and content planning** — mine rising related queries and topics before writing new content.
- **Brand and market tracking** — compare brands on one scale and see where interest is rising.
- **Launch monitoring** — watch breaking Trending Now items with their growth and news context.
- **Market research** — map demand across countries and sub-regions for a product or category.
- **Seasonality analysis** — pull multi-year timelines to find recurring peaks for planning.

# Actor input Schema

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

What to scrape. 'Interest over time & related queries' is the Google Trends Explore view (keywords required). 'Trending now' lists what is spiking in a country right now.

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

One or more search terms to analyze (mode=interest). Each term becomes its own dataset row, or enable Comparison mode to compare up to 5 terms side by side. Example: `tesla` or `tesla, ford, toyota`.

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

Compare all search terms on one shared 0-100 scale in a single row (Google Trends comparison view, maximum 5 terms). Off means each term is scraped independently.

## `startUrls` (type: `array`):

Paste Google Trends links to scrape them directly: explore links (trends.google.com/trends/explore?q=..., including www.google.com/trends/... redirect links) and embedded-chart links (trends.google.com/trends/embed/explore/...?req=...). Trending Now links (trends.google.com/trending?geo=...) are supported too. URL settings override the fields above; they are merged with your search terms.

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

Country, state/region or metro area to analyze. Leave empty for worldwide. Trending Now uses the country part of this location.

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

Time window for the interest data (mode=interest). 'now' ranges return minute-level points; 'today' ranges return day/week points. Choose 'Custom range' to enter exact dates below.

## `customDateRange` (type: `string`):

Only used when 'Time range' = 'Custom range': 'YYYY-MM-DD YYYY-MM-DD' (e.g. '2024-01-01 2024-12-31') or 'YYYY-MM-DDTHH YYYY-MM-DDTHH' for hourly granularity.

## `category` (type: `string`):

Google Trends category filter (mode=interest). 0 = All categories.

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

Which Google surface to query (mode=interest). Web Search is the default.

## `geoResolution` (type: `string`):

Breakdown level for 'interest by region' (mode=interest). Auto lets Google pick the right level for the location; other levels are applied when the location supports them.

## `trendingHours` (type: `string`):

How far back the Trending Now list goes (mode=trending).

## `trendingCategory` (type: `string`):

Filter the Trending Now list to one of Google's trending categories (mode=trending).

## `includeTrendingNews` (type: `boolean`):

Attach news headlines, links and sources from Google's Trending RSS feed to trending items whose titles it covers (about ten highlighted stories per country, anywhere in the list).

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

Maximum dataset records per run: each interest row counts as one record, each trending item as one record. Remaining work stops once the limit is reached.

## Actor input object example

```json
{
  "mode": "interest",
  "searchTerms": [
    "tesla"
  ],
  "compareMode": false,
  "geo": "US",
  "timeRange": "today 12-m",
  "category": "0",
  "searchType": "",
  "geoResolution": "",
  "trendingHours": "4",
  "trendingCategory": "all",
  "includeTrendingNews": true,
  "maxItems": 3
}
```

# Actor output Schema

## `trends` (type: `string`):

Dataset containing all scraped Google Trends 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 = {
    "mode": "interest",
    "searchTerms": [
        "tesla"
    ],
    "compareMode": false,
    "geo": "US",
    "timeRange": "today 12-m",
    "category": "0",
    "searchType": "",
    "geoResolution": "",
    "trendingHours": "4",
    "trendingCategory": "all",
    "includeTrendingNews": false,
    "maxItems": 3
};

// Run the Actor and wait for it to finish
const run = await client.actor("vexaloom-labs/google-trends-interest-and-related-query-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 = {
    "mode": "interest",
    "searchTerms": ["tesla"],
    "compareMode": False,
    "geo": "US",
    "timeRange": "today 12-m",
    "category": "0",
    "searchType": "",
    "geoResolution": "",
    "trendingHours": "4",
    "trendingCategory": "all",
    "includeTrendingNews": False,
    "maxItems": 3,
}

# Run the Actor and wait for it to finish
run = client.actor("vexaloom-labs/google-trends-interest-and-related-query-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 '{
  "mode": "interest",
  "searchTerms": [
    "tesla"
  ],
  "compareMode": false,
  "geo": "US",
  "timeRange": "today 12-m",
  "category": "0",
  "searchType": "",
  "geoResolution": "",
  "trendingHours": "4",
  "trendingCategory": "all",
  "includeTrendingNews": false,
  "maxItems": 3
}' |
apify call vexaloom-labs/google-trends-interest-and-related-query-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,vexaloom-labs/google-trends-interest-and-related-query-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/NEZGbjPfvDGos0EFq/builds/nDRCeMAwxTkbOpvlo/openapi.json