# Google Trends API: Interest, Regions, Queries & Trending Now (`maritimio/google-trends-api`) Actor

Google Trends data as clean JSON: interest over time, interest by region, related queries, keyword comparison, and Trending Now searches by country. Pay only for complete results.

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

## Pricing

from $2.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

### What does Google Trends API do?

This Actor returns **Google Trends data as clean JSON**: interest over time, interest by region, related search queries, side-by-side keyword comparisons, and what is **trending right now** in any country. Give it a list of keywords and get structured data back in seconds, ready for a spreadsheet, a dashboard, a database or an AI agent.

**You pay only for complete results.** If Google blocks a request, a section comes back incomplete, or a keyword has no search volume, that keyword is free.

### Why use this Google Trends scraper?

- **Reliable.** Automatic retries, fresh sessions and an automatic switch to residential proxies when Google rate limits. You do not need to configure anything.
- **Fair billing.** Partial and failed results cost nothing. The only other charge is Apify's standard run start fee of $0.00005.
- **Clean data.** ISO 8601 dates, numeric values, an average interest score per keyword, and a link back to the same view on Google Trends.
- **Built for automation and AI agents.** Flat, predictable JSON that works through the Apify API, integrations, and the Apify MCP server.

### What data can you get from Google Trends?

| Data | What you get |
|---|---|
| Interest over time | Search interest from 0 to 100 for every point in the time range, with ISO dates, a flag for the incomplete latest point, and the average |
| Interest by region | Interest by country, region, city or US metro area (DMA) |
| Related queries | Top and rising related searches, including Breakout terms |
| Keyword comparison | Up to 5 keywords on one shared 0 to 100 scale, exactly like comparing them on the Google Trends website |
| Trending Now | Today's trending searches per country with approximate search volume, start time and related news links |

Supported filters: any country or subregion (or worldwide), preset time ranges from the past hour to 2004 onward, custom date ranges, Google Trends categories, and search type (web, images, news, Google Shopping, YouTube).

### How do I use it?

1. Add your keywords under **Search terms**.
2. Optionally choose a location, time range, category and search type.
3. Turn on **Compare terms** if you want keywords measured against each other.
4. Optionally add country codes under **Trending Now countries**.
5. Click **Start** and download the results as JSON, CSV, Excel or HTML, or fetch them through the API.

### How much does it cost to scrape Google Trends?

| Event | Price |
|---|---|
| One keyword result (all sections you selected) | $0.002 |
| One Trending Now search | $0.001 |
| Run start (Apify standard) | $0.00005 |

So 1,000 keywords cost $2. Partial and failed results are free. You can cap any run with the maximum cost setting, and the Actor stops cleanly when the cap is reached.

### Input example

```json
{
    "searchTerms": ["scuba diving", "snorkeling"],
    "geo": "US",
    "timeRange": "today 12-m",
    "trendingNowGeos": ["US", "CA"]
}
```

### Output example

```json
{
    "keyword": "scuba diving",
    "geo": "US",
    "timeRange": "all",
    "category": 0,
    "property": "web",
    "trendsUrl": "https://trends.google.com/trends/explore?q=scuba+diving&date=all&geo=US",
    "status": "ok",
    "interestOverTime": [
        { "date": "2025-10-01T00:00:00.000Z", "formattedTime": "Oct 2025", "isPartial": false, "value": 54 }
    ],
    "averageInterest": 67.91,
    "interestByRegion": [{ "geoCode": "US-HI", "geoName": "Hawaii", "value": 100 }],
    "regionResolution": "REGION",
    "relatedQueries": {
        "top": [{ "query": "what is scuba diving", "value": 100, "formattedValue": "100" }],
        "rising": [{ "query": "scuba diving holiday", "value": 200, "formattedValue": "+200%" }]
    },
    "scrapedAt": "2026-10-12T19:00:00.000Z"
}
```

Trending Now rows look like this:

