# Google Trends Scraper — Interest, Regions & Related Queries (`genial_candlestand/google-trends-scraper`) Actor

Returns Google Trends data for your search terms: a 0–100 timeline, interest per country, state, US metro or city, and top and rising related queries, with up to 5 terms on one scale. Flat rows for Sheets, BI or AI agents. No login, $3.00 per 1,000 keyword reports.

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

## Pricing

from $2.73 / 1,000 keyword reports

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/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 Scraper — Interest, Regions & Related Queries

Google Trends Scraper returns flat rows of Google Trends data for your search terms: **interest over time** (a 0–100 `value` per time point with `periodStart`), **interest by region** (a score per country, state, US metro area or city, with `latitude` and `longitude` for cities) and **related queries** (top and rising, with `isBreakout`). You can compare up to 5 terms on one scale, with no login or browser, for $3.00 per 1,000 keyword reports.

### What does Google Trends Scraper do?

Google Trends Scraper gets [Google Trends](https://trends.google.com) data for your search terms. You can look up each term on its own or compare up to 5 terms on one scale. For every search it returns three sections:

- **Interest over time**: a 0–100 score for each time point (minutes, hours, days, weeks or months, depending on the time range).
- **Interest by region**: a 0–100 score per country, state/region, US metro area or city. Cities come with latitude and longitude.
- **Related queries**: the top and rising searches for each term, including Google's "Breakout" label.

Each result is a **flat row** with ISO dates, so it opens directly in Google Sheets, Excel or a BI tool, or can be passed to an AI agent. The actor talks to Google Trends over plain HTTP. It doesn't need a browser or a Google account. It's made for SEO and content marketers, market researchers, analysts, journalists and automations.

### How to use Google Trends Scraper

1. Open the actor in Apify Console.
2. Enter your **Search terms**, one per line, e.g. `coffee` and `tea`.
3. To see which term is searched more, tick **Compare the terms on one scale** (2–5 terms).
4. Pick a **Country** (empty = worldwide) and a **Time range** (past 12 months by default). Untick sections in **Data to extract** that you don't need.
5. Optional: open **More filters** to set a state or region, a category, the Google search type (web, YouTube, images, news, shopping), the region level or custom dates. Or paste **Google Trends links** copied from your browser.
6. Click **Start**. Download the dataset as JSON, CSV or Excel, or open the **Overview** and **Interest over time** tables.

Developers and AI agents can send the same JSON input through the Apify API, the Apify clients or the Apify MCP server.

### Pricing

Pricing is pay-per-event, with one event: **$3.00 per 1,000 keyword reports** ($0.003 per report).

| Event | Price |
|---|---|
| `keyword-report`: one search term in one search, with every section you requested (timeline, regions, related queries) | $0.003 |

A keyword report is usually about 200 flat rows (119–393 in our test runs with all three sections). **The rows themselves are free**: you pay once per term, not per row. In a comparison (**Compare** ticked, or a Google Trends link with several terms) each term is its own report, so comparing 3 terms costs 3 reports = $0.009. No platform usage is billed on top.

Example costs:

- The prefilled input (`coffee` and `tea`, worldwide, all sections): 2 reports = **$0.006**
- 100 search terms with all three sections: **$0.30**
- 1,000 search terms: **$3.00**
- 100 search terms with only related queries: still 100 reports = **$0.30**. Fewer sections make the run faster and the dataset smaller, not cheaper.
- A term Google has no data for: **$0**

What costs nothing:

- terms Google has no data for, and searches that fail;
- a run with no data at all, which still ends as succeeded;
- invalid input: the run stops before the first request with a message naming the field.

If one section of a report fails (for example related queries), the other sections are still saved, the report is charged once, and the log names the missing section. A report cut short by **Max rows** is also charged once. Higher Apify subscription plans may get a lower price per report; Console shows the price for your plan.

### Input

| Field | What it does |
|---|---|
| **Search terms** (`queries`) | One term per line, up to 100 characters each, no commas. Every term gets its own report. Duplicates are skipped. |
| **Compare the terms on one scale** (`compareQueries`) | Off by default. When on, 2–5 terms are looked up together, as on the Trends Compare page, and share one 0–100 scale. |
| **Country** (`country`) | Empty = worldwide. Pick one of 20 markets from the list or type any country as a code (`CH`) or English name (`Switzerland`). |
| **Time range** (`timeRange`) | Past hour, 4 hours, day, 7 days, 30 days, 90 days, 12 months (default), 5 years, 2004 – present, or custom dates. |
| **Data to extract** (`dataTypes`) | `interestOverTime`, `interestByRegion`, `relatedQueries`. All three by default. |
| **State or region** (`region`) | A region inside Country, by name (`California`) or code (`CA`, `US-CA`). |
| **Category** (`category`) | A Google Trends category by name (`Food & Drink`, `Programming`) or ID (`71`). Empty = all categories. |
| **Google search type** (`property`) | `web` (default), `youtube`, `images`, `news` or `shopping`. |
| **Interest by region: level** (`regionResolution`) | `auto` (as on Google Trends, default), `CITY` (any location, with coordinates) or `DMA` (US metro areas, Country = United States only). |
| **Custom start / end date** (`startDate`, `endDate`) | `YYYY-MM-DD`, used only with Time range = Custom dates. Data starts on 2004-01-01. |
| **Google Trends links** (`startUrls`) | Explore page links. Each link is one search with its own terms (up to 5), location, time, category and search type. |
| **Max rows** (`maxItems`) | Stop after this many rows in total. Empty = no limit. Rows are free; a report cut short by this limit is still charged once. |
| **Proxy** (`proxyConfiguration`) | Apify Proxy, datacenter by default. Switch to `RESIDENTIAL` only if runs report blocking. |

Invalid combinations stop the run before any request, with a message that names the field and says how to fix it. Examples: an unknown country or category, a region without a country, US metro areas outside the United States, or more than 5 terms to compare.

Example input (compare three drinks in the US over the past 90 days):

```json
{
  "queries": ["coffee", "tea", "matcha"],
  "compareQueries": true,
  "country": "US",
  "timeRange": "past90Days",
  "dataTypes": ["interestOverTime", "interestByRegion", "relatedQueries"]
}
```

### Output

The actor saves one flat row per data point. The `dataType` field says which section a row comes from. Fields of other sections are `null` or absent on that row.

**One keyword report** (the unit you pay for) is all rows of one search term in one search, i.e. the rows with the same `url` and `query`: its interest-over-time points, its regions with data and its top and rising related queries, whichever sections you requested. The rows of a report are saved together. A term without data gives no report and no rows.

| Field | Rows | Description |
|---|---|---|
| `url` | all | Google Trends Explore page of the search |
| `scrapedAt` | all | When the row was extracted (ISO 8601) |
| `dataType` | all | `interestOverTime`, `interestByRegion` or `relatedQueries` |
| `query` | all | The search term the row is about |
| `searchTerms` | all | All terms of the search, comma-separated (more than one = a comparison) |
| `geo` | all | Geo code of the search (`US`, `US-CA`, `US-CA-807`) or `WORLDWIDE` |
| `timeRange` | all | Google's time string, e.g. `today 12-m` or `2024-01-01 2024-12-31` |
| `categoryId`, `category` | all | Category ID and name (`0`, `All categories` when not narrowed) |
| `property` | all | `web`, `youtube`, `images`, `news` or `shopping` |
| `value` | all | 0–100 interest or top-query score; growth in % for a rising query |
| `formattedValue` | all | The value as Google shows it, e.g. `"63"`, `"+1,750%"`, `"Breakout"` |
| `periodStart`, `formattedTime` | interest over time | Start of the time point (ISO 8601, UTC) and Google's label |
| `hasData` | time points, regions | `false` when Google has too little data (value 0). Region rows are only saved with data, so they show `true`. |
| `isPartial` | interest over time | `true` for the last, still incomplete time point |
| `regionResolution`, `geoCode`, `location` | interest by region | Level (`COUNTRY`, `REGION`, `DMA`, `CITY`), region code (null for cities) and name |
| `latitude`, `longitude` | interest by region, cities | City coordinates |
| `rankType`, `position` | related queries | `top` or `rising` list and the 1-based rank |
| `relatedQuery`, `relatedQueryUrl`, `isBreakout` | related queries | Query text, its Trends page, and the "Breakout" flag |

A real interest-over-time row from a test run (`coffee`, worldwide, past 12 months):

```json
{
  "url": "https://trends.google.com/trends/explore?q=coffee&date=today+12-m",
  "dataType": "interestOverTime",
  "query": "coffee",
  "searchTerms": "coffee",
  "geo": "WORLDWIDE",
  "timeRange": "today 12-m",
  "categoryId": 0,
  "category": "All categories",
  "property": "web",
  "value": 60,
  "formattedValue": "60",
  "periodStart": "2025-10-12T00:00:00.000Z",
  "formattedTime": "Oct 12 – 18, 2025",
  "hasData": true,
  "isPartial": false,
  "scrapedAt": "2026-10-13T10:22:59.342Z"
}
```

### Use cases

- **Seasonality in one market.** `bitcoin` with Country = United States: weekly points for 12 months, every US state and 50 related queries (154 rows in our test).
- **Brand and product comparison.** Compare `coffee`, `tea` and `matcha` on one scale over 90 days: daily points, countries and related queries per term.
- **Content ideas from rising queries.** Keep only related queries, e.g. `election` in California over the past 7 days, to get the top and rising searches in a faster, smaller run (still one report per term).
- **City maps.** Set the region level to Cities to get interest per city with latitude and longitude.
- **Long-run series and saved charts.** `kubernetes` since 2004 in Computers & Electronics gives a monthly series. You can also paste links from the Trends site, for example a YouTube chart for the past day.

### Limitations

- **No related topics.** Google sends an empty related-topics list to visitors who aren't signed in, so only related queries are returned.
- **Relative values.** Scores are 0–100 relative to the highest point of the search and based on Google's sampling. They are not search volumes, and repeated runs can differ by a few points.
- **At most 5 terms per comparison**, as in the Google Trends interface. Use several links for more comparisons.
- **City data is sparse.** Google often has city data only for popular terms. When it has none, the term gets no region rows and a warning, and its other sections are kept. Some small countries (e.g. Cayman Islands, Singapore) may have no regional data at all.
- **Region levels.** US metro areas (DMA) work only with Country = United States. Some countries (e.g. Ireland, Singapore) have no states or regions on Google Trends, so State or region must stay empty there.
- **Non-web search types start in 2008.** Earlier time points come back with `hasData: false`.
- **Times are in UTC.** Trending Now (daily trending searches) is not included.
- **Rate limits.** Google blocks single IPs quickly. The actor uses a fresh proxy session per search and retries failures. Without a proxy you get a captcha after a few dozen requests. If searches keep failing, switch to the `RESIDENTIAL` proxy group.

### FAQ

**Is it legal to scrape Google Trends?**
The actor collects only aggregated, public Google Trends statistics and no personal data. You are responsible for how you use the data and for following the laws and terms that apply to you. If in doubt, ask a lawyer.

**Do I need a Google account or an API key?**
No. No login, API key or browser is used.

**How do I pick a country or category that isn't in the list?**
Type it. Country takes any two-letter code or English name Google Trends knows. Category takes any of Google's 1,100+ category names or its numeric ID (the `cat=` number in a Trends link).

**What's the difference between separate terms and "Compare"?**
Separately, each term is scaled to its own peak of 100. With Compare on, all terms share one scale, so you can see which one is searched more.

**How is this different from other Google Trends tools?**
It reads Google Trends over plain HTTP instead of a browser, and a failed search is retried with a fresh proxy session. One run takes many search terms, and there is no per-run start fee. You get flat, typed rows instead of nested arrays, and you choose the region level and the search type. Wrong inputs are caught before any request, and a failed section doesn't lose the other sections of the same search. You pay one fixed price per keyword report, all its rows included, and terms without data are free.

**Can I use it from an AI agent?**
Yes. The input is small and readable: country and category by name, time ranges like `past90Days`. Call it through the Apify API or MCP server.

# Actor input Schema

## `queries` (type: `array`):

What to look up on Google Trends, one term per line, e.g. `bitcoin` or `iphone 17`. Each term gets its own report. Max 100 characters per term and no commas — to compare terms, put each on its own line and tick Compare below. Fill this, Google Trends links, or both.

## `compareQueries` (type: `boolean`):

Off: each term is looked up alone and its own peak is 100. On: 2–5 terms are looked up together, as on the Google Trends Compare page, so they share one 0–100 scale and you see which is searched more. More than 5 terms with this on stops the run before any request.

## `country` (type: `string`):

Where people searched. Leave empty for worldwide. Pick from the list, or type any other country as a two-letter code (`CH`) or English name (`Switzerland`).

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

Period of the trend. It also sets the step of the time points: every minute for the past hour or 4 hours, every 8 minutes for the past day, hourly for 7 days, daily for 30 or 90 days, weekly for 12 months or 5 years, monthly since 2004. "Custom dates" uses the start and end dates under More filters.

## `dataTypes` (type: `array`):

Sections returned for every search: interest over time (one row per time point), interest by region (one row per region with data) and related queries (one row per top or rising query). You pay once per search term with data (a keyword report), whatever sections it includes; untick sections you don't need for a smaller, faster result. Empty = all three.

## `region` (type: `string`):

Narrow Country to one state, province or region, by name (`California`, `Bavaria`) or code (`CA` or `US-CA`). Leave empty for the whole country. Some countries have no regions on Google Trends (e.g. Ireland, Singapore); a region there stops the run with a message.

## `category` (type: `string`):

Keep only searches from one Google Trends category, e.g. `Food & Drink` for `apple` the fruit. Pick from the list or type any of Google's 1,100+ categories by exact name (`Programming`) or ID (the `cat=` number in a Trends link, e.g. `31`). Empty = all categories.

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

Which Google search to measure: web search (the Google Trends default), YouTube, image, news or Google Shopping search. Non-web data starts in 2008; earlier time points come back without data.

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

Automatic: as on Google Trends — countries for worldwide, states/regions for a country, metro areas for a US state, cities elsewhere. Cities: any location, with latitude/longitude, but Google often has city data only for popular terms (otherwise no region rows and a warning). US metro areas (DMA): Country = United States only.

## `startDate` (type: `string`):

First day of the period (`YYYY-MM-DD`, from 2004-01-01). Used only when Time range is "Custom dates", and then required with the end date.

## `endDate` (type: `string`):

Last day of the period (`YYYY-MM-DD`). Used only when Time range is "Custom dates". Must not be before the start date; a future date is cut to today.

## `startUrls` (type: `array`):

Explore page links copied from your browser, e.g. `https://trends.google.com/trends/explore?q=bitcoin&geo=US`. Each link is one search with its own terms (up to 5, compared), location, time, category and search type, so the filters above don't apply to it. Data to extract, region level and Max rows do.

## `maxItems` (type: `integer`):

Stop after this many rows in total. Rows are free: you pay per keyword report (a search term with data), and a report cut short by this limit is still charged once. Leave empty for no limit. One search term with all three sections gives about 100–400 rows.

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

Proxy for requests to Google Trends. The default Apify datacenter proxy works well; switch to the RESIDENTIAL group only if runs report blocking. Without a proxy, Google shows a captcha to your IP after a few dozen requests.

## Actor input object example

```json
{
  "queries": [
    "coffee",
    "tea"
  ],
  "compareQueries": false,
  "timeRange": "past12Months",
  "dataTypes": [
    "interestOverTime",
    "interestByRegion",
    "relatedQueries"
  ],
  "property": "web",
  "regionResolution": "auto",
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

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

Dataset with all rows (all data types)

## `overview` (type: `string`):

Dataset overview table

# 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 = {
    "queries": [
        "coffee",
        "tea"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("genial_candlestand/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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "queries": [
        "coffee",
        "tea",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("genial_candlestand/google-trends-scraper").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 '{
  "queries": [
    "coffee",
    "tea"
  ]
}' |
apify call genial_candlestand/google-trends-scraper --silent --output-dataset

```

## MCP server setup

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

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/pU1ZIm8oBrgIQeIUq/builds/wQe5Jj4v7kLtuS3Wz/openapi.json