# Google Trends API & Scraper (`sourcedirect/google-trends-api`) Actor

Google Trends data in clean JSON: interest over time, interest by region, related queries, keyword comparisons (up to 5) and Trending Now. Batch keywords, no browser, built for AI agents and analysts.

- **URL**: https://apify.com/sourcedirect/google-trends-api.md
- **Developed by:** [Kurt Landman](https://apify.com/sourcedirect) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 search-term reports

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?

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 API & Scraper

Get Google Trends data as clean JSON for any number of keywords:

- **Interest over time**, with a ready-made summary: average, peak, latest value, and whether interest is rising or falling.
- **Interest by region**, by country, region, city or US metro area.
- **Related queries**, both top and rising, including "Breakout" searches.
- **Keyword comparisons** on one shared scale, up to 5 terms at a time.
- **Trending Now**: what people are searching for right now, with search volume, growth and categories, for any country.

It talks directly to Google Trends' own data endpoints, with no browser. That keeps it fast and cheap and lets it handle large batches. Each keyword returns one complete report.

### Who uses it

- **SEO and content teams:** check whether a topic is growing before writing about it, and find rising related searches.
- **Marketers and e-commerce sellers:** compare products, brands or markets, and spot seasonality.
- **Analysts and researchers:** pull consistent timelines for many keywords in one run.
- **AI agents:** one call answers "is X trending?", with a compact `summary` that needs no further math.

### What you get for each search term

| Field | What it is |
|---|---|
| `summary` | `averageInterest`, `latestInterest`, `peak`, `low`, `changePercent`, and `direction` (`rising` / `falling` / `stable`) |
| `interestOverTime` | One point per hour, day, week or month: `date`, `value` (0–100), `isPartial` |
| `interestByRegion` | Regions sorted by interest: `geoName`, `geoCode`, `value` (0–100) |
| `relatedQueries` | `top` and `rising` lists. Rising values are % growth; `isBreakout` means more than +5,000% |
| `trendsUrl` | The same view on trends.google.com |
| `warnings` | Any section Google did not return, with the reason |

Trending Now items include:

- `title` and `searchVolume` (e.g. 200,000)
- `increasePercent`
- `startedAt`, `endedAt` and `isActive`
- `categories`
- `trendBreakdown`, the related searches behind the trend

### How to use it

1. Enter one or more **Search terms**, e.g. `chatgpt`, `claude`, `gemini`.
2. Pick a **Time range** and a **Location** (`US`, `GB`, `US-CA`, or empty for worldwide).
3. Optional:
   - Turn on **Compare terms** to put up to 5 terms on one scale.
   - Add countries under **Trending Now**.
4. Click **Start** and download the results as JSON, CSV or Excel, or read them via the API.

#### Input examples

One keyword, past 12 months, United States:

```json
{ "searchTerms": ["web scraping"], "geo": "US", "timeRange": "today 12-m" }
```

Compare three keywords worldwide over 90 days:

```json
{ "searchTerms": ["chatgpt", "claude", "gemini"], "compareTerms": true, "timeRange": "today 3-m" }
```

Today's trending searches in the US and UK, technology only:

```json
{ "trendingNowGeos": ["US", "GB"], "trendingNowHours": "24", "trendingNowCategory": "18" }
```

Exact dates, YouTube searches, regional breakdown by US metro area:

```json
{ "searchTerms": ["iphone 17"], "geo": "US", "customTimeRange": "2025-09-01 2026-09-30", "searchProperty": "youtube", "regionResolution": "DMA" }
```

#### Output example

This is a real result, shortened to one entry per list. It comes from comparing `web scraping` with `chatgpt` in the US over 90 days.

```json
{
  "type": "interestReport",
  "searchTerm": "chatgpt",
  "comparedWith": ["web scraping"],
  "geo": "US",
  "timeRange": "today 3-m",
  "categoryName": "All categories",
  "resolution": "DAY",
  "summary": {
    "averageInterest": 65.2,
    "latestInterest": 83,
    "latestDate": "2026-09-30",
    "peak": { "date": "2026-09-03", "value": 100 },
    "changePercent": 11.9,
    "direction": "stable"
  },
  "interestOverTime": [{ "date": "2026-07-01", "timestamp": 1782864000, "value": 67, "isPartial": false }],
  "interestByRegion": [{ "geoCode": "US-CA", "geoName": "California", "value": 100, "hasData": true }],
  "relatedQueries": {
    "top": [{ "query": "chatgpt ai", "value": 100, "formattedValue": "100", "isBreakout": false, "trendsUrl": "https://trends.google.com/trends/explore?q=chatgpt+ai&date=today+3-m&geo=US" }],
    "rising": [{ "query": "sam altman chatgpt water usage", "value": 7750, "formattedValue": "Breakout", "isBreakout": true, "trendsUrl": "https://trends.google.com/trends/explore?q=sam+altman+chatgpt+water+usage&date=today+3-m&geo=US" }]
  },
  "trendsUrl": "https://trends.google.com/trends/explore?date=today+3-m&geo=US&q=web+scraping%2Cchatgpt&hl=en-US",
  "warnings": [],
  "scrapedAt": "2026-10-01T03:43:59.067Z"
}
```

The dataset also has ready-made table views: **Search-term reports**, **Interest over time** (one row per period), **Interest by region**, and **Trending Now**.

### Pricing

You pay only for results. There are no platform-usage charges on top and no fee per run.

| Event | Price |
|---|---|
| Search-term report (one keyword, all sections you selected) | **$0.003** |
| Trending Now search (one row) | **$0.001** |

Examples: 100 keywords cost $0.30, and the top 100 trending searches for one country cost $0.10.

You are **never charged for failures**. A term that Google does not answer, even after retries, is returned as an item with `"type": "error"` and a reason, at no cost. If you set a maximum cost for a run, the Actor stops cleanly when it is reached.

### Using it from AI agents (MCP)

This Actor works with the [Apify MCP server](https://mcp.apify.com), so it runs from Claude, ChatGPT, Cursor or any MCP client. Agents can also pay per call without an Apify account through Apify's agentic payments.

Good prompts for an agent:

- "Use Google Trends to tell me whether interest in *solar panels* in Germany is rising, and list rising related queries."
- "Compare *Notion*, *Obsidian* and *Logseq* worldwide over the past 5 years and say which is growing fastest."
- "What is trending in the US right now in Technology?"

Tips for agents:

- Read `summary.direction` and `summary.changePercent` first. They answer "is it growing?" without parsing the timeline.
- Batch many keywords in one call with `searchTerms`.
- Use `compareTerms: true` only when you need the terms on one scale.

### How Google Trends numbers work

- Values are **relative, 0–100**. 100 is the highest point in your request (time range, location and compared terms), not an absolute search count.
- **Comparing changes the scale.** A small term next to a very popular one can show 0 everywhere. The report then adds a warning; run it on its own to see its curve.
- **Time range sets the granularity** (the `resolution` field):

  | Time range | Spacing of points |
  |---|---|
  | Past hour, past 4 hours | per minute |
  | Past day | every 8 minutes |
  | Past 7 days | hourly |
  | Past 30 or 90 days | daily |
  | Past 12 months or 5 years | weekly |
  | 2004 – present | monthly |

  Google picks the spacing of custom date ranges from their length. For example, 3 months is daily and 6 years is monthly.
- **The last point can be partial** (`isPartial: true`) because the period isn't over yet. The summary ignores it.
- **Rising queries** show growth versus the previous period. "Breakout" means more than +5,000%.

### Reliability

- Requests go through residential proxies, with a fresh session and exit IP whenever Google rate-limits one.
- Blocked jobs retry automatically, up to 6 times.
- If one section (for example regions) fails while the others succeed, you still get the report, and the problem is listed in `warnings`.

### Limitations

- **Related topics** are optional and off by default. Google currently often returns an empty topics list to automated requests; when that happens the report says so in `warnings`.
- Google offers related topics only for single terms, not comparisons. Region breakdowns are available only where Google has enough data.
- Google Trends data is sampled, so repeated requests can differ slightly. This is how Google Trends works.

### FAQ

**Is there an official Google Trends API?**
Google announced an alpha API in July 2025, but access is by application only. This Actor works today, with no application.

**Is it legal to collect Google Trends data?**
This Actor reads publicly available, aggregated search-interest data and no personal data. Use it in line with the laws and terms that apply to you.

**Can I schedule it?**
Yes. Use Apify Schedules to track keywords daily or weekly, and connect the results to Google Sheets, Slack, Zapier, Make or n8n.

**Something not working?**
Open an issue on the **Issues** tab with the run link. We respond quickly.

# Changelog

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

# Actor input Schema

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

Keywords or Google Knowledge Graph topic IDs (like /m/0dl567) to look up. Each term returns one report. Up to 1,000 per run.

## `compareTerms` (type: `boolean`):

On: terms are compared in groups of up to 5 on one shared 0–100 scale, like the Compare view on trends.google.com. Off: every term is scaled on its own.

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

Period to analyze. Shorter ranges return finer data points (hourly or daily); longer ones return weekly or monthly points.

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

Exact dates as "YYYY-MM-DD YYYY-MM-DD", e.g. "2025-01-01 2025-12-31". Overrides the time range above.

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

Two-letter country code (US, GB, DE), region code (US-CA, GB-ENG), or leave empty for worldwide.

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

Google Trends category to narrow searches (0 = all categories). For example 5 = Computers & Electronics, 7 = Finance, 71 = Food & Drink.

## `searchProperty` (type: `string`):

Which Google product the searches come from.

## `includeInterestOverTime` (type: `boolean`):

Timeline of search interest (0–100) plus a summary: average, peak, latest value and whether interest is rising or falling.

## `includeInterestByRegion` (type: `boolean`):

Where the term is most popular, as a 0–100 score per country, region, city or metro area.

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

Level of the regional breakdown. Auto uses Google's default (countries for worldwide, regions inside a country). DMA (metro areas) works for the US only.

## `includeLowSearchVolumeRegions` (type: `boolean`):

Also return regions where Google has too little data (their value is 0).

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

Top and rising searches related to each term. Rising queries show growth in percent, or "Breakout" for more than +5,000%.

## `includeRelatedTopics` (type: `boolean`):

Top and rising related topics. Only for single-term (not compared) queries. Google currently often returns this list empty for automated requests; when that happens the item says so in "warnings".

## `maxRelatedItems` (type: `integer`):

Maximum number of entries in each related queries/topics list.

## `trendingNowGeos` (type: `array`):

Get the searches trending right now (trends.google.com/trending) for these countries, e.g. US, GB, IN. Leave empty to skip.

## `trendingNowHours` (type: `string`):

Show searches that started trending in the past 4, 24 or 48 hours, or 7 days.

## `trendingNowCategory` (type: `string`):

Only return trending searches in this category.

## `trendingNowActiveOnly` (type: `boolean`):

Skip searches whose trend has already ended.

## `trendingNowMaxItems` (type: `integer`):

Upper limit of trending searches returned per country (Google lists up to about 1,200 for 7 days).

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

Language for topic names and Trending Now, as a code like en-US, de or es-MX.

## `timezoneOffset` (type: `integer`):

Offset from UTC in minutes as Google Trends expects it (UTC = 0, US Eastern standard time = 300, Central European time = -60). Affects hourly and daily data.

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

How many terms (or comparison groups) to fetch in parallel, each on its own proxy session.

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

Google Trends rate-limits shared IP addresses quickly. Residential proxies give the most reliable results.

## Actor input object example

```json
{
  "searchTerms": [
    "chatgpt",
    "claude",
    "gemini"
  ],
  "compareTerms": false,
  "timeRange": "today 12-m",
  "geo": "",
  "category": 0,
  "searchProperty": "web",
  "includeInterestOverTime": true,
  "includeInterestByRegion": true,
  "regionResolution": "AUTO",
  "includeLowSearchVolumeRegions": false,
  "includeRelatedQueries": true,
  "includeRelatedTopics": false,
  "maxRelatedItems": 25,
  "trendingNowGeos": [],
  "trendingNowHours": "24",
  "trendingNowCategory": "0",
  "trendingNowActiveOnly": false,
  "trendingNowMaxItems": 100,
  "language": "en-US",
  "timezoneOffset": 0,
  "maxConcurrency": 3,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# Actor output Schema

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

Every item: one search-term report per keyword, plus Trending Now entries and any errors.

## `overview` (type: `string`):

No description

## `timeline` (type: `string`):

No description

## `regions` (type: `string`):

No description

## `trending` (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": [
        "web scraping"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("sourcedirect/google-trends-api").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": ["web scraping"],
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("sourcedirect/google-trends-api").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": [
    "web scraping"
  ],
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}' |
apify call sourcedirect/google-trends-api --silent --output-dataset

```

## MCP server setup

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

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/KVVKiYDQdjNprCEno/builds/7fQI2F8GMMzexJcrK/openapi.json