```json
{
    "type": "trendingNow",
    "status": "ok",
    "geo": "US",
    "rank": 1,
    "title": "example trending search",
    "approxTraffic": "500+",
    "publishedAt": "2026-10-12T22:40:00.000Z",
    "news": [{ "title": "Headline", "url": "https://example.com/article", "source": "Publisher" }]
}
```

Every row has a `status` field: `ok` (charged), `partial` (free, with an `errors` list naming the missing section), `no_data` (free: Google has no search volume for that keyword) or `failed` (free). If Google blocks requests repeatedly, the run stops early instead of grinding on, and says so in its status message.

### Tips

- **Values are relative.** Google Trends scores are 0 to 100 relative to the peak in the chosen time and place. Use compare mode when you need several keywords on the same scale.
- **Low-volume keywords** may return empty related queries or regions. That is Google's data, not an error. Keywords with no search volume at all come back as `no_data` and are free.
- **Hourly ranges** (past hour, past 4 hours, past day) give minute or hour level points.
- **Speed vs blocking.** The default of 3 parallel requests is a safe balance. Raise it for big batches if you do not mind a few retries.

### FAQ

**Is it legal to scrape Google Trends?**
This Actor collects publicly available, aggregated and anonymized search statistics. Trending Now results also include public news headlines and links, as Google Trends shows them. You are responsible for how you use the results; check Google's terms and the laws that apply to you.

**Does Google Trends have an official API?**
Google announced an official Google Trends API in alpha in July 2025, with access limited to approved testers. This Actor works for everyone today and returns the same kinds of data.

**Why are related topics not included?**
Google Trends currently returns no related-topics data for these requests. We do not charge for a section that would come back empty.

**Can I use it from an AI agent?**
Yes. Call it through the Apify API or the Apify MCP server. The output shape is stable and documented above.

**Something broke or you need a feature?**
Open an issue on the Issues tab.

This Actor is not affiliated with or endorsed by Google.

# Actor input Schema

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

Keywords to look up on Google Trends. Each term is one result (or grouped into comparisons of up to 5 when Compare mode is on). Up to 1,000 per run.

## `compareMode` (type: `boolean`):

Off: each term gets its own 0 to 100 scale. On: terms are compared in groups of up to 5 on one shared scale, exactly like typing them side by side on Google Trends. Billing is the same: one result per term.

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

Two-letter country code (US, CA, ES, MX), or a subregion (US-CA, CA-QC). Leave empty for worldwide.

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

Preset time window. For an exact date range, use Custom time range below.

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

Overrides the preset. Format: YYYY-MM-DD YYYY-MM-DD, for example 2025-01-01 2025-12-31.

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

Google Trends category ID. 0 means all categories. Example: 67 = Travel, 71 = Food & Drink.

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

Which Google search to measure.

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

Timeline of search interest (0 to 100) with ISO dates, plus the average.

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

Search interest by country, region or city.

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

AUTO picks countries for worldwide, regions for a country, cities for a subregion. DMA is US metro areas.

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

Top and rising related searches, including Breakout terms.

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

Two-letter country codes. Returns what is trending on Google right now in each country, with approximate search volume and news links. Billed per trending search returned.

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

Interface language for labels such as formatted dates, for example en-US, es-ES, fr-CA.

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

How many terms to fetch at the same time. Higher is faster but more likely to be rate limited by Google.

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

Apify Proxy is used by default. If Google rate limits the run, the Actor switches to residential proxies automatically at no extra cost to you.

## Actor input object example

```json
{
  "searchTerms": [
    "scuba diving",
    "snorkeling"
  ],
  "compareMode": false,
  "geo": "",
  "timeRange": "today 12-m",
  "category": 0,
  "property": "",
  "includeInterestOverTime": true,
  "includeInterestByRegion": true,
  "regionResolution": "AUTO",
  "includeRelatedQueries": true,
  "language": "en-US",
  "maxConcurrency": 3,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

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

Interest over time, interest by region, related queries and Trending Now searches as JSON.

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

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

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

```

## MCP server setup

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