# Google Trends Scraper (`mvkdata/google-trends-fast`) Actor

Google Trends API alternative: scrape interest over time, interest by region and city, related queries and related topics for any search terms or Google Trends URLs. Fast plain HTTP, no browser: seconds per term, pay only per result.

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

## Pricing

from $0.50 / 1,000 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 & API (fast, no browser)

Get Google Trends data for any number of search terms or Google Trends URLs: **interest over time, interest by region and city, related queries (top and rising) and related topics**, plus side-by-side comparisons of up to 5 terms.

It talks to Google Trends' own data endpoints directly instead of driving a browser, so a term takes **seconds instead of minutes**. Items that Google blocks are retried on fresh IPs (and on residential IPs if needed) until they deliver, and **you only pay for items that actually come back with data**.

### What you get per search term

| Field | What it is |
|---|---|
| `interestOverTime_timelineData` | Search interest 0-100 for each time step (hour, day, week or month depending on the range) |
| `interestOverTime_averages` | Average interest per term (when comparing terms) |
| `interestBySubregion` | Interest by country (worldwide) or by state/region (inside a country) |
| `interestByCity` | Interest by city (when a country is set and Google has city data) |
| `relatedQueries_top` / `relatedQueries_rising` | Most popular and fastest-rising related searches |
| `relatedTopics_top` / `relatedTopics_rising` | Related topics (Google often returns these empty for automated access; filled when it gives them) |
| `byTerm` | When comparing terms: region map and related queries/topics for each term separately |
| `terms`, `geo`, `timeRange`, `category`, `property`, `scrapedAt` | The query the item belongs to |

Field names match the most used Google Trends actor in the Store, so you can switch without changing your pipeline.

### How to use

- **Search terms**: one per line. Each line gives one dataset item.
- **Compare terms**: switch it on and write up to 5 terms in one line separated by commas (`iphone, samsung`). They are measured on the same 0-100 scale.
- **Google Trends URLs**: paste any `trends.google.com/trends/explore?...` link; its terms, country/region, dates, category and property are used as-is (regions like `US-CA` work here).
- **Country, time range, category, Google property** (web, images, news, YouTube, Shopping), **custom date range** (`2024-01-01 2024-06-30`) and **language** of names.

#### Example input

```json
{
  "searchTerms": ["chatgpt, gemini, claude", "bitcoin, ethereum"],
  "isMultiple": true,
  "geo": "US",
  "timeRange": "today 3-m"
}
```

### Use it as a Google Trends API

There is no official Google Trends API, so this actor works as one: call it from your code and get JSON back in one request.

```bash
curl -X POST "https://api.apify.com/v2/acts/mvkdata~google-trends-fast/run-sync-get-dataset-items?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"searchTerms": ["bitcoin", "ethereum"], "timeRange": "today 12-m", "geo": "US"}'
```

It also works from the Apify Python and JavaScript clients, Make, Zapier, n8n and as an MCP tool for AI agents.

### Pricing

Pay per result: you are charged only for dataset items that contain data. Failed terms are not charged; they are listed in the run's key-value store record `FAILED_QUERIES`.

### Reliability

- Each term has its own retry budget (12 by default); every retry uses a new IP.
- With the default Apify Proxy, a term Google blocks three times moves to residential IPs (switch off with *Residential fallback*).
- The run's status line shows results, failures and retries live.

### FAQ

**Why are related topics sometimes empty?** Google decides per request whether to return them and often leaves them out for automated access; related queries are almost always present.

**Why only a few cities?** Google only reports cities with enough search volume; small countries and niche terms often have none.

**Is scraping Google Trends legal?** The data is public and aggregated (no personal data). Check your own use case and local rules.

# Actor input Schema

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

One dataset item per term. With 'Compare terms' on, put up to 5 comma-separated terms in one line to compare them on one chart.

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

Treat each line as a comparison of up to 5 comma-separated terms (like 'iphone, samsung'). Output adds a byTerm section with per-term maps and related queries.

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

Paste trends.google.com/trends/explore URLs; their terms, geo, time, category and property are used as-is.

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

Region codes like US-CA also work via a Google Trends URL.

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

Period to fetch. Shorter periods give finer time steps (hourly for the past day/week).

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

Overrides Time range. Format 'YYYY-MM-DD YYYY-MM-DD', e.g. '2024-01-01 2024-06-30'.

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

Limit the search interest to one Google Trends category.

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

Which Google search to measure: web, images, news, YouTube or Shopping.

## `includeCities` (type: `boolean`):

Extra request per item; only when a country is set.

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

Language for topic names and region names (hl), e.g. en-US, de, fi.

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

0 = no limit.

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

How many items run in parallel.

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

Max retries per item

## `residentialFallback` (type: `boolean`):

With the default Apify Proxy, an item Google blocks 3 times is retried on residential IPs so it still delivers. Turn off to stay on datacenter IPs only.

## `proxy` (type: `object`):

Apify Proxy is on by default; blocked requests rotate to a new IP automatically.

## Actor input object example

```json
{
  "searchTerms": [
    "web scraping",
    "chatgpt"
  ],
  "isMultiple": false,
  "geo": "",
  "timeRange": "today 12-m",
  "category": "0",
  "property": "",
  "includeCities": true,
  "language": "en-US",
  "maxItems": 0,
  "maxConcurrency": 5,
  "maxRequestRetries": 12,
  "residentialFallback": true,
  "proxy": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

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

No description

## `results` (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",
        "chatgpt"
    ],
    "proxy": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("mvkdata/google-trends-fast").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",
        "chatgpt",
    ],
    "proxy": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("mvkdata/google-trends-fast").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",
    "chatgpt"
  ],
  "proxy": {
    "useApifyProxy": true
  }
}' |
apify call mvkdata/google-trends-fast --silent --output-dataset

```

## MCP server setup

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

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/bt4II5qaNXMDvV7Nf/builds/G6r6xMoSDEV2AfHfq/openapi.json