# Google Trends Explore API: Interest Over Time and by Region (`boubap/google-trends-explore`) Actor

Google Trends data for a list of keywords: interest over time and interest by country or region, with the average interest of the period. Filter by country, time range, category and Google property (web, YouTube, News, Images, Shopping). Pay per keyword with data, proxies included.

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

## Pricing

$3.00 / 1,000 keywords

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 Explore API: Interest Over Time and by Region

Get Google Trends data for a list of keywords in one run: the interest over time series, its average, and interest
by country or region. Filter by country, time range, category and Google property (Web, YouTube, News, Images,
Shopping). You pay per keyword that returns data. Residential proxies are included in the price.

### What you get for each keyword

- **Interest over time**: a 0 to 100 series, daily, weekly or monthly depending on the time range, hourly for the
  "past hour" to "past 7 days" ranges, with a flag on the last, still incomplete, period.
- **Average interest** over the period (complete periods only).
- **Interest by region**: countries when the search is worldwide, states or regions when you set a country.

### Use cases

- Check seasonality before planning content, ads or stock (Black Friday, Halloween, summer products).
- Compare demand for product ideas, niches or brands across countries and regions.
- Track how interest in a topic moves week after week, with the Apify scheduler.
- Feed a dashboard or a spreadsheet with trend curves for a list of keywords.

### Input

| Field | Description | Default |
|---|---|---|
| `keywords` | Search terms, one result per term, up to 500 per run | required |
| `timeframe` | Past hour, 4 hours, day, 7 days, 30 days, 90 days, 12 months, 5 years, since 2004, or custom | `today 12-m` |
| `customTimeframe` | With a custom range: `YYYY-MM-DD YYYY-MM-DD`, from 2004 onward | |
| `geo` | Country (`US`, `FR`) or region (`US-CA`) code, empty for worldwide | worldwide |
| `category` | Google Trends category id (0 = all) | `0` |
| `property` | `web`, `youtube`, `news`, `images` or `froogle` (Google Shopping) | `web` |
| `maxConcurrency` | Keywords fetched in parallel (1 to 10) | `5` |

Example:

```json
{ "keywords": ["halloween costumes", "christmas gifts"], "timeframe": "today 5-y", "geo": "US" }
```

### Output

One item per keyword. Real output for "web scraping", worldwide, past 90 days (lists shortened here; the full item
has 93 days and 55 countries):

```json
{
  "keyword": "web scraping",
  "geo": "",
  "timeframe": "today 3-m",
  "category": 0,
  "property": "web",
  "scrapedAt": "2026-10-05T05:20:41.000Z",
  "error": null,
  "averageInterest": 27.4,
  "interestOverTime": [
    {
      "date": "2026-07-05",
      "value": 36,
      "isPartial": false
    },
    {
      "date": "2026-07-06",
      "value": 32,
      "isPartial": false
    },
    {
      "date": "2026-10-05",
      "value": 13,
      "isPartial": true
    }
  ],
  "interestByRegion": [
    {
      "geoCode": "SH",
      "geoName": "St. Helena",
      "value": 100
    },
    {
      "geoCode": "CN",
      "geoName": "China",
      "value": 30
    },
    {
      "geoCode": "SG",
      "geoName": "Singapore",
      "value": 29
    }
  ],
  "noData": false
}
```

Values are relative: 100 is the peak of the period for this keyword and place. Dates are days (`2026-07-05`) for
ranges of 30 days or more and UTC timestamps for the shorter ranges.

### Pricing

Pay per event: one `keyword` event per keyword that returns data. These items are free:

- keywords with too little search volume (`noData: true`, zeros and no region);
- keywords that Google keeps refusing after several retries with fresh proxy sessions (an `error` message and
  empty data).

The run stops as soon as your maximum charge per run is reached. Proxy traffic is included: there is nothing else
to pay for the residential proxies this Actor uses.

### Tips

