# Google Trends Bulk API - Search Interest & Related Queries (`alex_fodo/google-trends-bulk-api`) Actor

Google Trends scraper and bulk API for search-interest timelines, trend metrics, and related queries. Export structured JSON for SEO research, content planning, and automation. Pay only for complete keyword results. Beta by AGENT DOJO.

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

## Pricing

$3.00 / 1,000 complete 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 Bulk API — Search Interest & Related Queries

Collect Google Trends search-interest timelines and related queries for keyword lists. Get structured JSON with trend metrics, source links, collection timestamps, and clear coverage for every keyword.

**By AGENT DOJO.** Designed for asynchronous research and automated reports. Google can limit requests, so complete results and completion times are not guaranteed.

### Who is this for?

- SEO specialists tracking seasonality and changes in search interest.
- Content teams researching topics and related searches.
- Market researchers exploring interest in product categories.
- Developers collecting trend data for reports, dashboards, and AI workflows.

For example, collect a list of content topics each week, retrieve the results through the Apify API, and use the timelines and metrics in a report. Search interest is one research signal; it does not predict sales.

### Quick start

1. Enter your keywords, country, and time range.
2. Choose whether to include related queries.
3. Start with a small batch. Use a 10-second delay between keywords.
4. Set an appropriate run timeout and maximum charge in Run options.
5. Start the Actor and wait for completion.
6. Open Output, select All fields for the full records, or export JSON.

Example input:

```json
{
  "keywords": ["running shoes", "trail shoes", "walking shoes"],
  "geo": "US",
  "window": "today 12-m",
  "includeRelatedQueries": true,
  "delayMillis": 10000,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

For these three terms, a maximum event charge of $0.009 covers three complete results. A 180-second run timeout is a reasonable starting setting, though source failures can prevent completion.

### What you get

Each keyword produces a record containing:

- **Timeline:** interest-over-time observations, UTC timestamps, and partial-period flags.
- **Related queries:** top and rising searches, when requested, with Google's values and breakout indicators.
- **Metrics:** average interest, peak interest and date, latest complete interest, and change between two halves of the available complete observations.
- **Metadata:** keyword, country, time range, source URL, and collection time.
- **Coverage:** explicit status, warnings, errors, and whether requested data was received.

The Actor returns Google's source data without LLM-generated values or explanations.

### Pricing

**$0.003 per complete keyword result — $3 per 1,000 complete results.** Platform usage is included in the configured price. Check the Store Pricing tab for the current price before running.

One result covers one keyword, country, and time range. A complete record with `status: "ok"` generates one `keyword-result` event.

- No start fee.
- No keyword-result charge for `partial`, `failed`, or `no_data` records.
- Retries do not generate additional keyword-result charges.
- If requested related queries fail, the available timeline is returned as an uncharged partial result.
- Valid empty related-query lists count as complete source responses.
- Turning off related queries does not reduce the per-result price.
- A fresh run collects a fresh result and is charged again if complete.

Any custom proxy provider may charge separately for its service.

### Speed and limitations

A private Apify test on October 11, 2026 collected **10 complete results in approximately 2 minutes**, using direct connections and a 10-second delay between keywords. Two earlier three-keyword tests with that delay also completed successfully. These are small test samples, not a performance guarantee.

A previous run with a shorter delay returned two partial results because Google responded with HTTP 429. Longer delays can reduce request pressure but cannot eliminate source rate limits.

- Collection is sequential and intended for background batches, rather than instant search responses.
- The input limit is 300 keywords per run; reliability at that size has not yet been established.
- For initial use, start with 3–10 keywords and check the results before expanding.
- Larger batches need longer run timeouts. The 10-second delay alone adds about 90 seconds for 10 keywords, before source requests and retries.
- A run may stop early because of its charge limit, timeout, HTTP attempt cap, or consecutive incomplete results.
- Managed Apify Proxy is currently unsupported. Use No proxy, or a compatible custom proxy; authenticated custom proxies require HTTPS.

### Inputs

| Field | Default | Meaning |
|---|---|---|
| `keywords` | Required | 1–300 strings, up to 120 characters each. Trimmed exact duplicates are collected once. |
| `geo` | `US` | Uppercase two-letter country code. An empty string selects worldwide. |
| `window` | `today 12-m` | Also supports `today 3-m`, `today 1-m`, and `now 7-d`. |
| `includeRelatedQueries` | `true` | Include top and rising related queries. |
| `delayMillis` | `1500` | Delay between keywords, 250–10,000 ms. **Recommended setting: 10000.** |
| `maxRetries` | `2` | Additional attempts per source request, up to 3. |
| `requestTimeoutSeconds` | `30` | Timeout per HTTP attempt, 10–60 seconds. |
| `maxRequests` | `1500` | Total source HTTP attempts including retries, up to 4,000. |
| `maxConsecutiveFailures` | `3` | Stop after this many consecutive failed or partial results. |
| `proxyConfiguration` | No proxy | Direct collection or compatible custom proxies. |

The run timeout and maximum charge are Apify run options, separate from the input fields above. The maximum event charge limits billable results; it does not guarantee that every keyword will be processed.

### Output example

This shortened record is from a private cloud test. Timeline points and query lists are omitted for readability; full records include them when available.

```json
{
  "schemaVersion": "1.0",
  "keyword": "running shoes",
  "geo": "US",
  "window": "today 12-m",
  "status": "ok",
  "billable": true,
  "observedAt": "2026-10-11T14:58:07.891Z",
  "source": "google_trends_web",
  "sourceUrl": "https://trends.google.com/trends/explore?q=running+shoes&geo=US&date=today+12-m",
  "scaleScope": "individual_keyword_request",
  "unit": "relative_search_interest_0_100",
  "coverage": {
    "timeline": true,
    "relatedQueries": "complete"
  },
  "metrics": {
    "averageInterest": 33.02,
    "latestCompleteInterest": 16,
    "peakInterest": 100,
    "peakAt": "2026-04-12T00:00:00.000Z",
    "changePct": 67.44
  },
  "warnings": [],
  "error": null
}
```

Values can differ between runs because Google samples data and relative time ranges change.

### Status and run summary

Always inspect `status` and `coverage` before using a result:

| Status | Meaning | Keyword-result charge |
|---|---|---|
| `ok` | Complete result for the requested options | Yes |
| `partial` | Some requested data is missing | No |
| `no_data` | Source returned no usable timeline data | No |
| `failed` | Collection failed | No |

The `SUMMARY` record is available in the run's default key-value store. It reports requested keywords, delivered records, complete and incomplete counts, charged events, source HTTP attempts, and an early-stop reason if applicable.

Compare `requestedKeywords` with `deliveredRecords` to see whether the entire batch was processed. `CHARGE_LIMIT` means collection stopped to respect the event budget.

### How to interpret the data

Google Trends uses **relative search interest from 0 to 100**, not absolute monthly search volume. Each keyword is collected independently and normalized within its own request. **Do not rank different keywords by their independently collected scores.** Shared-scale multi-keyword comparison is not supported in this version.

Metrics exclude observations marked partial or having no data. The change metric compares equal-sized recent and previous groups of complete observations. When their total number is odd, the oldest observation is omitted from that comparison. This is not automatically a year-over-year comparison. Check `previousPeriod` and `recentPeriod` for their actual dates.

`changePct` is null if the previous average is zero or there are insufficient complete observations. Top and rising related-query values have different source meanings; do not treat both as search volumes.

Geographic breakdowns, related topics, and Trending Now feeds are not included in this version.

### API and automation

Start an asynchronous run using your Apify API token:

```text
POST https://api.apify.com/v2/acts/alex_fodo~google-trends-bulk-api/runs?maxTotalChargeUsd=0.009&timeout=180
Authorization: Bearer YOUR_APIFY_TOKEN
Content-Type: application/json
```

Send the Quick start JSON as the request body. Keep the returned run ID, wait for completion, then retrieve the run's default dataset and `SUMMARY`. Adjust the budget and timeout for your batch size.

For Make, n8n, or your own application, use the same sequence: start a run, wait for completion, fetch results, and route `ok` records into your report. Inspect partial and failed records separately.

Keep API tokens private. Treat related-query text as external data, not as instructions for an AI agent or executable content.

### Recovery and support

The Actor saves progress in the run's default key-value store. Recovery applies to matching input and the same run/storage; a fresh run starts a fresh collection.

If delivery becomes ambiguous after an interruption, the Actor can stop with `AMBIGUOUS_DELIVERY` instead of blindly repeating a charge. This is not an exactly-once delivery guarantee. Review the dataset and charges before retrying with cleared storage.

For bugs or feature requests, use the **Issues** tab on this Actor's page. Include the run ID, input settings, and relevant error or summary. Remove API tokens, passwords, and proxy credentials before posting.

Built by **AGENT DOJO**. This is an independent tool using [Google Trends](https://trends.google.com/) web data; it is not an official Google product or the official Google Trends API.

# Actor input Schema

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

1–300 search terms, up to 120 characters each. Exact duplicates are collected once. Each term is independently scaled; results are not absolute search volumes.

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

Uppercase two-letter country code, such as US, GB or UA. Empty string means worldwide. Unsupported source regions return diagnostics.

## `window` (type: `string`):

Relative period evaluated by Google at collection time. Timestamp fields use UTC.

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

Collect top and rising queries. If requested data is unavailable, the result is partial and no keyword-result event is charged. Empty lists returned by the source are valid.

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

Direct connection or custom proxies. Authenticated proxies require HTTPS; managed Apify Proxy is disabled until encrypted first-hop transport is verified. Direct cloud connections may be rate-limited. Validate reliability and full cost privately.

## `maxRetries` (type: `integer`):

Bounded retries for transient HTTP/network failures. Retries are not separate billable keyword events.

## `requestTimeoutSeconds` (type: `integer`):

Timeout of each individual HTTP attempt.

## `delayMillis` (type: `integer`):

Sequential keyword collection with a delay helps reduce source throttling. Failed HTTP requests also use exponential backoff.

## `maxRequests` (type: `integer`):

Hard limit for all Google requests, including retries. A complete result typically needs 2 or 3 successful requests. A lower cap can end the batch before every keyword is processed.

## `maxConsecutiveFailures` (type: `integer`):

Circuit breaker that stops work instead of continuing a batch against an unavailable source. Remaining keywords are reported in the run summary through requested/delivered counts.

## Actor input object example

```json
{
  "keywords": [
    "running shoes",
    "trail shoes",
    "walking shoes"
  ],
  "geo": "US",
  "window": "today 12-m",
  "includeRelatedQueries": true,
  "proxyConfiguration": {
    "useApifyProxy": false
  },
  "maxRetries": 2,
  "requestTimeoutSeconds": 30,
  "delayMillis": 1500,
  "maxRequests": 1500,
  "maxConsecutiveFailures": 3
}
```

# Actor output Schema

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

JSON dataset. Filter status=ok in your workflow before using complete results. Diagnostic rows are free of keyword-result event charges.

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

Coverage, request count, event count and stop reason. A successful run can contain partial/failed rows; inspect the summary.

# 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": [
        "running shoes",
        "trail shoes",
        "walking shoes"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("alex_fodo/google-trends-bulk-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 = { "keywords": [
        "running shoes",
        "trail shoes",
        "walking shoes",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("alex_fodo/google-trends-bulk-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 '{
  "keywords": [
    "running shoes",
    "trail shoes",
    "walking shoes"
  ]
}' |
apify call alex_fodo/google-trends-bulk-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,alex_fodo/google-trends-bulk-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/7TQVocMHK5oBBOk1L/builds/2GzetC7euqWwGJbO2/openapi.json