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

Get Google Trends interest over time, by region, city and metro, related queries and trending searches. 20% cheaper than the leading Google Trends scraper on Free to Gold plans; pay only for data.

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

## Pricing

from $2.40 / 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 search terms (interest over time, interest by region, city and metro, related queries) or today's trending searches. The price is 20% cheaper than the leading Google Trends scraper on Free to Gold plans. You pay only for terms that return data. Failed terms and terms with no data are free.

Built for pytrends users, SEO and content teams, and AI agents (MCP). Use it as a pytrends alternative or a Google Trends API alternative for keyword trends, interest by region and trending searches.

### Pricing

Pay per event. No monthly fee.

| Event | Charged when | Price (depends on your Apify plan) |
|---|---|---|
| Search term result | One search term, or one comparison group, returned data | $0.0048 (Free), $0.004 (Bronze), $0.0032 (Silver), $0.0024 (Gold and higher plans) |
| Trending country | One country in trending mode returned at least one trending search | $0.022 for all plans |

Free Apify plans can use up to $1.00 of this Actor each month. Paid plans have no monthly limit.

### Quick start

Open the Actor in Apify Console, paste one of these inputs and click Start.

One search term, United States, past 3 months:

```json
{
  "searchTerms": ["python"],
  "geo": "US",
  "timeRange": "today 3-m"
}
```

Compare terms. With `isMultiple` each entry is split on commas into one comparison group (up to 5 terms). It costs one search term result per group:

```json
{
  "searchTerms": ["python,java"],
  "isMultiple": true,
  "geo": "US",
  "timeRange": "today 3-m"
}
```

Today's trending searches:

```json
{
  "mode": "trending",
  "trendingGeos": ["US"]
}
```

### Input

| Field | What it does |
|---|---|
| `mode` | `keyword` (default) or `trending` |
| `searchTerms` | Terms to look up |
| `isMultiple` | `true`: each entry is split on commas into one comparison group (up to 5 terms) |
| `startUrls` | Google Trends explore URLs. The `q`, `geo`, `date`, `cat` and `gprop` parameters override the form |
| `timeRange` | `now 1-H`, `now 4-H`, `now 1-d`, `now 7-d`, `today 1-m`, `today 3-m`, `today 5-y`, `all`. Empty = past 12 months |
| `customTimeRange` | `YYYY-MM-DD YYYY-MM-DD`. Overrides `timeRange` |
| `geo` | Two-letter country code such as `US`, or region such as `US-CA`. Empty = worldwide |
| `viewedFrom` | Only `US` or empty is supported |
| `category` | Google Trends category ID. 0 = all |
| `property` | `news`, `images`, `youtube`, `froogle`. Empty = web search |
| `maxItems` | Process only the first N items. 0 = no limit |
| `trendingGeos` | Countries for trending mode (two-letter codes) |

### Output

Keyword mode: one item per search term or comparison group, with the same fields as the leading Google Trends scraper.

- `inputUrlOrTerm`, `searchTerm`
- `interestOverTime_timelineData`, `interestOverTime_averages`
- `interestBySubregion`, `interestByCity`, `interestByMetro` (metro areas: US queries only), `interestBy` (worldwide queries: by country)
- `relatedQueries_top`, `relatedQueries_rising`
- `relatedTopics_top`, `relatedTopics_rising` (always empty, see Limits)

`[]` means this kind of data does not exist for the query (for example metro areas outside the US). `null` means the data should exist but Google did not return it. The run status message names the fields that were `null`.

Trending mode: one item per trending search with `geo`, `title`, `approxTraffic`, `pubDate`, `picture`, `pictureSource` and `news` (`title`, `url`, `source`, `picture`, `snippet`).

Example item (keyword mode, `python`, `US`, `today 3-m`; arrays cut to one or two entries):

