# Google Trends Scraper & Keyword Research (`nodeflow/google-trends-scraper-keyword-research`) Actor

Scrape Google Trends keyword data, interest over time, rising queries, related searches, and regional trends. Export clean JSON for SEO research, content planning, market analysis, Google Sheets, Make, Zapier, and automated workflows.

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

## Pricing

from $2.00 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Google Trends Keyword Snapshot

Track keyword interest on Google Trends with a fast, focused Apify Actor. Get interest-over-time data and related search queries by country or region in clean JSON dataset items.

### What this Actor does

- Tracks up to 10 keywords in one run
- Returns one dataset item per unique keyword
- Collects Google Trends interest over time on a 0–100 scale
- Extracts related search queries and their relative values
- Supports country/region targeting such as `US`, `GB`, `DE`, and `TR`
- Supports time ranges from the past hour to the past 5 years
- Supports Web Search, Google News, Google Images, Google Shopping, and YouTube properties
- Uses lightweight HTTP requests without browser automation
- Supports Apify Proxy for repeated or higher-volume runs
- Produces API-friendly JSON output for SEO tools, content workflows, dashboards, and alerts

### Why use Google Trends Keyword Snapshot?

Many trend workflows need only two things: historical search interest and the queries growing around a topic. This Actor focuses on those signals without adding unrelated profile, company, or page data. It is designed for quick keyword research, content planning, market monitoring, and automation.

### Input

| Field                | Type         | Default                           | Description                                                   |
| -------------------- | ------------ | --------------------------------- | ------------------------------------------------------------- |
| `keywords`           | string array | `[`"`artificial intelligence`"`]` | One to ten keywords to track                                  |
| `geo`                | string       | `US`                              | Country or region code; use an empty value for worldwide data |
| `timeRange`          | select       | `today 12-m`                      | Google Trends period                                          |
| `category`           | integer      | `0`                               | Google Trends category ID; `0` means all categories           |
| `property`           | select       | Web Search                        | Web, News, Images, Shopping, or YouTube                       |
| `proxyConfiguration` | object       | optional                          | Apify Proxy configuration                                     |

#### Example input

```json
{
  "keywords": ["ai agents", "generative ai", "workflow automation"],
  "geo": "US",
  "timeRange": "today 12-m",
  "category": 0,
  "property": ""
}
```

### Output

The Actor creates one dataset item per keyword. `timeline` contains the interest-over-time points returned by Google Trends. Values are relative to the selected period, where 100 is the peak interest for that keyword and 0 means insufficient data or no measurable interest.

```json
{
  "keyword": "ai agents",
  "geo": "US",
  "timeRange": "today 12-m",
  "category": 0,
  "property": "",
  "timeline": [
    {
      "time": "1711929600",
      "formattedTime": "Apr 2024",
      "value": 42
    }
  ],
  "relatedQueries": [
    {
      "query": "ai agent tools",
      "value": 100,
      "formattedValue": "Breakout"
    }
  ],
  "sourceUrl": "https://trends.google.com/trends/explore?geo=US&q=ai%20agents",
  "success": true,
  "error": null
}
```

If one keyword fails, the Actor records `success: false` and the error for that keyword while continuing with the remaining keywords.

### Use cases

- SEO keyword research and content calendars
- Discovering rising related queries
- Comparing demand signals across regions
- Monitoring a product category or market topic
- Building trend dashboards and newsletters
- Feeding Make, Zapier, Google Sheets, Airtable, or custom APIs
- Scheduling daily or weekly keyword snapshots

### Pay-per-event pricing

This Actor is designed for usage-based billing: **one successful or failed keyword snapshot equals one billable event**. Configure the final event price in the Apify Console Store pricing settings. The Actor itself does not require a subscription or external API key.

### Run with the Apify API

```bash
curl "https://api.apify.com/v2/acts/YOUR_USERNAME~google-trends-keyword-snapshot/runs" \\
  -X POST \\
  -H "Authorization: Bearer YOUR_APIFY_TOKEN" \\
  -H "Content-Type: application/json" \\
  -d '{
    "keywords": ["ai agents", "content marketing"],
    "geo": "US",
    "timeRange": "today 12-m",
    "category": 0,
    "property": ""
  }'
```

### Local development

Requirements: Node.js 20 or newer.

```bash
npm install
npm run check
npm run test:live
```

To run the full Actor locally, place input JSON at `storage/key_value_stores/default/INPUT.json` and start it:

```bash
mkdir -p storage/key_value_stores/default
cp INPUT.example.json storage/key_value_stores/default/INPUT.json
npm start
```

Results are written to `storage/datasets/default/`.

### Data source and limitations

- Data comes from Google Trends public web endpoints.
- Google Trends values are relative, not absolute search volume.
- Related queries and timeline points depend on the selected keyword, region, property, and period.
- Google may change public endpoint behavior or rate-limit repeated requests; Apify Proxy is recommended for scheduled or larger runs.
- No Google login, cookies, or private account data are used.
- This Actor is not affiliated with or endorsed by Google.

### Responsible use

Use the Actor in accordance with Google’s terms, applicable laws, and your own data-use requirements. Do not use it to infer sensitive personal information about individuals.

### License

MIT

# Actor input Schema

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

One or more search terms. The Actor creates one dataset item per unique keyword.

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

Two-letter country code such as US, GB, DE, or TR. Leave empty for worldwide data.

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

Google Trends comparison period.

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

Optional Google Trends category ID. Use 0 for all categories.

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

Search property: web, news, images, google shopping, or youtube.

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

Optional Apify Proxy settings for repeated or high-volume runs.

## Actor input object example

```json
{
  "keywords": [
    "artificial intelligence"
  ],
  "geo": "US",
  "timeRange": "today 12-m",
  "category": 0,
  "property": "",
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

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

No description

# 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": [
        "artificial intelligence"
    ],
    "geo": "US",
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("nodeflow/google-trends-scraper-keyword-research").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": ["artificial intelligence"],
    "geo": "US",
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("nodeflow/google-trends-scraper-keyword-research").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": [
    "artificial intelligence"
  ],
  "geo": "US",
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call nodeflow/google-trends-scraper-keyword-research --silent --output-dataset

```

## MCP server setup

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

```

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/VjjiVxSlU5Cq9wqHU/builds/VdL30p796A2Q3EKou/openapi.json