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

Google Trends data for any search term: interest over time, interest by region, related queries and topics. Compare up to 5 terms. No proxies.

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

## Pricing

Pay per event + usage

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
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

Export Google Trends data for any search term or pasted Google Trends URL: **interest over time**, **interest by region**, **related queries** and **related topics** (top and rising), for any country, time range, category and Google property (Web, Images, News, Shopping, YouTube). You get flat rows ready for CSV, Excel, Google Sheets or your own code.

### Why this Actor

- **Compare up to 5 terms per query, all 4 panels in one charge.** One query returns the timeline, the regional breakdown and the top/rising related queries and topics for up to 5 compared terms. It costs **$0.015** on the Free plan and **$0.006** on Gold and above.
- **Priced per query, not per row.** When terms are compared in groups of 5, each term costs **$0.003** (Free) down to **$0.0012** (Gold+). **1,000 terms** in groups of 5 cost **$3.00** on Free and **$1.20** on Gold+, however many rows come back. A 12-month weekly timeline alone is about 53 rows per term.
- **No proxies, no start fee, no monthly rental.** No proxy setup and no blocked requests on your side. Apify platform usage is billed separately by Apify (at the default 256 MB a small run typically uses about $0.001–$0.003).
- **Paste Google Trends URLs.** Copy the address of any Google Trends explore page and the Actor reads its terms (`q`), country (`geo`), period (`date`), category (`cat`), property (`gprop`) and language (`hl`).
- **34 output fields**, including a stable row `id` for de-duplication, breakout flags, partial-bucket flags, period averages and "leading term" per region. Queries that return no data cost only a reduced **"query checked"** fee (see [Pricing](#pricing)).

### Compared with alternatives

Typical run: **100 search terms, all 4 panels** (terms compared in groups of 5 here = 20 queries).

| Alternative on Apify Store | Listed price per result (row) | 100 terms on Free | 100 terms on Gold | Platform usage extra? |
|---|---|---|---|---|
| Most-used Google Trends Actor (~14,100 users) | $0.003 Free, $0.0003 Gold, **$0.00015 Platinum, $0.0001 Diamond** | at least $0.30 + platform usage | at least $0.03 + platform usage ($0.015 Platinum, $0.01 Diamond) | Yes |
| Fast Google Trends Actor with "Trending now" (~2,300 users) | $0.002 Free / $0.0005 Gold + $0.02 per run | at least $0.22 | at least $0.07 | No |
| Flat-price Google Trends Actor (~1,130 users) | $0.025 on all plans + $0.025 per run | at least $2.53 | at least $2.53 | No |
| Interest, regions & queries Actor (~360 users) | $0.005 on all plans + $0.00005 per run | at least $0.50 + platform usage | at least $0.50 + platform usage | Yes |
| **This Actor** | **$0.015 Free / $0.006 Gold+ per query** (up to 5 terms, all 4 panels, any number of rows) | **$0.30** | **$0.12** (Platinum and Diamond pay the Gold price) | Yes (small: ~$0.001–$0.003 per run) |

Prices and user counts from public Apify Store listings, checked September 2026. "At least" assumes only one result per term. The other Actors charge per result (row), and one term with all 4 panels usually returns far more than one row: a 12-month weekly timeline alone is about 53 rows per term, plus regions and related lists. With just 10 rows per term, the four alternatives would cost at least $3.00 + platform usage, $2.02, $25.03 and $5.00 + platform usage on Free.

**Where we are not cheaper.** The most-used Actor is cheaper whenever a term returns only a few rows: on Gold below 4 rows per term ($0.0003 × 4 = $0.0012, our Gold price per term in groups of 5), on Platinum below 8 rows and on Diamond below 12 rows. That happens if you only need, say, a short regional list or a few related queries; with a full timeline it does not. On Free, one row per term costs the same as our per-term price. The fast alternative can also be cheaper for very small runs and offers "Trending now", which this Actor does not. If you turn off *Compare terms against each other*, each term is its own query and this Actor costs 5× more ($1.50 on Free, $0.60 on Gold for 100 terms). This Actor's price never depends on the number of rows.

### Not included

- **"Trending now" / daily trending searches.** This Actor covers the Google Trends Explore view (interest over time, by region, related queries and topics).
- **Absolute search volumes.** Google Trends only publishes relative 0–100 values. For monthly search volumes, CPC and keyword ideas use [Keyword Research Tool](https://apify.com/cheapapi/keyword-research-tool).
- **Google search results and rankings.** Use [Google SERP Scraper](https://apify.com/cheapapi/google-serp-scraper).
- **YouTube video search results.** The `youtube` property gives YouTube search *interest*; for the videos themselves use [YouTube Search Scraper](https://apify.com/cheapapi/youtube-search-scraper).
- **Topic IDs as input** (e.g. `/m/02vqfm`). Type the topic name as a search term instead.

### What data you get

Each row has a `recordType` that tells you which Google Trends panel it comes from.

| Data | One row per | Key fields |
|---|---|---|
| Interest over time | date bucket × search term | `date`, `dateTo`, `value` (0–100), `periodAverage`, `isPartial` |
| Interest by region | region × search term | `regionCode`, `regionName`, `value` (0–100), `isLeadingTerm`, `regionRank` |
| Related queries | query in the top / rising list | `listType`, `rank`, `query`, `value`, `isBreakout` |
| Related topics | topic in the top / rising list | `listType`, `rank`, `topicId`, `topicTitle`, `topicType`, `value`, `isBreakout` |

All output fields:

| Field | Type | Example |
|---|---|---|
| `id` | string | `c8eff4ce4b9fa3fa` (stable across runs for the same data point) |
| `recordType` | string | `interestOverTime`, `interestByRegion`, `relatedQuery`, `relatedTopic` |
| `searchTerm` | string | `coffee` |
| `comparedTerms` | string | `coffee, tea` |
| `country` | string | null | `US` (or `Worldwide`) |
| `location` | string | `United States` |
| `language` | string | `en` |
| `searchType` | string | `web`, `images`, `news`, `shopping`, `youtube` |
| `categoryId` | integer | `0` (all categories) |
| `timeRange` | string | `past12Months` or `custom` |
| `periodStart` / `periodEnd` | string | null | `2024-01-01` / `2024-12-31` (custom dates only) |
| `queryIndex` | integer | `1` |
| `sourceUrl` | string | null | Google Trends URL you pasted, `null` for search terms |
| `scrapedAt` | string | `2026-09-28T09:00:47.505Z` |
| `dataUpdatedAt` | string | `2026-09-26T15:24:02.000Z` |
| `date` / `dateTo` | string | `2025-09-21` / `2025-09-27` |
| `timestamp` | string | `2025-09-21T00:00:00.000Z` |
| `value` | number | null | `100` (0–100; percent increase in rising lists) |
| `periodAverage` | number | null | `92` |
| `isPartial` | boolean | `false` |
| `regionCode` / `regionName` | string | `US-MS` / `Mississippi` |
| `isLeadingTerm` | boolean | null | `true` |
| `regionRank` | integer | `2` |
| `listType` | string | `top` or `rising` |
| `rank` | integer | `1` |
| `query` | string | `matcha tea latte` |
| `topicId` / `topicTitle` / `topicType` | string | `/g/11x` / `Brown sugar oat latte` / `Drink` |
| `valueMeaning` | string | `relativeInterest` or `percentIncrease` |
| `isBreakout` | boolean | `true` when growth is above 5000% |

### How to use

#### In Apify Console

1. Open the Actor and go to the **Input** tab.
2. Enter your **Search terms** (e.g. `coffee`, `tea`), **or** paste one or more **Google Trends URLs** copied from your browser. If you only want the URLs, clear the prefilled terms first.
3. Pick a **Country** (e.g. `US`, or leave empty for worldwide) and a **Time range**. These apply to search terms; URLs keep their own settings.
4. Optional: open the **Advanced** sections to change grouping, panels, Google property, category, language, a state/city, custom dates or processing speed.
5. Optional: set **Maximum cost per run** in the run options to cap your spend.
6. Click **Start**. When the run finishes, open the **Output** tab and export as JSON, CSV, Excel, XML or HTML, or pick one of the table views (All rows, Interest over time, Interest by region, Related queries, Related topics).

#### Input JSON

```json
{
  "searchTerms": ["coffee", "tea", "matcha"],
  "trendsUrls": ["https://trends.google.com/trends/explore?date=today%205-y&geo=GB&q=oat%20milk,almond%20milk"],
  "country": "US",
  "timeRange": "past12Months"
}
```

This run makes 2 queries: `coffee, tea, matcha` compared in the US over the past 12 months, and `oat milk, almond milk` in the UK over the past 5 years (settings taken from the URL).

#### API: curl

```bash
curl -X POST "https://api.apify.com/v2/acts/cheapapi~google-trends-scraper-pro/run-sync-get-dataset-items?token=<YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"searchTerms": ["coffee", "tea"], "country": "US", "timeRange": "past12Months"}'
```

#### API: JavaScript (`apify-client`)

```js
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: '<YOUR_TOKEN>' });
const run = await client.actor('cheapapi/google-trends-scraper-pro').call({
    searchTerms: ['coffee', 'tea'],
    country: 'US',
    timeRange: 'past12Months',
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items.filter((r) => r.recordType === 'interestOverTime'));
```

#### API: Python (`apify-client`)

```python
from apify_client import ApifyClient

client = ApifyClient("<YOUR_TOKEN>")
run = client.actor("cheapapi/google-trends-scraper-pro").call(run_input={
    "trendsUrls": ["https://trends.google.com/trends/explore?geo=US&q=coffee,tea"],
})
for row in client.dataset(run["defaultDatasetId"]).iterate_items():
    if row["recordType"] == "relatedQuery":
        print(row["searchTerm"], row["listType"], row["rank"], row["query"], row["value"])
```

### Use cases

- **Content and SEO planning:** find rising related queries and "Breakout" topics before they peak.
- **Product and market research:** compare brands, products or features across countries and Google Shopping.
- **Seasonality analysis:** pull 5-year or since-2004 timelines to plan campaigns, stock and budgets.
- **Regional targeting:** see which states or countries show the most interest to focus ads and sales.
- **Dashboards and monitoring:** schedule weekly runs and feed Google Sheets, BI tools or a data warehouse.
- **Research and journalism:** reproduce a Google Trends chart you found by pasting its URL, and get the numbers behind it.

### Advanced options

| Option | Input field | Default | What it does |
|---|---|---|---|
| Google Trends URLs | `trendsUrls` | empty | Explore URLs to fetch. Each URL = 1 query with its own `q` (up to 5 terms), `geo`, `date`, `cat`, `gprop` and `hl`. Missing parameters use Google's defaults (worldwide, past 12 months, web, all categories). |
| Compare terms against each other | `compareTerms` | `true` | On: search terms are compared in groups of up to 5 (1 query per group). Off: each term is its own query on its own 0–100 scale. |
| Interest over time | `includeInterestOverTime` | `true` | Timeline of relative interest (0–100). |
| Interest by region | `includeInterestByRegion` | `true` | Interest per state/province (country searches) or per country (worldwide). |
| Related queries | `includeRelatedQueries` | `true` | Top and rising related search queries. |
| Related topics | `includeRelatedTopics` | `true` | Top and rising related topics (brands, people, places…). |
| Max related items per list | `maxRelatedItems` | `25` (1–100) | Keep the top N items of each top/rising list. |
| Google property | `searchType` | `web` | `web`, `images`, `news`, `shopping` or `youtube`. All 4 panels are available for `web`. News searches return interest over time only (see [Limitations](#limitations)). |
| Category ID | `categoryId` | `0` (all) | Google Trends category, e.g. `71` Food & Drink, `7` Finance, `18` Shopping. See [Category IDs](#category-ids) below. With a category and no terms you get the whole category's trend. |
| Language | `language` | `en` | ISO code for topic and category names. It does not change the numbers. |
| State / region / city (Google location ID) | `geoTargetId` | empty | Numeric Google location ID, e.g. `21167` = New York state. See [Locations](#locations-countries-states-and-cities) below. Overrides Country. |
| Custom start / end date | `dateFrom`, `dateTo` | empty | Any period since 2004-01-01 (web) or 2008-01-01 (other properties). Overrides Time range. |
| Processing speed | `processingSpeed` | `auto` | **Bronze and higher plans always use bulk mode** (a few minutes, up to ~45 min at peak times). On Free, Auto fetches up to 20 queries instantly and uses bulk mode for larger runs. Same price in every mode. |
| Max queries | `maxQueries` | no limit | Hard cap on the number of queries in a run. |

Supported URL `date` values include `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`, `all_2008`, other `today N-m` / `today N-y` / `now N-d` values, and custom ranges like `2024-01-01 2024-06-30`.

Example: Google Shopping interest in Germany, Food & Drink category, calendar year 2024, each term on its own scale, only the timeline and related queries.

```json
{
  "searchTerms": ["matcha", "chai latte", "cold brew"],
  "compareTerms": false,
  "country": "DE",
  "language": "de",
  "searchType": "shopping",
  "categoryId": 71,
  "dateFrom": "2024-01-01",
  "dateTo": "2024-12-31",
  "includeInterestByRegion": false,
  "includeRelatedTopics": false
}
```

#### Category IDs

Google Trends has 25 top-level categories and about 1,400 subcategories. The ID is the `cat=` number in a Google Trends URL. The easiest way to find a subcategory ID is to pick it on trends.google.com and copy `cat` from the address bar (or just paste the whole URL into *Google Trends URLs*).

| ID | Category | ID | Category |
|---|---|---|---|
| `0` | All categories (default) | `22` | Books & Literature |
| `3` | Arts & Entertainment | `29` | Real Estate |
| `5` | Computers & Electronics | `44` | Beauty & Fitness |
| `7` | Finance | `45` | Health |
| `8` | Games | `47` | Autos & Vehicles |
| `11` | Home & Garden | `65` | Hobbies & Leisure |
| `12` | Business & Industrial | `66` | Pets & Animals |
| `13` | Internet & Telecom | `67` | Travel |
| `14` | People & Society | `71` | Food & Drink |
| `16` | News | `174` | Science |
| `18` | Shopping | `299` | Online Communities |
| `19` | Law & Government | `533` | Reference |
| `20` | Sports | `958` | Jobs & Education |

Popular subcategories: `32` Software, `31` Programming, `78` Consumer Electronics, `107` Investing, `37` Banking, `276` Restaurants, `68` Apparel, `34` Movies, `294` Soccer, `1080` Real Estate Listings.

#### Locations: countries, states and cities

- **Country:** a 2-letter ISO code (`US`, `GB`, `DE`, `BR`…) or an English name (`Germany`). Leave it empty for worldwide data.
- **State, region or city:** set *State / region / city* (`geoTargetId`) to a numeric Google location ID. These are the public Google Ads geo target IDs, listed in Google's geo targets file at developers.google.com/google-ads/api/data/geotargets. Examples: `21167` New York state, `21137` California, `21176` Texas, `20339` England.
- **In the output:** `country` is the ISO code (or `Worldwide`), `location` the name. Interest-by-region rows use ISO 3166-2 codes in `regionCode` (`US-NY`, `GB-ENG`), or country codes for worldwide searches.
- **Pasted URLs:** the URL's `geo` is used. A country (`geo=DE`) works as is; a sub-region (`geo=US-NY`) falls back to the country, so use `geoTargetId` for regional data.

### Example output

```json
[
  {
    "id": "c8eff4ce4b9fa3fa",
    "recordType": "interestOverTime",
    "searchTerm": "coffee",
    "comparedTerms": "coffee, tea",
    "country": "US",
    "location": "United States",
    "language": "en",
    "searchType": "web",
    "categoryId": 0,
    "timeRange": "past12Months",
    "periodStart": null,
    "periodEnd": null,
    "queryIndex": 1,
    "sourceUrl": null,
    "scrapedAt": "2026-09-28T09:00:47.505Z",
    "dataUpdatedAt": "2026-09-26T15:24:02.000Z",
    "date": "2025-09-21",
    "dateTo": "2025-09-27",
    "timestamp": "2025-09-21T00:00:00.000Z",
    "value": 100,
    "periodAverage": 92,
    "isPartial": false
  },
  {
    "id": "8c5eda87cec1a4eb",
    "recordType": "interestByRegion",
    "searchTerm": "tea",
    "comparedTerms": "coffee, tea",
    "country": "US",
    "location": "United States",
    "regionCode": "US-MS",
    "regionName": "Mississippi",
    "value": 62,
    "isLeadingTerm": true,
    "regionRank": 2
  },
  {
    "id": "9405e3c1c9a78c0b",
    "recordType": "relatedQuery",
    "searchTerm": "tea",
    "comparedTerms": "coffee, tea",
    "listType": "rising",
    "rank": 1,
    "query": "matcha tea latte",
    "value": 1250,
    "valueMeaning": "percentIncrease",
    "isBreakout": false
  },
  {
    "id": "d9beb4240e792703",
    "recordType": "relatedTopic",
    "searchTerm": "coffee",
    "comparedTerms": "coffee, tea",
    "listType": "rising",
    "rank": 1,
    "topicId": "/g/11x",
    "topicTitle": "Brown sugar oat latte",
    "topicType": "Drink",
    "value": null,
    "valueMeaning": "percentIncrease",
    "isBreakout": true
  }
]
```

The context fields are left out of the last three rows to keep the example short. Every row has all of them. A `RUN_SUMMARY` record in the key-value store shows how many queries were delivered, empty, failed or not run, how many rows of each type were produced, and any problems. The dataset has 5 views: **All rows**, **Interest over time**, **Interest by region**, **Related queries** and **Related topics**. Each view shows the columns of one record type; all rows stay in the same dataset, so sort or filter by the *Type* column (or by `recordType` in your code) to see one type only.

### Pricing

**Typical cost: 100 search terms with all 4 panels = $0.30 on Free, $0.12 on Gold and above** (20 queries of 5 compared terms), plus Apify platform usage billed separately (about $0.001–$0.003 for a small run).

> **Speed depends on your Apify plan.** On **Bronze, Silver, Gold and higher plans every run uses slower bulk processing: results take a few minutes, and up to ~45 minutes at peak times.** The lower prices are only possible that way. On the Free plan, runs of up to 20 queries are fetched instantly (larger runs also use bulk processing).

**Apify Free plan:** Apify does not pay developers for usage on its Free plan, so on the Free plan this Actor can be used for up to **$0.25 of results per calendar month** — enough to try it on a small input. When the allowance is used up, the run ends with a clear message (not an error). Any paid Apify plan removes the limit; prices are the same.

Pay per event: you pay per query that delivered data. Apify platform usage is billed separately by Apify (at the default 256 MB a small run typically uses about $0.001–$0.003). Prices drop automatically on higher Apify plans (see the speed note above).

| Event | Free | Bronze | Silver | Gold, Platinum, Diamond |
|---|---|---|---|---|
| Trend query (up to 5 compared terms or 1 URL, all selected panels) | **$0.015** | $0.008 | $0.007 | **$0.006** |
| Cost per term when compared in groups of 5 | $0.003 | $0.0016 | $0.0014 | $0.0012 |
| 1,000 terms in groups of 5 (200 queries) | $3.00 | $1.60 | $1.40 | $1.20 |
| Query checked, no data (only when a query was processed but Google Trends had no data for it, or the answer was lost) | $0.014 | $0.0037 | $0.0037 | $0.0037 |

A **query** is one comparison group of up to 5 search terms, one term when comparison is off, one category-only lookup, or one pasted Google Trends URL. All 4 panels are included at no extra cost.

**Query checked fee.** Every query we send is processed and paid for, even when Google Trends has no data for it (tiny terms, narrow locations, very short ranges) or the answer never reaches us (a dropped connection or a bulk task that did not finish in time). Such a query delivers no rows and is charged only the reduced *query checked* fee instead of the full query price. Queries rejected before processing (invalid settings) are free. **Why is the Free-plan fee ($0.014) almost as high as a full query ($0.015)?** Free-plan runs of up to 20 queries are fetched instantly, and an instant query costs us almost the same to process whether or not Google Trends has data for it. The fee only covers that processing cost, so it stays close to the query price. Paid plans (Bronze and up) use bulk processing, which costs us much less, so their fee is only $0.0037. Tip for Free-plan users: check doubtful terms in your browser first, or compare them with a popular term, so the query returns data.

> **Each term on its own scale costs 5× more.** With *Compare terms against each other* turned off, every term is a separate query ($0.015 on Free, $0.006 on Gold+ per term) instead of sharing one query with 4 other terms. Keep comparison on (the default) unless you need independent 0–100 scales.

Worked examples (Free plan):

- **5 brands compared, all panels, 12 months:** 1 query = **$0.015**.
- **100 keywords for a seasonality study, compared in groups of 5 (default):** 20 queries = **$0.30** ($0.12 on Gold+).
- **The same 100 keywords, each on its own scale (comparison off):** 100 queries = **$1.50** ($0.60 on Gold+), 5× the grouped price.
- **10 niche keywords, comparison off, 3 have no data:** 7 × $0.015 + 3 × $0.014 = **$0.147** on Free (7 × $0.006 + 3 × $0.0037 = **$0.0531** on Gold+), plus Apify platform usage.

Set a **Maximum cost per run** in the run options. The Actor never starts a query that would go over it and stops cleanly when the limit is reached.

### De-duplicate or upsert with `id`

Every row has a stable `id`: the same week, region or related query for the same terms and settings gets the same `id` in every run. Use it as the primary key when you store results from scheduled runs.

```python
from apify_client import ApifyClient

client = ApifyClient("<YOUR_TOKEN>")
run = client.actor("cheapapi/google-trends-scraper-pro").call(run_input={"searchTerms": ["coffee", "tea"], "country": "US"})
store = {}  # replace with your database table keyed by id
for row in client.dataset(run["defaultDatasetId"]).iterate_items():
    is_new = row["id"] not in store
    store[row["id"]] = row  # upsert: insert new rows, refresh values of existing ones
    if is_new and row["recordType"] == "relatedQuery" and row["listType"] == "rising":
        print("New rising query:", row["query"])
```

In SQL: `INSERT ... ON CONFLICT (id) DO UPDATE SET value = EXCLUDED.value, "isPartial" = EXCLUDED."isPartial"`. The last timeline bucket is often partial (`isPartial: true`), so update existing rows instead of skipping them.

### Integrations

- **Google Sheets:** export the dataset directly, or use the Apify Google Sheets integration to append rows after each run.
- **Make and Zapier:** use the Apify app to start the Actor and send new rows to any of thousands of apps.
- **Webhooks:** get a POST request to your endpoint when a run succeeds or fails, then fetch the dataset.
- **Schedules:** run the same input daily or weekly (e.g. every Monday at 8:00) to monitor trends over time.
- **API and MCP:** call the Actor from the Apify REST API, the JavaScript or Python clients above, or AI agents through the Apify MCP server.

### FAQ

**Is there a limit on the Apify Free plan?** Yes: up to $0.25 of this Actor's results per calendar month, enough to try it. Apify pays developers nothing for Free-plan usage while our data costs are real, so this keeps the Actor sustainable. Runs that reach the allowance stop cleanly and keep everything collected so far; the allowance resets on the 1st of the month. Any paid Apify plan has no limit.

**Is it legal to scrape Google Trends?** Google Trends shows public, aggregated and anonymised statistics. It contains no personal data. Collecting publicly available data is generally legal, but you are responsible for how you use it. Check Google's terms and your local law, and ask a lawyer if you are unsure.

**How fresh is the data?** Data is collected from Google Trends when you run the Actor. `dataUpdatedAt` shows when the numbers were retrieved and `scrapedAt` shows when the row was written. Short ranges (past hour/day) are near real time. The last bucket of a timeline may be incomplete (`isPartial: true`).

**Why are the values between 0 and 100?** That is how Google Trends reports interest. 100 is the peak popularity within the chosen comparison, time range and location. Values are relative, not absolute search volumes. In rising lists `value` is the percent increase instead; when Google shows "Breakout" (growth above 5000%) we set `isBreakout: true` and `value: null`.

**Why do my numbers change when I compare different terms?** Values are scaled within each comparison group. To keep every term on its own scale, turn off *Compare terms against each other*. Each term then counts as one query, so the run costs 5× more than grouping terms in fives.

**Can I paste a Google Trends link instead of typing terms?** Yes. Paste it into *Google Trends URLs*. The terms, country, period, category, property and language come from the URL. Sub-regions in the URL (e.g. `geo=US-NY`) fall back to the whole country; use the *State / region / city* option for regional data instead. Topic IDs such as `/m/02vqfm` are skipped. Type the topic name as a search term instead.

**Why did I get fewer results than expected, or a "query checked" fee?** Low-volume terms, very short time ranges and narrow locations often have no data, or have empty related lists, on Google Trends too. Also check *Max related items per list*, *Max queries*, your maximum cost per run and the `RUN_SUMMARY` record. A *query checked* fee means one of your queries was processed but returned no data (Google Trends has nothing for that term, place or period), or its answer was lost on the way. Processing it still costs us, so it is charged the reduced fee ($0.014 on Free, $0.0037 on paid plans) instead of the full query price. `RUN_SUMMARY.queriesCheckedCharged` shows how many. To avoid it, compare low-volume terms with popular ones, widen the location or time range, and check a Google Trends URL in your browser first.

**How do I control my budget, and why is there a separate platform usage charge?** Set *Maximum cost per run* in the run options and/or *Max queries* in the input. Group terms in fives (the default) for the lowest cost per term. Apify bills the compute a run uses separately from the query price; at the default 256 MB a small run typically uses about $0.001–$0.003.

**Can I monitor trends automatically?** Yes. Save your input as a task, add a schedule (daily or weekly) and connect a webhook, Google Sheets, Make or Zapier to get every new run's rows. Every row has a stable `id`: the same week, region or related query gets the same `id` in every run, so you can upsert rows into a sheet or database and keep one row per data point. To see only new rising queries, keep the `id`s of `relatedQuery` rows from earlier runs and filter out the ones you have already seen. Each run is charged per query, so a weekly check of 5 terms costs $0.015 (Free) per week.

**Which export formats are available?** JSON, CSV, Excel, XML, HTML table and RSS from the Output tab or the dataset API. Rows are flat, so spreadsheets need no extra processing.

**Something is wrong. How do I get help?** Open an issue on the Actor's **Issues** tab with your run ID and the input you used. We read every issue and fix confirmed problems quickly.

### Limitations

- Google Trends data is relative (0–100) and sampled. Small terms often return no data, and repeated runs can differ slightly. That is how Google Trends works.
- Related queries and topics are often empty for short time ranges (past hour/day) or low-volume terms.
- Regional, related-query and related-topic data is available for Web searches. For **News** searches it is not available (confirmed in live tests): those queries return interest over time only (still one query charge), the log says so and `RUN_SUMMARY.panelsUnavailableFor` lists the property. For **Image, Shopping and YouTube** searches all 4 panels are requested, but this has not been verified in live tests; if Google Trends rejects the extra panels for a property, the Actor detects it during the run and falls back to interest over time for that property in the same way. Web queries in the same run are not affected.
- Pasted URLs: a sub-region `geo` (e.g. `US-NY`) falls back to the country, topic IDs are skipped, and only the first 5 terms are used.
- Bulk mode (all runs on Bronze and higher plans, large runs on Free) can take several minutes, up to about 45 minutes at peak times.
- "Trending now" / daily trending searches are out of scope (see [Not included](#not-included)). This Actor covers the Google Trends Explore view.

### Privacy

This Actor collects only aggregated, anonymised search-interest statistics published by Google Trends. It does not collect or output personal data. Your inputs and results are stored in your own Apify account and are not shared with anyone.

# Actor input Schema

## `searchTerms` (type: `array`):

Words or phrases to look up in Google Trends, e.g. <code>coffee</code>, <code>iphone 17</code>. Terms are compared in groups of up to 5 (Google Trends values are relative within a comparison) — change this under <b>Advanced: comparison & data</b>. Characters Google Trends rejects (such as <code>- + : ( ) "</code>) are replaced with spaces.

## `trendsUrls` (type: `array`):

Paste Google Trends explore URLs, e.g. <code>https://trends.google.com/trends/explore?date=today%205-y\&geo=US\&q=coffee,tea</code>. Each URL is one query and keeps exactly the settings from the URL: search terms (<code>q</code>, up to 5), country (<code>geo</code>), time range (<code>date</code>), category (<code>cat</code>), Google property (<code>gprop</code>) and language (<code>hl</code>). Anything the URL leaves out uses Google Trends' defaults (worldwide, past 12 months, web search, all categories) — the Country and Time range fields below apply to Search terms only.

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

2-letter country code (e.g. <code>US</code>, <code>GB</code>, <code>DE</code>) or English country name (e.g. <code>Germany</code>). Leave empty for worldwide data. Applies to Search terms (URLs carry their own <code>geo</code>).

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

Period to analyse for Search terms. Ignored when you set custom dates in the advanced options. URLs carry their own <code>date</code>.

## `compareTerms` (type: `boolean`):

On: terms are compared in groups of up to 5 (values are relative to the most popular term in the group, like the comparison view on Google Trends). Off: every term is looked up on its own (each term gets its own 0–100 scale; each term then counts as a separate query for pricing).

## `includeInterestOverTime` (type: `boolean`):

Timeline of relative search interest (0–100) for each term.

## `includeInterestByRegion` (type: `boolean`):

Relative interest per region (country-wide searches return states/provinces; worldwide searches return countries).

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

Top and rising related search queries for each term.

## `includeRelatedTopics` (type: `boolean`):

Top and rising related topics (entities such as brands, people, places) for each term.

## `maxRelatedItems` (type: `integer`):

Maximum number of items kept in each top/rising list of related queries and related topics.

## `searchType` (type: `string`):

Which Google search to analyse, like the 'Web search / Image search / News search / Google Shopping / YouTube search' switch on Google Trends.

## `categoryId` (type: `integer`):

Google Trends category to restrict the data to: the <code>cat=</code> number in a Google Trends URL. <code>0</code> = all categories. Examples: <code>71</code> Food & Drink, <code>7</code> Finance, <code>18</code> Shopping, <code>32</code> Software. The full list of top-level categories and popular subcategories is in the README (Category IDs). Tip: pick a category on trends.google.com and copy <code>cat</code> from the address bar. With a category and no search terms you get the trend of the whole category.

## `language` (type: `string`):

ISO language code (e.g. <code>en</code>, <code>de</code>, <code>es</code>, <code>pt-BR</code>) used for the names of related topics and categories. It does not change the interest numbers.

## `geoTargetId` (type: `integer`):

Optional. Numeric Google location ID (the public Google Ads geo target ID) of a state, region or city, e.g. <code>21167</code> New York state, <code>21137</code> California, <code>21176</code> Texas, <code>20339</code> England. The full list is Google's public geo targets file (developers.google.com/google-ads/api/data/geotargets). Overrides Country.

## `dateFrom` (type: `string`):

Optional start date (YYYY-MM-DD). Earliest: 2004-01-01 for web search, 2008-01-01 for other properties. When set, Time range is ignored.

## `dateTo` (type: `string`):

Optional end date (YYYY-MM-DD). Defaults to today when only a start date is given.

## `processingSpeed` (type: `string`):

<b>Bronze, Silver, Gold and higher Apify plans always use bulk processing</b>: results take a few minutes, up to ~45 minutes at peak times, whatever you pick here (their lower prices are only possible in bulk). On the Free plan, Auto fetches small runs (up to 20 queries) instantly and processes larger runs in bulk. The price is the same in every mode. A query that is processed but returns no data is charged only the reduced "query checked" fee.

## `maxQueries` (type: `integer`):

Optional cap on the number of queries in this run (one query = one comparison group of up to 5 terms, one term when comparison is off, or one Google Trends URL). Leave empty for no limit. You can also cap the spend with the run's maximum cost setting.

## Actor input object example

```json
{
  "searchTerms": [
    "coffee",
    "tea"
  ],
  "trendsUrls": [
    "https://trends.google.com/trends/explore?date=today%205-y&geo=GB&q=oat%20milk,almond%20milk"
  ],
  "country": "US",
  "timeRange": "past12Months",
  "compareTerms": true,
  "includeInterestOverTime": true,
  "includeInterestByRegion": true,
  "includeRelatedQueries": true,
  "includeRelatedTopics": true,
  "maxRelatedItems": 25,
  "searchType": "web",
  "categoryId": 0,
  "language": "en",
  "processingSpeed": "auto"
}
```

# Actor output Schema

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

No description

## `timeline` (type: `string`):

No description

## `regions` (type: `string`):

No description

## `relatedQueries` (type: `string`):

No description

## `relatedTopics` (type: `string`):

No description

## `summary` (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 = {
    "searchTerms": [
        "coffee",
        "tea"
    ],
    "country": "US",
    "timeRange": "past12Months",
    "searchType": "web"
};

// Run the Actor and wait for it to finish
const run = await client.actor("cheapapi/google-trends-scraper-pro").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 = {
    "searchTerms": [
        "coffee",
        "tea",
    ],
    "country": "US",
    "timeRange": "past12Months",
    "searchType": "web",
}

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

```

## MCP server setup

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

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/Te6f7AxddacJ3XnZg/builds/yJMW773SmzYZfcgog/openapi.json