- One keyword per item: Google scales each keyword on its own 0 to 100 range, so values are not comparable across
  items. Compare the shape of the curves or the average interest rather than raw points.
- Use the past 90 days range or shorter for daily points; longer ranges return weekly or monthly points.
- If many items come back with HTTP 429 errors, lower `maxConcurrency` and run again later.
- If the platform restarts a run, keywords already saved are skipped.
- On short ranges (past hour to past 7 days), a keyword searched only once or twice shows a single spike at 100
  and is charged as data.

### FAQ

**Is there an official Google Trends API?** Google runs an alpha API open on application only. This Actor reads the
public Google Trends explore data.

**Does it return related queries or related topics?** Not in this version. Google returns unreliable related
queries and empty related topics to automated requests, so they are left out rather than sold.

**Does it collect personal data?** No. Google Trends only publishes aggregated and anonymized search interest.

**Do I need a Google account or an API key?** No. Proxies are included and you only need your Apify account.

### Related Actors

Other Actors in the same toolbox, with the same pay-per-result model:

- [Tech Stack Detector](https://apify.com/boubap/tech-stack-detector): Detect which websites run the technologies you track.
- [Career Site Jobs Scraper](https://apify.com/boubap/ats-jobs-scraper): Compare search interest with real job postings.
- [EU TED Tenders Scraper](https://apify.com/boubap/ted-tenders-scraper): Compare search interest with public tenders in the same sector.
- [French Company Search](https://apify.com/boubap/france-companies-scraper): List French companies in the sectors that show rising interest.

# Actor input Schema

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

Search terms to look up, one per line, up to 500 per run. One result item per term; duplicates are removed. Example: web scraping. Required. Google scales each keyword on its own 0 to 100 range.

## `timeframe` (type: `string`):

Period covered by the interest over time series and the interest by region. Default: Past 12 months. Short ranges (past hour to past 7 days) return hourly points, up to 90 days daily points, longer ranges weekly or monthly points. Choose Custom range to use the field below.

## `customTimeframe` (type: `string`):

Used only when Time range is Custom range. Start and end date as YYYY-MM-DD YYYY-MM-DD, from 2004 onward. Example: 2024-01-01 2024-06-30.

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

ISO country code or region code. Examples: US, FR, DE, US-CA, GB-ENG. Leave empty for worldwide (default). With a country, interest by region lists its states or regions.

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

Google Trends category id. Default 0 (all categories). Examples: 5 (Computers and Electronics), 7 (Finance), 71 (Food and Drink). Minimum 0.

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

Which Google search product the interest is measured on: Web Search (default), YouTube, News, Images or Google Shopping.

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

Number of keywords fetched in parallel, from 1 to 10. Default 5. Lower it if many items come back with HTTP 429 errors.

## Actor input object example

```json
{
  "keywords": [
    "web scraping",
    "bitcoin",
    "air fryer"
  ],
  "timeframe": "today 3-m",
  "geo": "",
  "category": 0,
  "property": "web",
  "maxConcurrency": 5
}
```

# Actor output Schema

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

Dataset items of the run: one item per result, with the fields described in the dataset schema.

# 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": [
        "web scraping",
        "bitcoin",
        "air fryer"
    ],
    "timeframe": "today 3-m"
};

// Run the Actor and wait for it to finish
const run = await client.actor("boubap/google-trends-explore").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": [
        "web scraping",
        "bitcoin",
        "air fryer",
    ],
    "timeframe": "today 3-m",
}

# Run the Actor and wait for it to finish
run = client.actor("boubap/google-trends-explore").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": [
    "web scraping",
    "bitcoin",
    "air fryer"
  ],
  "timeframe": "today 3-m"
}' |
apify call boubap/google-trends-explore --silent --output-dataset

```

## MCP server setup

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

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/XCiBNrp40Un9RFXO9/builds/QUfSMZNywiUlRILc7/openapi.json