# Google Trends API (`brii3343/google-trends-api`) Actor

Fast Google Trends API without a browser: interest over time, interest by region, related queries and trending searches for any country. Compare unlimited terms on one shared 0-100 scale. Pay only for results. Spreadsheet-ready output.

- **URL**: https://apify.com/brii3343/google-trends-api.md
- **Developed by:** [Brian Gastaldelli](https://apify.com/brii3343) (community)
- **Categories:** SEO tools, Marketing, News
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 keyword results

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 — fast, no browser, unlimited comparisons

Get Google Trends data for hundreds of search terms in minutes: **interest over time**, **interest by region**
(countries, regions, cities, US metro areas), **related queries** (top and rising) and **trending searches now**
for any country.

This Actor talks to Google Trends directly over HTTP, without launching a browser. That makes it fast, light
and cheap, and it paces its requests and rotates sessions so Google's rate limits don't break your run.

### Why this Actor

- **Compare any number of terms on one scale.** Google Trends compares at most 5 terms at a time, and every
  chart has its own 0-100 scale, so numbers from different charts can't be compared. In **Compare** mode this
  Actor bridges groups of 5 with a shared anchor term and puts *all* your terms on the same 0-100 scale.
- **You pay only for results.** A term that fails after all retries is returned with the reason and is not charged.
  No fee per run.
- **Spreadsheet-ready output.** Choose *Rows* to get one flat row per data point, ready for Excel, Google Sheets
  or a database. Or keep *Nested* to get one item per term with everything inside.
- **Everything Google Trends shows**: any country or region, any time range (past hour to 2004-present, or custom
  dates), categories, and Web, Image, News, Shopping or YouTube search.

### What you can use it for

- **SEO and content planning**: find rising queries before they peak, pick the keyword people actually search.
- **Market and product research**: compare brands, products or ideas across countries and seasons.
- **E-commerce**: spot seasonal demand and trending products with Google Shopping data.
- **Finance and data science**: build time series of public interest for models and dashboards.
- **AI agents**: call it from your agent through the Apify API or MCP to answer "is this growing?" questions.

### Modes

| Mode | What you get |
|---|---|
| Keywords | One item per term, on its own 0-100 scale: interest over time, average, interest by region, related queries, link to the same chart on Google Trends. |
| Compare | One item per term, all terms on one shared 0-100 scale (unlimited terms), with a precision flag for each term. |
| Trending now | Today's trending searches for each country you list, with approximate traffic and news articles. |

### Input example

```json
{
  "mode": "keywords",
  "searchTerms": ["coffee", "matcha", "cold brew"],
  "geo": "US",
  "timeRange": "today 12-m",
  "interestOverTime": true,
  "interestByRegion": true,
  "relatedQueries": true
}
```

### Output example (Keywords mode, real run, lists shortened)

```json
{
  "keyword": "matcha",
  "geo": "US",
  "timeRange": "today 12-m",
  "category": 0,
  "property": "",
  "language": "en-US",
  "status": "ok",
  "interestOverTime": [
    { "date": "2026-09-13T00:00:00.000Z", "value": 74, "isPartial": false },
    { "date": "2026-09-20T00:00:00.000Z", "value": 64, "isPartial": false },
    { "date": "2026-09-27T00:00:00.000Z", "value": 65, "isPartial": true }
  ],
  "averageInterest": 75.21,
  "interestByRegion": [
    { "geoCode": "US-HI", "geoName": "Hawaii", "value": 100 },
    { "geoCode": "US-WY", "geoName": "Wyoming", "value": 95 }
  ],
  "relatedQueries": {
    "top": [{ "query": "matcha latte", "value": 100, "formattedValue": "100" }],
    "rising": [{ "query": "starbucks banana bread matcha", "value": 9600, "formattedValue": "Breakout" }]
  },
  "googleTrendsUrl": "https://trends.google.com/trends/explore?date=today+12-m&q=matcha&hl=en-US&geo=US",
  "scrapedAt": "2026-09-28T15:57:45.449Z"
}
```

`isPartial: true` marks the current period, which is not over yet. `averageInterest` leaves it out.

### Compare mode: how the shared scale works

Terms are split into groups of the anchor term plus 4 others. The anchor appears in every group, so each group
can be rescaled to the first one, and at the end everything is normalized so the highest point is 100.
Google rounds values to whole numbers, so a term that is very small next to the anchor loses precision: each
term gets `scaleConfidence` = `high`, `medium` or `low`. For best results pick an **anchor term** with popularity
similar to your other terms.

### Tips

- Values are **relative** (0-100), not search volumes. This is how Google Trends works.
- Short time ranges (past hour / day) return hourly or minute data; long ones return weekly or monthly data.
- *Parallel sessions* (default 10) sets the speed: each session uses its own IP address and paces its requests.
  If Google rate-limits a session, the Actor retries on a fresh one automatically.

### Is it legal?

This Actor collects publicly available, aggregated and anonymous statistics from Google Trends. It does not use
any Google account and collects no personal data. Check that your use complies with Google's terms and the laws
that apply to you.

### Support

Found a problem or need a feature? Open an issue on the Actor's Issues tab: we answer quickly.

# Actor input Schema

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

<b>Keywords</b>: each term on its own 0-100 scale, with all the data Google Trends shows for it.<br><b>Compare</b>: all terms on ONE shared 0-100 scale, even more than 5 (Google's limit), bridged by an anchor term.<br><b>Trending now</b>: today's trending searches for one or more countries.

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

Terms to look up, one per line. Hundreds or thousands are fine.

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

Country or region code as used by Google Trends, e.g. US, GB, IT, US-CA. Leave empty for worldwide.

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

Period to analyze. Short ranges give hourly data, long ranges weekly or monthly data.

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

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

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

Google Trends category ID. 0 = all categories (e.g. 71 = Food & Drink, 7 = Finance, 18 = Shopping).

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

Which Google search to measure: Web, Image, News, Google Shopping or YouTube.

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

Language of related topics and region names, e.g. en-US, it, de, fr.

## `interestOverTime` (type: `boolean`):

Search interest over time (0-100) for each term.

## `interestByRegion` (type: `boolean`):

Where the term is most popular (0-100 per country, region or city).

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

Level of detail for Interest by region. Automatic = countries for worldwide, regions for a country.

## `relatedQueries` (type: `boolean`):

Queries people also search for: the most popular (top) and the fastest growing (rising).

## `anchorTerm` (type: `string`):

Term used as a bridge between groups when comparing more than 5 terms. Defaults to the first search term. Pick one with popularity similar to the others for the best precision.

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

Country codes, e.g. US, GB, IT, DE.

## `outputFormat` (type: `string`):

<b>Nested</b>: one item per term with all its data. <b>Rows</b>: one flat row per data point, ready for spreadsheets.

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

More sessions = faster. Each session has its own IP address and pace; rate-limited requests are retried with new sessions automatically. 10 is a good default.

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

Google Trends limits requests per IP. The default Apify Proxy works for most runs.

## Actor input object example

```json
{
  "mode": "keywords",
  "searchTerms": [
    "coffee",
    "matcha"
  ],
  "geo": "",
  "timeRange": "today 12-m",
  "category": 0,
  "property": "",
  "language": "en-US",
  "interestOverTime": true,
  "interestByRegion": true,
  "regionResolution": "",
  "relatedQueries": true,
  "trendingGeos": [
    "US"
  ],
  "outputFormat": "nested",
  "maxConcurrency": 10,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

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

One item per search term (or per trending search), or flat rows if you chose the Rows output format.

# 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": [
        "coffee",
        "matcha"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("brii3343/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": [
        "coffee",
        "matcha",
    ],
    "proxyConfiguration": { "useApifyProxy": True },
}

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

```

## MCP server setup

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