# Google Trends API — Interest Over Time, Regions & Related (`saliga/google-trends`) Actor

Google Trends for hundreds of keywords and up to 20 countries in one run: interest over time with trend summary, interest by region, and top and rising related queries and topics. Web, News, YouTube, Images and Shopping.

- **URL**: https://apify.com/saliga/google-trends.md
- **Developed by:** [Salih Küçükkayış](https://apify.com/saliga) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $6.00 / 1,000 queries

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 for hundreds of keywords and up to 20 countries in one run: **interest over time with a ready-made trend summary, interest by region, and top and rising related queries and topics.** Web search, News, YouTube, Images and Google Shopping. No browser, no blocked requests, no CAPTCHAs.

**$6 per 1,000 queries.** A query is one keyword (or up to 5 compared keywords) in one place and time range, with all the extras you ask for. Comparing 5 keywords at once is one query, so it works out at $1.20 per 1,000 keywords. Keywords with too little data, and queries that fail or are not ready in time, are free. No subscription, and platform usage is included. (Plus a tiny $0.00005 start fee per run.)

### What you get

- **Interest over time** on Google's 0-100 scale, point by point, as in the Google Trends chart.
- **A summary you can sort by:** average, latest value, peak and peak date, and the change from the first quarter of the period to the last, with `rising`, `falling` or `flat`. The last point Google marks as incomplete is kept but left out of the summary.
- **Compare mode:** up to 5 keywords on one shared scale, like the compare view on the Google Trends site.
- **Interest by region** (states or countries) and **related queries and topics**, top and rising, at no extra cost.
- **Many places in one run:** worldwide plus up to 20 countries.
- **Any period:** past hour to 2004 to now, or your own dates.
- **Bring keywords from anywhere:** paste them, link a CSV, or point to a [Keyword Research](https://apify.com/saliga/keyword-research) dataset.

### Typical uses

- **Spot rising topics** before you write: rising related queries for your main keywords.
- **Seasonality:** five years of weekly interest to plan campaigns.
- **Brand vs. brand:** compare mode for you and four competitors in ten markets.
- **Where to launch:** interest by region for a product category.

### Input

```json
{
  "keywords": ["chatgpt", "claude", "gemini"],
  "mode": "compare",
  "countries": ["worldwide", "US", "DE"],
  "timeRange": "past_12_months",
  "includeRegions": true
}
```

| Field | Meaning |
|---|---|
| `keywords` | Search terms, up to 100 characters. Symbols Google Trends refuses (`- + ! : * ( )` and the like) become spaces, with a note. |
| `mode` | `separate` (default): each keyword on its own scale. `compare`: groups of up to 5 on one scale. |
| `countries` | Up to 20: codes, names, or `worldwide`. Default worldwide. |
| `timeRange` | `past_hour`, `past_4_hours`, `past_day`, `past_7_days`, `past_30_days`, `past_90_days`, `past_12_months` (default), `past_5_years`, `all`. |
| `dateFrom`, `dateTo` | Your own period instead, as `2024-01-31`. |
| `searchType` | `web` (default), `news`, `youtube`, `images`, `froogle` (Google Shopping). |
| `includeRegions` | Add interest by region rows. |
| `includeRelated` | Add related queries and topics (separate mode). |
| `maxWaitMinutes` | How long to wait for queued queries. Default 60. |
| `keywordsUrl`, `datasetId`, `keywordField` | Other ways to pass keywords. |

### Output

`interest`, one per keyword and place:

```json
{
  "type": "interest",
  "keyword": "claude",
  "comparedWith": [],
  "country": "US",
  "searchType": "web",
  "period": "past_12_months",
  "average": 54.7,
  "latest": 65,
  "peakDate": "2026-05-24",
  "changePct": 223.5,
  "trendDirection": "rising",
  "points": ["… one { date, value } per point, oldest first"],
  "status": "ok",
  "charged": true
}
```

A real row from a run on 17 October 2026 (`chatgpt`, `claude` and `gemini`, worldwide and United States: six queries, $0.036). In compare mode, `comparedWith` lists the other keywords on the same scale.

`region`: `keyword`, `region`, `regionId`, `value` (0-100). `related_query`: `list` (`top` or `rising`), `query`, `value`. `related_topic`: `list`, `topic`, `topicType`, `topicId`, `value`.

`country` is `Worldwide` for worldwide queries. Rows that cost nothing: `no_data`, `invalid_keyword`, `input_error`, `note` (a keyword was cleaned), `spending_limit`, `free_plan_limit`, `not_ready`, `throttled` and `provider_error`.

### What it costs

| Run | Price |
|---|---|
| 100 keywords, worldwide | $0.60 |
| 100 keywords in 10 countries | $6.00 |
| 1,000 keywords compared in groups of 5, worldwide | $1.20 |
| 20 keywords with regions and related, 5 countries | $0.60 |

### How long it takes

Queries go through a queue: most finish within a few minutes, some take longer at busy times. The run collects them as they finish and stops waiting after `maxWaitMinutes`; anything not ready by then is listed and not charged.

### Apify free plan

Every query costs us real money at the data source, and free-plan runs earn nothing. So on the Apify free plan this Actor gives 3 queries a day. The rest comes back as uncharged `free_plan_limit` rows. Any paid Apify plan has no such limits.

### Good to know

- Google Trends values are relative: 100 is the peak interest for that keyword (or group) in that place and period. Values from separate queries are not on the same scale; use compare mode for that.
- Data comes from a licensed data provider. This Actor is not affiliated with, endorsed by or sponsored by Google; "Google" and "Google Trends" are trademarks of Google LLC.
- A run that is moved to another server continues where it stopped, collecting the queries it already queued. Nothing is charged twice.
- Pricing: one `trends-query` charge per delivered query, plus $0.00005 when a run starts.
- Questions or a missing feature: open an issue on the Actor page.

### Next steps

- **Search volume behind the trend:** [Keyword Search Volume](https://apify.com/saliga/keyword-search-volume) gives Google Ads monthly searches for the same keywords.
- **More keywords around a rising topic:** [Keyword Research](https://apify.com/saliga/keyword-research).
- **Who ranks for it:** [Google SERP Rank Tracker](https://apify.com/saliga/serp-rank-tracker).

### More from this developer

- [Keyword Research](https://apify.com/saliga/keyword-research): keyword ideas, suggestions and related keywords with volume, difficulty and search intent, $2 per 1,000 keywords.
- [Competitor Keywords](https://apify.com/saliga/competitor-keywords): every Google keyword a domain or page ranks for, and its organic competitors, $2 per 1,000 rows.
- [Domain SEO Overview](https://apify.com/saliga/domain-seo-overview): organic keywords, estimated traffic and top-10 rankings for thousands of domains, $5 per 1,000 domains.
- [Google SERP Rank Tracker](https://apify.com/saliga/serp-rank-tracker): Google positions for your keywords by country and device, with AI Overview checks, $2 per 1,000 result pages.
- [Keyword Search Volume](https://apify.com/saliga/keyword-search-volume): Google Ads search volume, CPC and up to 48 months of trend for a keyword list, $2 per 1,000 keywords.
- [Sitemap Extractor](https://apify.com/saliga/sitemap-extractor): every URL a website lists in its sitemaps, with lastmod, images and hreflang, $0.25 per 1,000 URLs.
- [Broken Link Checker](https://apify.com/saliga/broken-link-checker): crawl a site and find broken links and images, with the pages they are on.
- [Tech Stack Detector](https://apify.com/saliga/tech-stack-detector): which CMS, ecommerce platform, analytics and hosting a website uses, $1.50 per 1,000 websites.
- [Website Screenshot + Change Detection](https://apify.com/saliga/website-screenshot-change-detection): screenshots of many URLs on desktop and mobile, with visual change detection between runs.
- [Dataset Merge & Dedup Datasets](https://apify.com/saliga/dataset-merge-dedupe): merge, dedupe and filter the results of several runs into one dataset.

# Actor input Schema

## `keywords` (type: `array`):

Search terms, up to 100 characters each. Symbols Google Trends does not accept (such as - + ! :) are turned into spaces.

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

Separate: each keyword on its own 0-100 scale (and related queries are available). Compare: groups of up to 5 keywords on one shared scale, as in the Google Trends compare view.

## `countries` (type: `array`):

Up to 20: two-letter codes (US, GB, DE), names, or "worldwide". Default worldwide.

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

Ignored when dates are set below.

## `dateFrom` (type: `string`):

Optional, as 2024-01-31. From 2004-01-01 (2008 for News, YouTube, Images and Shopping).

## `dateTo` (type: `string`):

Optional, as 2024-12-31. Default today.

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

Which Google property the interest comes from: web search, News, YouTube, Images or Google Shopping.

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

Add one row per region (state or country) with its 0-100 interest. No extra cost.

## `includeRelated` (type: `boolean`):

Add the top and rising related queries and topics for each keyword (separate mode only). No extra cost.

## `maxWaitMinutes` (type: `integer`):

Queries run in a queue and usually finish in a few minutes. Queries not ready in this time are not charged.

## `keywordsUrl` (type: `string`):

Link to a text file (one keyword per line), a CSV with a keyword column, or a JSON list.

## `datasetId` (type: `string`):

Use the output of another Actor, such as Keyword Research.

## `keywordField` (type: `string`):

The column or field that holds the keyword.

## Actor input object example

```json
{
  "keywords": [
    "chatgpt",
    "claude",
    "gemini"
  ],
  "mode": "separate",
  "countries": [
    "worldwide",
    "US"
  ],
  "timeRange": "past_12_months",
  "searchType": "web",
  "includeRegions": false,
  "includeRelated": false,
  "maxWaitMinutes": 60,
  "keywordField": "keyword"
}
```

# Actor output Schema

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

One row per keyword and place: summary and weekly or daily points.

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

Rows of type "region".

## `related` (type: `string`):

Rows of type "related_query" and "related_topic".

## `fullResults` (type: `string`):

Every row and field.

## `summary` (type: `string`):

Counts for the run and why it stopped.

# 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 = {
    "keywords": [
        "chatgpt",
        "claude",
        "gemini"
    ],
    "countries": [
        "worldwide",
        "US"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("saliga/google-trends").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 = {
    "keywords": [
        "chatgpt",
        "claude",
        "gemini",
    ],
    "countries": [
        "worldwide",
        "US",
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("saliga/google-trends").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 '{
  "keywords": [
    "chatgpt",
    "claude",
    "gemini"
  ],
  "countries": [
    "worldwide",
    "US"
  ]
}' |
apify call saliga/google-trends --silent --output-dataset

```

## MCP server setup

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

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/tTCbcdheMHNey3Qng/builds/Fm6iQ75sgS6A6O3ey/openapi.json