# Google Trends Scraper: Interest Over Time, Regions & Related (`fairfetch/google-trends-scraper`) Actor

Reliable Google Trends scraper: interest over time, interest by region or city, related queries (top and rising), compare up to 5 terms, plus Trending Now. Retries with a new IP on every 429 and returns partial results instead of failing. $0.30 per 1,000 rows.

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

## Pricing

from $0.30 / 1,000 result rows

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Google Trends Scraper: Interest Over Time, Regions & Related

Get **Google Trends data as clean, flat rows**: interest over time, interest by region (country, state, metro or city), related queries (top and rising), comparisons of up to 5 terms on one scale, and the searches **trending now** in any country. No browser, no login, no API key.

Built for **reliability**. Google Trends rate-limits scrapers hard (HTTP 429), and that is why Google Trends runs so often time out or fail. This Actor is designed around it: it completes Google's cookie handshake, paces its requests, retries every throttled request on a **new residential IP**, keeps what it already has when one data type fails, and **never fails the whole run because of one term**. Every problem is explained per term in the run summary.

**Price: $0.30 per 1,000 rows** ($0.0003 per data point), Apify platform and proxy costs included. You pay only for rows you get.

### What you get

| `type` | One row is | Main fields |
|---|---|---|
| `interest_over_time` | One time point of one term (minute, hour, day, week or month) | `date`, `value` (0-100), `isPartial` |
| `interest_by_region` | One country, state, metro area or city for one term | `regionCode`, `regionName`, `value` |
| `related_query` | One related search, top or rising | `query`, `rankType`, `value`, `formattedValue` ("Breakout", "+250%") |
| `related_topic` | One related topic, top or rising. Optional, off by default: Google rarely sends topics to automated requests (see limits) | `query` (topic title), `topicType`, `topicId` |
| `trending_search` | One search trending now in a country | `query`, search volume, growth %, start time, categories, related searches |

Every row also has the `term`, all `comparedTerms` of the request, `geo`, `timeRange`, `category`, `property` and a `trendsUrl` that opens the same view on Google Trends, so the numbers can be checked and cited.

- **Any location**: worldwide, any country (`US`, `GB`, `DE`, `IN`, ...), regions (`US-CA`) and US metro areas.
- **Any time range**: past hour, 4 hours, day, 7 days, 30 days, 90 days, 12 months, 5 years, 2004 - present, or a custom date range.
- **Categories and search properties**: Web, News, Images, YouTube and Google Shopping search, any Google Trends category.
- **Comparisons**: up to 5 terms on one shared 0-100 scale, exactly like the Compare button.
- **Google Trends URLs** work as input: paste an explore URL and its settings are used.
- **Topic IDs** (e.g. `/m/02vqfm`) work as search terms.

### Why this Actor is reliable

- **New IP on every 429.** Each worker (up to 3 run in parallel) has its own proxy session, i.e. its own residential IP. When Google throttles a request, it is retried on a fresh IP within seconds, up to 6 times. The only longer wait (at most about a minute) happens when Google first has to accept a brand-new cookie.
- **Cookie handling that Google accepts.** Google answers the first request of a new visitor with HTTP 429 and a cookie; the Actor completes that handshake automatically. On IPs that Google watches, a brand-new cookie is refused for about a minute, so the Actor keeps cookies when it changes IPs and reuses a cookie Google already accepted instead of burning retries.
- **Polite pacing.** One request at a time per IP with a minimum gap, and a new IP after every 30 requests, so no single IP sends a burst.
- **Partial results instead of failures.** If, say, the region map of a term fails after all retries, you still get its interest over time and related queries; the summary says what is missing and why.
- **One bad term never stops the run.** Invalid input lines are reported and skipped. A run is marked failed only when nothing could be fetched because of a problem on our side (for example Google blocking every request); input mistakes end as succeeded, with the reason in the status message and the summary.
- **Expired tokens are refreshed.** Google's per-request tokens are renewed automatically if they expire during retries.
- **Survives platform migrations.** Progress is saved after every query. If Apify moves the run to another server, it resumes where it stopped: finished queries are neither fetched nor charged again.
- **Clean stop at your spending limit.** With a maximum cost per run (or `maxItems`), the Actor stops exactly at the limit: it sends no further requests (not even retries) and skips the remaining queries instead of fetching data you won't pay for. A query cut by the limit is marked `partial`, one with no rows saved `skipped`.
- **Fast health checks.** A typical query takes 4 requests and a few seconds; run time is capped so a run never runs into its timeout while waiting for Google.