```json
{
  "inputUrlOrTerm": "python",
  "searchTerm": "python",
  "interestOverTime_timelineData": [
    {"time": "1786838400", "formattedTime": "Aug 16, 2026", "formattedAxisTime": "Aug 16", "value": [44], "hasData": [true], "formattedValue": ["44"]},
    {"time": "1786924800", "formattedTime": "Aug 17, 2026", "formattedAxisTime": "Aug 17", "value": [57], "hasData": [true], "formattedValue": ["57"]}
  ],
  "interestOverTime_averages": [],
  "interestBySubregion": [
    {"geoCode": "US-KS", "geoName": "Kansas", "value": [100], "formattedValue": ["100"], "maxValueIndex": 0, "hasData": [true]}
  ],
  "interestByCity": [
    {"coordinates": {"lat": 38.3312379, "lng": -77.0510857}, "geoName": "Dahlgren", "value": [0], "formattedValue": [""], "maxValueIndex": 0, "hasData": [false]}
  ],
  "interestByMetro": [
    {"geoCode": "582", "geoName": "Lafayette IN", "value": [100], "formattedValue": ["100"], "maxValueIndex": 0, "hasData": [true]}
  ],
  "relatedTopics_top": [],
  "relatedTopics_rising": [],
  "relatedQueries_top": [
    {"query": "what is python", "value": 100, "formattedValue": "100", "hasData": true, "link": "/trends/explore?q=what+is+python&date=today+3-m&geo=US"},
    {"query": "ball python", "value": 78, "formattedValue": "78", "hasData": true, "link": "/trends/explore?q=ball+python&date=today+3-m&geo=US"}
  ],
  "relatedQueries_rising": [
    {"query": "best time to visit maldives", "value": 6350, "formattedValue": "Breakout", "link": "/trends/explore?q=best+time+to+visit+maldives&date=today+3-m&geo=US"}
  ],
  "interestBy": []
}
```

Example item (trending mode, `US`; one of 10 items, `news` cut to one entry):

```json
{
  "geo": "US",
  "title": "golden knights",
  "approxTraffic": "500+",
  "pubDate": "Sun, 15 Nov 2026 19:00:00 -0800",
  "picture": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQcPGooAaShpdcyUb3pOhdThjQadoDBlGYOD78EaQQv6jSOb0I_PGDHUWgnbtA",
  "pictureSource": "CBS Sports",
  "news": [
    {"title": "Golden Knights' Carter Hart: Between pipes against Vancouver", "url": "https://www.cbssports.com/fantasy/hockey/news/golden-knights-carter-hart-between-pipes-against-vancouver/", "source": "CBS Sports", "picture": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQcPGooAaShpdcyUb3pOhdThjQadoDBlGYOD78EaQQv6jSOb0I_PGDHUWgnbtA", "snippet": ""}
  ]
}
```

You can export the dataset from Apify as CSV, JSON or Excel.

### Use it as an API or MCP tool

Call the Actor over the Apify API. This request waits for the run and returns the dataset items:

```bash
curl -X POST "https://api.apify.com/v2/acts/krammer~google-trends-scraper/run-sync-get-dataset-items" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"searchTerms": ["python"], "geo": "US", "timeRange": "today 3-m"}'
```

AI agents such as Claude and Cursor can call this Actor as a tool through the Apify MCP server. Use it to get keyword trends inside an agent workflow.

### Replacing pytrends

| pytrends | This Actor |
|---|---|
| `build_payload(kw_list=[...], geo=, timeframe=, cat=, gprop=)` | `searchTerms`, `geo`, `timeRange` or `customTimeRange`, `category`, `property` |
| `interest_over_time()` | `interestOverTime_timelineData` |
| `interest_by_region()` | `interestBySubregion` (with `geo`), `interestBy` (worldwide), `interestByCity`, `interestByMetro` |
| `related_queries()` | `relatedQueries_top`, `relatedQueries_rising` |
| `trending_searches()` / `realtime_trending_searches()` | `mode` = `trending` with `trendingGeos` |

Python example with `apify-client` and pandas:

```python
import pandas as pd
from apify_client import ApifyClient

client = ApifyClient("<APIFY_TOKEN>")
run = client.actor("krammer/google-trends-scraper").call(
    run_input={"searchTerms": ["python"], "geo": "US", "timeRange": "today 3-m"}
)
item = next(iter(client.dataset(run.default_dataset_id).iterate_items()))
df = pd.DataFrame(
    [
        {"date": p["formattedTime"], "interest": p["value"][0]}
        for p in item["interestOverTime_timelineData"]
    ]
)
print(df.tail())
```

