# Google Trends Scraper (`kawsar/google-trends-scraper`) Actor
Google Trends Scraper that fetches keyword interest, regional data, related topics, and rising queries from Google Trends, so you can track search demand and catch trends before they peak.
- **URL**: https://apify.com/kawsar/google-trends-scraper.md
- **Developed by:** [Kawsar](https://apify.com/kawsar) (community)
- **Categories:** SEO tools, Developer tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks
- **User rating**: No ratings yet
## Pricing
from $0.99 / 1,000 results
This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.
Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event
## What's an Apify Actor?
Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
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.
In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):
```bash
npm install apify-client
```
In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):
```bash
pip install apify-client
```
In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):
````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash
In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).
If your project is in a different language, use 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 Scraper
Extract keyword interest by region from Google Trends. For each keyword you enter, the actor returns a flat list of countries with their indexed search interest scores. Good for SEO research, market analysis, and finding which countries are driving demand for any topic.
### What it collects
For each keyword, the actor returns one row per country containing:
- **geoCode** — ISO country code (e.g. `US`, `IN`, `DE`)
- **geoName** — Full country name
- **value** — Search interest indexed from 0 to 100 (100 = peak interest)
- **formattedValue** — Same value as a formatted string
- **hasData** — Whether Google had enough data for this country
### Input
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `keywords` | string list | Yes | — | Keywords to analyze. Each keyword costs 20 credits. |
| `geo` | select | No | Worldwide | Filter results to a specific country |
| `timeRange` | select | No | Past 12 months | Time period for the data |
| `gprop` | select | No | Web Search | Search type |
| `maxRegions` | integer | No | `0` (all) | Limit rows returned per keyword. `0` returns all countries. |
| `maxItems` | integer | No | `100` | Max keywords to process per run |
| `requestTimeoutSecs` | integer | No | `30` | Per-request timeout in seconds |
#### Time range options
| Value | Label |
|---|---|
| `now 1-H` | Past hour |
| `now 4-H` | Past 4 hours |
| `now 1-d` | Past day |
| `now 7-d` | Past 7 days |
| `today 1-m` | Past 30 days |
| `today 3-m` | Past 90 days |
| `today 12-m` | Past 12 months |
| `today 5-y` | Past 5 years |
| `all` | Since 2004 |
#### Search type options
| Value | Label |
|---|---|
| *(blank)* | Web Search |
| `images` | Image Search |
| `news` | News Search |
| `youtube` | YouTube Search |
| `froogle` | Google Shopping |
#### Geographic filter options
| Code | Country | Code | Country |
|---|---|---|---|
| *(blank)* | Worldwide | `MX` | Mexico |
| `US` | United States | `IT` | Italy |
| `GB` | United Kingdom | `ES` | Spain |
| `CA` | Canada | `NL` | Netherlands |
| `AU` | Australia | `SG` | Singapore |
| `IN` | India | `ZA` | South Africa |
| `DE` | Germany | `NG` | Nigeria |
| `FR` | France | `PH` | Philippines |
| `BR` | Brazil | `ID` | Indonesia |
| `JP` | Japan | `PK` | Pakistan |
| `KR` | South Korea | `BD` | Bangladesh |
| `TR` | Turkey | `SA` | Saudi Arabia |
| `AE` | United Arab Emirates | `AR` | Argentina |
| `CO` | Colombia | `PL` | Poland |
| `SE` | Sweden | `NO` | Norway |
| `DK` | Denmark | `FI` | Finland |
| `AT` | Austria | `CH` | Switzerland |
| `PT` | Portugal | `MY` | Malaysia |
| `TH` | Thailand | `VN` | Vietnam |
| `EG` | Egypt | `NZ` | New Zealand |
| `RU` | Russia | `UA` | Ukraine |
| `HK` | Hong Kong | `TW` | Taiwan |
| `CN` | China | `IL` | Israel |
| `GR` | Greece | `CZ` | Czech Republic |
| `HU` | Hungary | `RO` | Romania |
| `BE` | Belgium | | |
### Example input
```json
{
"keywords": ["python", "javascript", "typescript"],
"geo": "",
"timeRange": "today 12-m",
"gprop": "",
"maxRegions": 10
}
````
### Output
Each run produces one row per keyword per country. For 3 keywords with worldwide data, you will typically get 150–250 rows total.
**Example rows for keyword "python":**
```json
[
{
"keyword": "python",
"geo": "",
"timeRange": "today 12-m",
"gprop": "",
"geoCode": "CN",
"geoName": "China",
"value": 100,
"formattedValue": "100",
"hasData": true,
"scrapedAt": "2026-05-18T11:09:17.754800+00:00",
"error": null
},
{
"keyword": "python",
"geo": "",
"timeRange": "today 12-m",
"gprop": "",
"geoCode": "IN",
"geoName": "India",
"value": 87,
"formattedValue": "87",
"hasData": true,
"scrapedAt": "2026-05-18T11:09:17.754800+00:00",
"error": null
}
]
```
#### Output field reference
| Field | Type | Description |
|---|---|---|
| `keyword` | string | The search term analyzed |
| `geo` | string | Country filter applied (empty = worldwide) |
| `timeRange` | string | Time period used |
| `gprop` | string | Search type used |
| `geoCode` | string | ISO country or region code |
| `geoName` | string | Full country or region name |
| `value` | integer | Search interest 0–100 (100 = highest point in period) |
| `formattedValue` | string | Value as a formatted string |
| `hasData` | boolean | Whether Google had sufficient data for this region |
| `scrapedAt` | string | UTC timestamp when the record was collected |
| `error` | string/null | Error message if the keyword failed, otherwise null |
### How to run
#### Via Apify Console
1. Open the actor and go to the **Input** tab
2. Type one or more keywords into the **Keywords** field
3. Choose a country filter if needed (leave blank for worldwide)
4. Set time range and search type
5. Optionally set **Max regions per keyword** to limit output rows
6. Click **Start**
7. Download results as JSON, CSV, or Excel from the **Dataset** tab
### Use cases
- **SEO geo-targeting** — find which countries search for your target keyword most, then prioritize those markets
- **Market expansion research** — compare demand for a product category across 50+ countries before entering a new market
- **Content localization** — see where a topic is trending to decide which language versions to build first
- **Competitor keyword tracking** — monitor regional demand for competitor brand names over time
- **YouTube channel strategy** — switch search type to YouTube to find where your video topics have the strongest audience
- **E-commerce demand mapping** — use Google Shopping search type to find where product demand is highest
### Scheduling
Use Apify's built-in scheduler to run the actor on a recurring schedule. Weekly runs let you track how regional interest shifts over time.
1. Open the actor and configure your keyword list
2. Click **Schedule** in the top menu
3. Set a cron expression — for example `0 9 * * 1` runs every Monday at 9am
4. Each run adds new rows to the dataset so you can see trends across weeks
### Integrations
- **Google Sheets** — push results to a spreadsheet automatically after each run
- **Slack** — get notified when a run finishes
- **Make / Zapier** — route data to any downstream tool
- **Webhook** — send results to your own endpoint on completion
### Frequently asked questions
**What does a value of 100 mean?**
It means that country had the highest search interest for the keyword within the selected time period and region filter. All other countries are scored relative to that peak. It is not an absolute search volume number.
**Why do some countries show value 0 or hasData: false?**
Google does not return data for countries where search volume for the keyword is too low to be statistically reliable. This is normal for niche keywords or small markets.
**Can I get sub-region data (states, cities)?**
Not in the current version. The actor returns country-level data. Sub-region resolution requires a separate widget type.
**Can I run multiple keywords at once?**
Yes. Add all keywords to the list. They are processed one at a time. Each costs 20 credits regardless of how many regions are returned.
**Why does the `geo` filter change the results?**
When you set `geo` to a specific country, Google Trends returns sub-region data for that country (states, provinces) instead of country-level data. For worldwide comparison, leave it blank.
**How many rows will I get per keyword?**
Worldwide with no `maxRegions` limit: typically 50–250 rows depending on the keyword. Use `maxRegions` to cap this.
### Limitations
- Values are relative (0–100), not absolute search volumes
- Keywords with very low global search volume may return no regional data
- Google Trends data has a 1–3 day lag for recent periods
- Hourly data is only available for time ranges of 7 days or less
# Actor input Schema
## `keywords` (type: `array`):
One or more search terms to analyze. Each keyword produces one row per country/region.
## `geo` (type: `string`):
Filter results to a specific country. Select Worldwide to get global data.
## `timeRange` (type: `string`):
Time period for the trend data.
## `gprop` (type: `string`):
Type of Google search to analyze.
## `maxRegions` (type: `integer`):
Limit how many country/region rows are returned per keyword. Results are returned in the order Google provides (highest interest first). Set to 0 for all regions.
## `maxItems` (type: `integer`):
Maximum number of keywords to process per run.
## `requestTimeoutSecs` (type: `integer`):
Per-request timeout in seconds.
## Actor input object example
```json
{
"keywords": [
"python programming",
"machine learning"
],
"geo": "",
"timeRange": "today 12-m",
"gprop": "",
"maxRegions": 0,
"maxItems": 100,
"requestTimeoutSecs": 30
}
```
# 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 '' with your token
const client = new ApifyClient({
token: '',
});
// Prepare Actor input
const input = {
"keywords": [
"python"
]
};
// Run the Actor and wait for it to finish
const run = await client.actor("kawsar/google-trends-scraper").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 '' with your token.
client = ApifyClient("")
# Prepare the Actor input
run_input = { "keywords": ["python"] }
# Run the Actor and wait for it to finish
run = client.actor("kawsar/google-trends-scraper").call(run_input=run_input)
# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).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": [
"python"
]
}' |
apify call kawsar/google-trends-scraper --silent --output-dataset
```
## MCP server setup
```json
{
"mcpServers": {
"apify": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.apify.com/?tools=kawsar/google-trends-scraper",
"--header",
"Authorization: Bearer "
]
}
}
}
```
## OpenAPI specification
```json
{
"openapi": "3.0.1",
"info": {
"title": "Google Trends Scraper",
"description": "Google Trends Scraper that fetches keyword interest, regional data, related topics, and rising queries from Google Trends, so you can track search demand and catch trends before they peak.",
"version": "0.0",
"x-build-id": "u2shsqswtVY8Mqiuk"
},
"servers": [
{
"url": "https://api.apify.com/v2"
}
],
"paths": {
"/acts/kawsar~google-trends-scraper/run-sync-get-dataset-items": {
"post": {
"operationId": "run-sync-get-dataset-items-kawsar-google-trends-scraper",
"x-openai-isConsequential": false,
"summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
},
"/acts/kawsar~google-trends-scraper/runs": {
"post": {
"operationId": "runs-sync-kawsar-google-trends-scraper",
"x-openai-isConsequential": false,
"summary": "Executes an Actor and returns information about the initiated run in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/runsResponseSchema"
}
}
}
}
}
}
},
"/acts/kawsar~google-trends-scraper/run-sync": {
"post": {
"operationId": "run-sync-kawsar-google-trends-scraper",
"x-openai-isConsequential": false,
"summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
}
},
"components": {
"schemas": {
"inputSchema": {
"type": "object",
"required": [
"keywords"
],
"properties": {
"keywords": {
"title": "Keywords",
"type": "array",
"description": "One or more search terms to analyze. Each keyword produces one row per country/region.",
"items": {
"type": "string"
}
},
"geo": {
"title": "Geographic region",
"enum": [
"",
"US",
"GB",
"CA",
"AU",
"IN",
"DE",
"FR",
"BR",
"JP",
"KR",
"MX",
"IT",
"ES",
"NL",
"SG",
"ZA",
"NG",
"PH",
"ID",
"PK",
"BD",
"TR",
"SA",
"AE",
"AR",
"CO",
"PL",
"SE",
"NO",
"DK",
"FI",
"AT",
"CH",
"PT",
"MY",
"TH",
"VN",
"EG",
"NZ",
"RU",
"UA",
"HK",
"TW",
"CN",
"IL",
"GR",
"CZ",
"HU",
"RO",
"BE"
],
"type": "string",
"description": "Filter results to a specific country. Select Worldwide to get global data.",
"default": ""
},
"timeRange": {
"title": "Time range",
"enum": [
"now 1-H",
"now 4-H",
"now 1-d",
"now 7-d",
"today 1-m",
"today 3-m",
"today 12-m",
"today 5-y",
"all"
],
"type": "string",
"description": "Time period for the trend data.",
"default": "today 12-m"
},
"gprop": {
"title": "Search type",
"enum": [
"",
"images",
"news",
"youtube",
"froogle"
],
"type": "string",
"description": "Type of Google search to analyze.",
"default": ""
},
"maxRegions": {
"title": "Max regions per keyword",
"minimum": 0,
"maximum": 250,
"type": "integer",
"description": "Limit how many country/region rows are returned per keyword. Results are returned in the order Google provides (highest interest first). Set to 0 for all regions.",
"default": 0
},
"maxItems": {
"title": "Max keywords",
"minimum": 1,
"maximum": 1000,
"type": "integer",
"description": "Maximum number of keywords to process per run.",
"default": 100
},
"requestTimeoutSecs": {
"title": "Request timeout (seconds)",
"minimum": 5,
"maximum": 120,
"type": "integer",
"description": "Per-request timeout in seconds.",
"default": 30
}
}
},
"runsResponseSchema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"actId": {
"type": "string"
},
"userId": {
"type": "string"
},
"startedAt": {
"type": "string",
"format": "date-time",
"example": "2025-01-08T00:00:00.000Z"
},
"finishedAt": {
"type": "string",
"format": "date-time",
"example": "2025-01-08T00:00:00.000Z"
},
"status": {
"type": "string",
"example": "READY"
},
"meta": {
"type": "object",
"properties": {
"origin": {
"type": "string",
"example": "API"
},
"userAgent": {
"type": "string"
}
}
},
"stats": {
"type": "object",
"properties": {
"inputBodyLen": {
"type": "integer",
"example": 2000
},
"rebootCount": {
"type": "integer",
"example": 0
},
"restartCount": {
"type": "integer",
"example": 0
},
"resurrectCount": {
"type": "integer",
"example": 0
},
"computeUnits": {
"type": "integer",
"example": 0
}
}
},
"options": {
"type": "object",
"properties": {
"build": {
"type": "string",
"example": "latest"
},
"timeoutSecs": {
"type": "integer",
"example": 300
},
"memoryMbytes": {
"type": "integer",
"example": 1024
},
"diskMbytes": {
"type": "integer",
"example": 2048
}
}
},
"buildId": {
"type": "string"
},
"defaultKeyValueStoreId": {
"type": "string"
},
"defaultDatasetId": {
"type": "string"
},
"defaultRequestQueueId": {
"type": "string"
},
"buildNumber": {
"type": "string",
"example": "1.0.0"
},
"containerUrl": {
"type": "string"
},
"usage": {
"type": "object",
"properties": {
"ACTOR_COMPUTE_UNITS": {
"type": "integer",
"example": 0
},
"DATASET_READS": {
"type": "integer",
"example": 0
},
"DATASET_WRITES": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_READS": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_WRITES": {
"type": "integer",
"example": 1
},
"KEY_VALUE_STORE_LISTS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_READS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_WRITES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_INTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_EXTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_SERPS": {
"type": "integer",
"example": 0
}
}
},
"usageTotalUsd": {
"type": "number",
"example": 0.00005
},
"usageUsd": {
"type": "object",
"properties": {
"ACTOR_COMPUTE_UNITS": {
"type": "integer",
"example": 0
},
"DATASET_READS": {
"type": "integer",
"example": 0
},
"DATASET_WRITES": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_READS": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_WRITES": {
"type": "number",
"example": 0.00005
},
"KEY_VALUE_STORE_LISTS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_READS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_WRITES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_INTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_EXTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_SERPS": {
"type": "integer",
"example": 0
}
}
}
}
}
}
}
}
}
}
```