### How to use

1. Add **Search terms** (one per line). Each term gets its own 0-100 scale.
2. To compare terms on one scale, add **Comparison groups**, e.g. `coffee, tea, matcha` (up to 5 terms per line).
3. Set **Location** (empty = worldwide), **Time range**, and optionally **Category** and **Search property**.
4. Choose the data: interest over time, interest by region (and its resolution), related queries (related topics are optional and usually empty), and whether you want top, rising or both.
5. Optional: turn on **Trending now** for a country.
6. Run it and download the dataset as JSON, CSV or Excel, or read it via API. The `SUMMARY` record in the run's key-value store lists every query with its status, rows per type, errors and notes.

#### Input example

The input of a real test run:

```json
{
  "searchTerms": ["coffee", "pickleball", "https://trends.google.com/trends/explore?q=bitcoin&geo=GB&date=now%207-d"],
  "comparisonGroups": ["chatgpt, gemini, claude"],
  "geo": "US",
  "timeRange": "today 12-m",
  "includeTrendingNow": true,
  "trendingGeo": "US"
}
```

It returned 1,010 rows: 50 trending searches; 154 rows each for `coffee` and `pickleball` (53 weeks, 51 states, 50 related queries); 207 rows for `bitcoin` in the UK over 7 days (hourly, from the URL's own settings); and 445 rows for the three-way comparison.

Other options: `"timeRange": "custom", "customTimeRange": "2024-01-01 2024-12-31"`, `"property": "youtube"`, `"category": 71`, `"regionResolution": "CITY"`, `"includeLowVolumeRegions": true`, `"relatedRanking": "rising"`, `"includeRelatedTopics": true`, `"trendingTimeRange": "4"`, `"trendingMaxItems": 100`, `"maxItems": 500`, `"language": "de"`.

#### Output examples

Real rows from the run above. The first one is complete; in the others, fields that are `null` for that type are left out to keep this page short (the dataset always has every field).

Interest over time:

```json
{
  "type": "interest_over_time",
  "term": "coffee",
  "comparedTerms": ["coffee"],
  "geo": "US",
  "timeRange": "today 12-m",
  "category": 0,
  "property": "web",
  "value": 60,
  "formattedValue": "60",
  "hasData": true,
  "date": "2025-10-12",
  "formattedDate": "Oct 12 – 18, 2025",
  "timestamp": 1760227200,
  "resolution": "WEEK",
  "isPartial": false,
  "regionCode": null,
  "regionName": null,
  "coordinates": null,
  "query": null,
  "topicType": null,
  "topicId": null,
  "rankType": null,
  "rank": null,
  "increasePercent": null,
  "endedAt": null,
  "isActive": null,
  "categories": null,
  "relatedQueries": null,
  "trendsUrl": "https://trends.google.com/trends/explore?date=today%2012-m&geo=US&q=coffee&hl=en-US",
  "scrapedAt": "2026-10-17T13:30:48Z"
}
```

Interest by region in a comparison (each term's share of the region, the three terms add up to 100%):

```json
{
  "type": "interest_by_region",
  "term": "chatgpt",
  "comparedTerms": ["chatgpt", "gemini", "claude"],
  "geo": "US",
  "timeRange": "today 12-m",
  "value": 58,
  "formattedValue": "58%",
  "hasData": true,
  "resolution": "REGION",
  "regionCode": "US-CA",
  "regionName": "California",
  "trendsUrl": "https://trends.google.com/trends/explore?date=today%2012-m&geo=US&q=chatgpt,gemini,claude&hl=en-US"
}
```

Related query, rising:

```json
{
  "type": "related_query",
  "term": "chatgpt",
  "comparedTerms": ["chatgpt", "gemini", "claude"],
  "geo": "US",
  "timeRange": "today 12-m",
  "query": "chatgpt caricature",
  "rankType": "rising",
  "rank": 1,
  "value": 3200,
  "formattedValue": "+3,200%"
}
```

Trending now (from a cloud run on 18 Oct 2026, related searches shortened):

```json
{
  "type": "trending_search",
  "geo": "US",
  "timeRange": "past 24 hours",
  "query": "texans vs jaguars",
  "rank": 1,
  "value": 500000,
  "formattedValue": "500K+",
  "increasePercent": 1000,
  "date": "2026-10-18T01:50:00Z",
  "isActive": true,
  "endedAt": null,
  "categories": ["Sports"],
  "relatedQueries": ["texans vs jaguars", "houston texans", "where to watch texans vs jacksonville jaguars", "wembley stadium", "nfl london games 2026"],
  "trendsUrl": "https://trends.google.com/trending?geo=US&hours=24&hl=en-US"
}
```

Related topic rows (when switched on and Google sends them) have `query` (topic title), `topicType` (e.g. "Beverage") and `topicId` (e.g. `/m/02vqfm`, usable as a search term). City rows have `regionName` and `coordinates` (`{"lat": ..., "lng": ...}`) instead of a `regionCode`.

#### Output fields

| Field | Description |
|---|---|
| `type` | `interest_over_time`, `interest_by_region`, `related_query`, `related_topic` or `trending_search` |
| `term`, `comparedTerms` | The term of this row, and all terms of the same request (their values share one scale) |
| `geo`, `timeRange`, `category`, `property` | Request settings (`geo` "" = worldwide; `property` web, news, images, youtube or shopping) |
| `value`, `formattedValue` | The number and how Google shows it (see "How to read the values") |
| `hasData` | `false` when Google has not enough data for that time point (value 0). Region rows always have data: regions without data are left out |
| `date`, `formattedDate`, `timestamp` | Start of the period in UTC (`YYYY-MM-DD`, or date-time for hourly / minute data), Google's label, Unix time. Trending: start of the trend |
| `resolution` | Time resolution (`MINUTE`, `EIGHT_MINUTE`, `HOUR`, `DAY`, `WEEK`, `MONTH`) or region resolution (`COUNTRY`, `REGION`, `DMA`, `CITY`) |
| `isPartial` | `true` for the current, still incomplete period |
| `regionCode`, `regionName`, `coordinates` | Region of a region row (cities have coordinates instead of a code) |
| `query`, `topicType`, `topicId` | Related query, related topic (title, type, ID) or trending search |
| `rankType`, `rank` | `top` or `rising`, and the position in the list (trending: position in Google's list) |
| `increasePercent`, `endedAt`, `isActive`, `categories`, `relatedQueries` | Trending searches: growth, end time (null while active), Google's categories, searches that belong to the trend |
| `trendsUrl` | Opens the same view on Google Trends |
| `scrapedAt` | When the run started (UTC) |

The dataset has the views **All rows**, **Trending now** and **All fields**. To work with one data type, filter by `type`.

### How to read the values

- Google Trends never shows search counts. **Interest over time** is relative: 100 is the peak for that request, 50 is half as popular, 0 means not enough data.
- Values of one request share a scale. Compare terms **inside one comparison group**; two separate runs (or two separate terms) are each scaled to their own peak. To compare more than 5 terms, use several groups that share one anchor term.
- **Interest by region**: single term, 100 is the region where the term has the largest share of all searches. In comparison groups, values are each term's share of the region (they add up to 100%).
- **Related queries / topics**: top lists are 0-100 relative to the most popular one; rising lists show the growth in percent, and "Breakout" means growth above 5,000%.
- **Trending now**: `value` is Google's approximate search volume (e.g. 200,000 shown as "200K+"), `increasePercent` the growth.
- The last point of a time series is usually the current period (`isPartial: true`); its value rises until the period ends.

### Pricing

Pay per event, no subscription and no extra usage fees:

| Event | Price |
|---|---|
| `result`: one row in the dataset (one data point of any type) | **$0.0003** ($0.30 per 1,000 rows) |
| Actor start (standard Apify event, per run) | $0.00005 |

Cost examples (row counts from our test runs):

| Request | Rows | Cost |
|---|---|---|
| 1 term, past 12 months, interest over time only | 53-54 (weekly points incl. the current week) | **$0.016** |
| 1 term, past 12 months, US, all default data types | about 155 (54 weeks, 51 states, 50 related queries) | $0.047 |
| 1 term, past 30 days, interest over time only | 31 (daily) | $0.009 |
| 3 terms compared, 12 months, US, all data types | about 445 | $0.13 |
| Trending now, one country, 50 trends | 50 | $0.015 |
| 10 terms, past 5 years, interest over time only | 2,610 (261 weeks each) | $0.78 |

To pay less, switch off the data types you don't need, choose top or rising only, or set **Max rows**.

What is never charged: regions where Google has no data (also with "include low search volume regions" on), a term whose whole time series has no data (a query with no data at all ends as `no_data` and costs nothing), empty related lists, failed or skipped queries and the `SUMMARY` record. If Google has data for a term at even one time point, its whole series is returned and charged, including points with value 0 and `hasData: false`; the summary notes how many points have data. Set **Maximum cost per run** in the run options (or `maxTotalChargeUsd` via API); the Actor stops cleanly at that amount and keeps everything fetched so far.

### Use it from the API, an app or an AI agent

Run synchronously and get the rows in one call (keep your own API token in the `APIFY_TOKEN` environment variable):

```bash
curl -X POST "https://api.apify.com/v2/acts/fairfetch~google-trends-scraper/run-sync-get-dataset-items?maxTotalChargeUsd=0.50" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"comparisonGroups": ["chatgpt, gemini, claude"], "geo": "US", "timeRange": "today 3-m", "includeInterestByRegion": false, "includeRelatedQueries": false}'
```

The Actor uses pay-per-event pricing without usage fees and limited permissions, so AI agents can call it through the Apify MCP server and pay per run. Tips for agents: put terms that must be compared in one comparison group, filter rows by `type`, check `SUMMARY.perQuery[].status` (`ok`, `partial`, `no_data`, `failed`, `skipped`) and `rowsPushed`, and cite `trendsUrl`.

### Performance and limits

- About 4 requests per term (5 with related topics, 1 for Trending now) and 5-15 KB of traffic. With the default proxy a query needs roughly 5-10 seconds (requests about one second apart); up to 3 queries run in parallel, each on its own IP.
- Google Trends compares at most 5 terms per request; bigger groups are reported as invalid input.
- Region resolution: countries for worldwide; regions, cities and (US only) metro areas inside a country. Not every combination has data, especially for YouTube or News search.
- Related topics are off by default. Google sends them to visitors it treats as regular users, but tags automated requests as scrapers and then returns an empty related-topics list, almost always (it was empty in every one of our cloud runs). Comparisons have no related-topics widget at all. Related queries are not affected. You can still switch topics on: empty lists cost nothing and are noted in the summary.
- Very rare terms, tiny regions and very short time ranges often have no data. When Google has no data at all for a query, it ends as `no_data` and nothing is charged. A rare term with data at only a few time points still returns (and charges) its whole series.
- At most 1,000 queries (search terms, URLs and comparison groups) per run; any beyond that are listed in the summary and not run.
- Without a proxy (e.g. local runs) all requests share one IP, so the Actor slows down to about 10 requests per minute and waits out throttling.

### FAQ

**Is there an official Google Trends API?**
Google has announced an official Trends API, but access has been limited to a small group of testers. This Actor needs no access approval: it reads the same data the Google Trends website shows.

**Why do I get 429 errors with other tools?**
Google Trends throttles quickly, especially cloud servers. This Actor uses residential IPs, completes Google's cookie handshake, paces requests and retries throttled requests on a new IP. You can see how often that happened in `SUMMARY` (`throttledResponses`, `ipRotations`).

**Why are the values different from yesterday's run?**
Google computes Trends from a sample of searches, so values can change slightly between requests, and every request is scaled to its own peak. Compare terms inside one comparison group.

**Can I get absolute search volumes?**
No. Google Trends only publishes relative interest (0-100). Trending now has Google's approximate search volume per trend.

**Can I compare more than 5 terms?**
Not in one request. Use several comparison groups that all contain the same anchor term and rescale them against it.

**What do "Breakout" and "+250%" mean?**
They are rising related queries or topics: "+250%" means searches grew by 250% compared with the previous period; "Breakout" means more than 5,000%.

**Which time zone are dates in?**
UTC. Daily, weekly and monthly points are dated by the start of the period.

**What happens if a term fails?**
The other terms still run. The failed term, the reason (for example "HTTP 429 ... gave up after 7 attempts") and anything that was still fetched are in the `SUMMARY` record and the status message. Failed terms are not charged.

**Do I need a proxy?**
It's on by default and included in the price (Apify residential proxy). Turning it off is only advised for local test runs.

### Legal

This Actor reads aggregated, anonymous statistics that Google Trends shows publicly to every visitor. It does not log in, does not bypass any login or paywall and collects no data about Google users. Search terms that Google lists (related queries, trending searches) are free text and can contain names of people in the news; handle them with care. Google and Google Trends are trademarks of Google LLC; this Actor is independent and not affiliated with or endorsed by Google. You are responsible for how you use the data and for complying with Google's terms and the laws that apply to you.

# Actor input Schema

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

One term per line; each term is fetched on its own (its own 0-100 scale). Commas also separate terms, as on Google Trends.

- Plain terms: coffee, iphone 17
- Topic IDs: /m/02vqfm (the Coffee topic)
- Google Trends explore URLs, e.g. https://trends.google.com/trends/explore?q=coffee,tea\&geo=US\&date=today%205-y. Location, time range, category and property in the URL override the fields below for that URL.

## `comparisonGroups` (type: `array`):

One group per line, terms separated by commas, e.g. "coffee, tea, matcha". Terms in a group are compared on one shared 0-100 scale, exactly like the Compare button on Google Trends. Google allows at most 5 terms per group.

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

Two-letter country code (US, GB, DE, IN, ...), a region code (US-CA, GB-SCT) or a US metro code (US-NY-501). Leave empty for worldwide.

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

Google Trends time range (Past 12 months when left empty). The time range also sets the resolution: minutes for the past hour / 4 hours, 8 minutes for the past day, hours for 7 days, days for 30 / 90 days, weeks for 12 months / 5 years, months for 2004 - present. Choose "Custom" to use the custom range below.

## `customTimeRange` (type: `string`):

Start and end date as "YYYY-MM-DD YYYY-MM-DD" (e.g. "2024-01-01 2024-12-31"), or hours within the past week as "2026-10-15T10 2026-10-16T10". Used only when Time range is Custom (or not set at all, e.g. in an API call).

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

Google Trends category ID; 0 = all categories. Common IDs: 3 Arts & Entertainment, 5 Computers & Electronics, 7 Finance, 12 Business & Industrial, 16 News, 18 Shopping, 20 Sports, 44 Beauty & Fitness, 45 Health, 47 Autos & Vehicles, 67 Travel, 71 Food & Drink, 174 Science. The ID is the cat= value in a Google Trends URL.

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

Which Google search to measure, like the "Web Search" menu on Google Trends.

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

One row per time point and term (value 0-100).

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

One row per region (country, state or city) and term. Single terms: 0-100 per region. Comparison groups: each term's share of the region (the terms add up to 100%). Regions without data are never returned and never charged.

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

Auto uses Google's default: countries for worldwide, states / regions for a country. City works for countries and regions; Metro (DMA) only for the US.

## `includeLowVolumeRegions` (type: `boolean`):

Like the checkbox on Google Trends: also return regions with low search volume (more rows). Regions where Google has no data at all are still skipped and not charged.

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

Up to 25 top and 25 rising related searches per term.

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

Up to 25 top and 25 rising related topics per term (single terms only). Off by default because the list is usually empty: Google sends related topics to automated requests only rarely. Empty lists cost nothing. Related queries are not affected.

## `relatedRanking` (type: `string`):

Return the Top list, the Rising list (fastest-growing, including "Breakout"), or both.

## `includeTrendingNow` (type: `boolean`):

Also return the searches trending right now in a country (the trends.google.com/trending list): search volume, growth, start time, categories and related searches. Works without search terms.

## `trendingGeo` (type: `string`):

Two-letter country code (or region code such as US-CA). Defaults to Location (a US metro code is cut to its state, e.g. US-NY-501 to US-NY), or US when Location is worldwide.

## `trendingTimeRange` (type: `string`):

Trends started within this window.

## `trendingMaxItems` (type: `integer`):

Google often lists several hundred trends for a big country. Returns the first N in Google's order; 0 = all.

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

Stop after this many dataset rows in total (each row is one charged result). 0 = no limit. You can also set a maximum cost per run in the run options.

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

On by default (Apify residential proxy, included in the price). Google Trends rate-limits cloud and datacenter IPs hard; every throttled request is retried on a new residential IP. Runs use only a few KB of proxy traffic per term.

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

Language for region names, topic titles and date labels (hl parameter), e.g. en-US, de, fr, pt-BR, ja.

## `maxConcurrency` (type: `integer`):

How many queries run at the same time, each on its own proxy IP. Without a proxy everything runs one by one.

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

Retries for throttling (HTTP 429, each on a new IP), server errors and network errors.

## `requestTimeoutSecs` (type: `integer`):

Timeout for a single HTTP request.

## Actor input object example

```json
{
  "searchTerms": [
    "coffee",
    "matcha",
    "https://trends.google.com/trends/explore?q=bitcoin&geo=GB&date=now%207-d"
  ],
  "comparisonGroups": [
    "coffee, tea, matcha",
    "chatgpt, gemini, claude"
  ],
  "geo": "US",
  "timeRange": "today 12-m",
  "category": 0,
  "property": "web",
  "includeInterestOverTime": true,
  "includeInterestByRegion": true,
  "regionResolution": "auto",
  "includeLowVolumeRegions": false,
  "includeRelatedQueries": true,
  "includeRelatedTopics": false,
  "relatedRanking": "both",
  "includeTrendingNow": false,
  "trendingTimeRange": "24",
  "trendingMaxItems": 50,
  "maxItems": 0,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  },
  "language": "en-US",
  "maxConcurrency": 3,
  "maxRetries": 6,
  "requestTimeoutSecs": 25
}
```

# Actor output Schema

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

All rows as JSON: interest over time, interest by region, related queries, related topics and trending searches.

## `trending` (type: `string`):

The same rows in the "Trending now" view (rank, trend, searches, growth, categories).

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

Per-query status (ok, partial, no_data, failed), rows per type, errors, notes, HTTP and IP-rotation statistics.

# 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"
    ],
    "geo": "US",
    "timeRange": "today 12-m",
    "includeRelatedTopics": false,
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("fairfetch/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 = {
    "searchTerms": ["coffee"],
    "geo": "US",
    "timeRange": "today 12-m",
    "includeRelatedTopics": False,
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("fairfetch/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 '{
  "searchTerms": [
    "coffee"
  ],
  "geo": "US",
  "timeRange": "today 12-m",
  "includeRelatedTopics": false,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}' |
apify call fairfetch/google-trends-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,fairfetch/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/duTQT9C06fgIEEuAS/builds/ETxLfIFpGAd76fVUK/openapi.json