### Switching from the leading Google Trends scraper

- Input field names and output field names are the same, so you can switch without changing your code.
- Not supported: `spreadsheetId` (put the terms in `searchTerms` instead). `viewedFrom` supports only US.
- Related topics are not provided. The fields `relatedTopics_top` and `relatedTopics_rising` are kept as empty arrays so existing code keeps working.
- For a comparison group, related queries come from the first term in the group (the same as the leading scraper).

### Limits

- Related topics are not available. The fields stay in the output as empty arrays so that the item shape matches other scrapers.
- `viewedFrom` supports only US.
- Free plan: $1.00 per month.
- Each search term takes about 8 seconds. The default run timeout is 300 seconds, which is about 30 terms. Raise the run timeout for more terms. When time runs out the Actor stops before sending the next request, delivers what it has, and charges only for delivered items.
- One run handles at most 1,000 items.

### More data than the leading scraper

- Worldwide queries (`geo` empty) also return `interestByCity` (about 200 cities). The leading scraper returns an empty array there.
- Trending searches mode.
- `property` for news, image, YouTube and shopping search.

### FAQ

**Is this a Google Trends API?**
It is not the official Google API. It returns the same data as the Google Trends website, as JSON, through the Apify API.

**Is it a SerpApi Google Trends alternative?**
Yes. You pay per search term. There is no monthly fee.

**What happens when Google limits requests?**
The run stops. Items that were not processed are not charged. Try again in about 10 minutes.

**Why are some fields null?**
`null` means Google did not return that data. `[]` means that kind of data does not exist for the query, for example states for a worldwide query.

**How many terms per run?**
Each term takes about 8 seconds. The default timeout of 300 seconds fits about 30 terms. Raise the run timeout for more.

# Actor input Schema

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

Use this field when the user wants to choose between search term data and trending searches. `keyword` returns trends data for search terms; `trending` returns today's trending searches for the countries in `trendingGeos`.

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

Use this field when the user names the topics or keywords to look up (keyword mode). Required in keyword mode unless `startUrls` is set. Empty entries are dropped.

## `isMultiple` (type: `boolean`):

Use this field when the user wants to compare several terms in one chart. When true, each search term is split on commas into one comparison group of up to 5 terms, for example `python,java`. A group counts as one item.

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

Use this field when the user gives Google Trends explore URLs (trends.google.com/trends/explore). The q, geo, date, cat and gprop parameters in the URL override the form fields. A q with commas is a comparison group.

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

Use this field when the user names a time range. Empty means the past 12 months.

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

Use this field when the user gives exact dates. Format: `YYYY-MM-DD YYYY-MM-DD` (start and end). When set, it overrides `timeRange`.

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

Use this field when the user names a country or region. Two-letter country code such as `US`, or a region code such as `US-CA`. Empty means worldwide.

## `viewedFrom` (type: `string`):

Use this field only for compatibility with other Google Trends scrapers. Only `US` or empty is supported; any other value fails the run.

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

Use this field when the user names a Google Trends category. Numeric category ID. 0 means all categories.

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

Use this field when the user wants data from one Google service instead of web search.

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

Use this field when the user wants to cap the run. Only the first N items (terms, comparison groups or countries) are processed. 0 means no limit.

## `trendingGeos` (type: `array`):

Use this field when mode is `trending`. Two-letter country codes such as `US`. Each country is one charged item.

## Actor input object example

```json
{
  "mode": "keyword",
  "searchTerms": [
    "webscraping"
  ],
  "isMultiple": false,
  "timeRange": "",
  "geo": "",
  "viewedFrom": "",
  "category": 0,
  "property": "",
  "maxItems": 0,
  "trendingGeos": [
    "US"
  ]
}
```

# Actor output Schema

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

One item per search term (or comparison group) in keyword mode; one item per trending search in trending mode.

## `runSummary` (type: `string`):

Run outcome, per-item status and charged events.

# 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": [
        "webscraping"
    ],
    "trendingGeos": [
        "US"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("krammer/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": ["webscraping"],
    "trendingGeos": ["US"],
}

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

```

## MCP server setup

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