# Google Trends API: interest over time, related queries (`pxdata/google-trends-api`) Actor

Google Trends as clean JSON: interest over time, by region, related queries and topics, compare up to 5 terms, trending now. No browser, no login. Rate-limit aware: backs off on 429 and never rotates IP to dodge it. Charged only for terms that fully succeed.

- **URL**: https://apify.com/pxdata/google-trends-api.md
- **Developed by:** [Marcio Motta](https://apify.com/pxdata) (community)
- **Categories:** SEO tools, Developer tools, Automation
- **Features:** Limited permissions
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.50 / 1,000 search term processeds

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 API: interest over time, related queries

Google Trends as clean JSON. Give it search terms and it returns, per term: the interest-over-time series (0-100), the ranking of regions, and the top and rising related queries. It can also compare up to 5 terms on one scale and list what is trending right now in a country.

It is a **pytrends alternative** for people who lost their script when the library was archived, and for teams that want Trends data in a pipeline without running a browser. It talks to the same internal endpoints the Trends website uses, over plain HTTP: no browser, no login, no cookie from you.

### Read this first: how it treats Google's rate limit

Google rate limits this endpoint hard. Most Trends scrapers react by rotating IP addresses until the 429 goes away. **This Actor does not.** When Google answers 429 (Too Many Requests) the Actor:

1. waits (20 s, then 40 s, 80 s... or the `Retry-After` Google sends), with random jitter;
2. retries on the **same** session and the same IP;
3. slows its own pace for the rest of the run;
4. after your configured number of retries, returns that term as `ok: false`, `errorCode: "RATE_LIMITED"`, **not charged**;
5. if several terms in a row are rate limited, stops and returns the rest as `SKIPPED` (not charged), instead of hammering Google.

The reason is Google's terms, which forbid bypassing protective measures. The price of staying on the right side is speed: expect roughly 30 to 60 seconds per term, not 3. If you need thousands of terms per hour, this is not the Actor for you.

### What you get

- **Interest over time**: date, 0-100 value, partial-period flag, plus average and peak.
- **Interest by region**: countries, states or cities ranked, with `geoCode`.
- **Related queries**: `top` and `rising` (with the Google "Breakout" flag).
- **Compare**: up to 5 terms per group on one shared 0-100 scale. Longer lists are cut into groups of 5.
- **Trending now**: the current trending searches of a country with approximate traffic, start time and news links, from Google's official RSS feed.
- **Filters**: country or region (`BR`, `US-CA`, `BR-SP`), period (past hour to 2004-present or custom dates), category, property (web, images, news, YouTube, Shopping), interface language.
- **Optional cache**: identical requests inside your TTL are served from your own key-value store, not sent to Google, and not charged.
- **Per-term errors**: one failed term never stops the run. It becomes a row with `ok: false` and a readable error.
- **Charged only for success.** See Pricing.

### Quick start

```json
{
  "terms": ["bitcoin", "iphone 17"],
  "geo": "BR",
  "timeRange": "today 3-m",
  "language": "pt-BR",
  "timezoneOffsetMinutes": 180
}
```

Output (real run, trimmed to the first and last entries of each list; one row per term):

```json
{
  "term": "bitcoin",
  "mode": "terms",
  "geo": "BR",
  "timeRange": "today 3-m",
  "category": 0,
  "property": "web",
  "language": "pt-BR",
  "comparedWith": [],
  "trendsUrl": "https://trends.google.com/trends/explore?q=bitcoin&hl=pt-BR&geo=BR&date=today+3-m",
  "timeline": [
    {
      "date": "2026-07-17",
      "label": "17 de jul. de 2026",
      "value": 39,
      "hasData": true,
      "isPartial": false
    },
    {
      "date": "2026-07-18",
      "label": "18 de jul. de 2026",
      "value": 38,
      "hasData": true,
      "isPartial": false
    },
    {
      "date": "2026-07-19",
      "label": "19 de jul. de 2026",
      "value": 52,
      "hasData": true,
      "isPartial": false
    },
    {
      "_": "... 89 more points ..."
    },
    {
      "date": "2026-10-17",
      "label": "17 de out. de 2026",
      "value": 33,
      "hasData": true,
      "isPartial": true
    }
  ],
  "average": 43.2,
  "peak": {
    "date": "2026-09-20",
    "value": 100
  },
  "resolution": "DAY",
  "regions": [
    {
      "geoCode": "BR-MT",
      "name": "Mato Grosso",
      "value": 100
    },
    {
      "geoCode": "BR-PA",
      "name": "Pará",
      "value": 64
    },
    {
      "geoCode": "BR-SC",
      "name": "Santa Catarina",
      "value": 60
    },
    {
      "_": "... 24 more regions ..."
    }
  ],
  "regionResolution": "REGION",
  "relatedQueries": {
    "top": [
      {
        "query": "bitcoin hoje",
        "value": 100,
        "display": "100",
        "breakout": false
      },
      {
        "query": "dolar",
        "value": 48,
        "display": "48",
        "breakout": false
      },
      {
        "query": "bitcoin dolar",
        "value": 47,
        "display": "47",
        "breakout": false
      }
    ],
    "rising": [
      {
        "query": "bitget login",
        "value": 27650,
        "display": "Aumento repentino",
        "breakout": true
      },
      {
        "query": "surfshark free",
        "value": 24400,
        "display": "Aumento repentino",
        "breakout": true
      }
    ]
  },
  "fromCache": false,
  "scrapedAt": "2026-10-17T11:56:23.197Z",
  "ok": true,
  "errorCode": null,
  "error": null
}
```

The `{"_": ...}` entries above are only abbreviations for this README; real rows contain every point. Full files are in the `exemplos` folder of the source.

`timeline[].value` is Google's relative index, 100 being the peak of that term in that geo and period. In terms mode each term has its own scale: 50 for one term and 50 for another does not mean the same volume. Use **compare** mode when you need to compare terms.

### Compare mode

```json
{ "mode": "compare", "terms": ["uber", "99", "indrive"], "geo": "BR", "timeRange": "today 3-m" }
```

Terms are sent to Google together, so the values share a scale (the biggest term peaks at 100, the others are relative to it). The output still has one row per term, with `comparedWith` listing the others.

### Trending now

```json
{ "mode": "trendingNow", "geo": "BR", "maxTrendingItems": 25 }
```

One row per trend, charged per row:

```json
{
  "mode": "trendingNow",
  "geo": "BR",
  "rank": 2,
  "title": "shanghai open",
  "approxTraffic": "200+",
  "approxTrafficMin": 200,
  "publishedAt": "2026-10-17T10:40:00.000Z",
  "pictureSource": "Sportscape Magazine",
  "news": [
    {
      "title": "Zverev Targets Shanghai Final As Jodar Faces Biggest Test Against Medvedev",
      "snippet": null,
      "url": "https://www.sportscapemagazine.com/blog/zverev-shanghai-final-jodar-medvedev-semifinal",
      "source": "Sportscape Magazine"
    }
  ],
  "trendsUrl": "https://trends.google.com/trends/explore?q=shanghai%20open&geo=BR&date=now%201-d",
  "scrapedAt": "2026-10-17T11:17:22.096Z",
  "ok": true,
  "errorCode": null,
  "error": null
}
```

This mode uses Google's public RSS feed (`/trending/rss`). Country level only, with whatever Google lists at that moment (about 10 trends in our tests), not a history.

### Input reference

| Field | What it does | Default |
|---|---|---|
| `mode` | `terms`, `compare` or `trendingNow` | `terms` |
| `terms` | Up to 500 search terms, duplicates removed | |
| `geo` | `BR`, `US`, `GB`..., or a region like `US-CA`, `BR-SP`. Empty is worldwide | worldwide |
| `timeRange` | `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`, `custom` | `today 12-m` |
| `startDate`, `endDate` | `YYYY-MM-DD`, with `custom` | |
| `category` | Google category ID (0 = all, 7 = Finance, 71 = Food & Drink...) | 0 |
| `property` | web (empty), `images`, `news`, `youtube`, `froogle` (Shopping) | web |
| `language` | `hl` for labels and formatted dates (`pt-BR`, `en-US`, `de-DE`...). Does not filter searches | `en-US` |
| `timezoneOffsetMinutes` | Minutes behind UTC, as Trends sends it (180 = Brasilia) | 0 |
| `blocks` | Any of `timeline`, `regions`, `relatedQueries`, `relatedTopics`. Each block is one more request to Google | first three |
| `regionResolution` | `COUNTRY`, `REGION`, `CITY`, `DMA` | automatic |
| `includeLowVolumeRegions` | List regions with very low volume | false |
| `maxTrendingItems` | Trending mode only | 50 |
| `cacheTtlHours` | 0 disables the cache | 0 |
| `minDelayMs` | Minimum wait between requests, plus random jitter. Floor 1000 | 2500 |
| `maxRetriesOn429` | Waits and retries on the same session | 4 |
| `stopAfterConsecutiveRateLimits` | Then the rest is `SKIPPED` | 3 |
| `proxyConfiguration` | Optional. One IP is kept for the whole run | off |

Tip: ask only for the blocks you need. Timeline alone is 2 requests per term, all three blocks are 4.

### Output fields

| Field | Meaning |
|---|---|
| `term`, `mode`, `geo`, `timeRange`, `category`, `property`, `language` | The query that produced the row |
| `comparedWith` | Other terms in the same compare group (empty otherwise) |
| `timeline[]` | `{date, label, value, hasData, isPartial}` |
| `average`, `peak` | Mean of the series and `{date, value}` of the maximum |
| `regions[]` | `{geoCode, name, value}`, highest first, zeros omitted |
| `relatedQueries` | `{top[], rising[]}` with `{query, value, display, breakout}` |
| `relatedTopics` | Same idea with `{title, type, mid}`. **See Known limits** |
| `warnings[]` | Non-fatal notes for the row |
| `trendsUrl` | Link to open the same query on the Trends website, to check a number by hand |
| `fromCache`, `cachedAt` | Cache information |
| `ok`, `errorCode`, `error` | `errorCode` is one of `RATE_LIMITED`, `HTTP_ERROR`, `NO_DATA`, `PARSE_ERROR`, `NETWORK`, `PARTIAL`, `SKIPPED` |
| `scrapedAt` | UTC time of collection |

A row with `PARTIAL` carries the data blocks that did arrive, with `ok: false` and no charge.

### Calling it from code

JavaScript:

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('pxdata/google-trends-api').call({
    terms: ['chatgpt', 'gemini'], geo: 'US', timeRange: 'today 12-m',
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
for (const item of items) console.log(item.term, item.ok, item.average, item.peak);
```

Python:

```python
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("pxdata/google-trends-api").call(
    run_input={"terms": ["dólar hoje"], "geo": "BR", "language": "pt-BR", "blocks": ["timeline"]}
)
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item["term"], item["average"], item.get("error"))
```

cURL (synchronous; keep the list short because a term takes up to a minute):

```bash
curl -X POST "https://api.apify.com/v2/acts/pxdata~google-trends-api/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"terms":["bitcoin"],"geo":"BR","blocks":["timeline"]}'
```

### Pricing

Pay per event. You pay for results.

| Event | Charged when | FREE | BRONZE | SILVER | GOLD |
|---|---|---|---|---|---|
| `keyword` | One term came back with every requested block | $0.006 | $0.005 | $0.004 | $0.0035 |
| `trend` | One row in trendingNow mode | $0.001 | $0.001 | $0.001 | $0.001 |

Apify also charges its standard `apify-actor-start` event once per run.

Not charged: terms that fail, are rate limited, skipped, or served from your cache. The price per term is the same whatever blocks you pick, so asking for fewer blocks only makes the run faster. 1,000 terms on BRONZE cost $5.00. Use "Maximum cost per run" in the Console as a hard cap.

### Rate limits and run time (measured)

Measured on Apify's own infrastructure over a 7-day soak test (17 to 24 October 2026): 258 runs of 10 terms each, three tasks every two hours. All 258 runs finished; they covered 2,556 term requests.

- **95.7% of terms came back complete** (2,446 of 2,556). 79 terms failed and 31 were skipped after repeated rate limiting. Failed and skipped terms are returned as rows with `ok: false` and are not charged.
- **Success rate fell during the week.** The first 90 runs reached 98.9%; the last 168 runs (about the final four days) reached about **94%**. Google answered 429 more often and for longer as the test went on. Plan for roughly 94 to 96% of terms succeeding, not 100%, and rerun the failed ones later.
- **Google answered 429 in 94% of runs** (2,086 rate-limited requests across 242 of 258 runs). The Actor waited and retried on the same session, and **96% of those requests recovered** after the retry (2,007 of 2,086). There were no other HTTP errors.
- **Median 56 seconds per term** with three blocks. Early in the week the median was lower (about 35 to 47 seconds); it rose as Google throttled more. Most of that time is deliberate waiting; a single term with one block is faster.
- Trending now (RSS) is a different endpoint and was not part of the soak.
- The 429 state belongs to the IP, not to the session. Google throttles by IP, so the numbers can change with how many other people use the same Apify IP range.

These are measurements from one week, not a service-level guarantee.

### Known limits

- **Related topics come back empty.** Google returns an empty `relatedTopics` list for every term we tried, with or without country. It appears to withhold that block from anonymous API sessions. It is off by default; if you ask for it, the row gets a warning. We do not try to pose as a browser to get it.
- **Not fast. Optimised for reliability, not for speed.** The median is about 56 seconds per term because the Actor respects Google's rate limit and never swaps IP. Do not use it for thousands of terms per hour.
- **Not every term succeeds.** About 94 to 96% of terms succeeded in the soak test. The rest are returned as `RATE_LIMITED` or `SKIPPED`, free of charge, and can be sent again in a later run.
- **Sampling.** Google computes Trends from a sample, so two identical queries can differ by a few points. Use `trendsUrl` to check a number by hand.
- **Short windows.** Past hour, 4 hours and day return minute or hour resolution and are the most likely to be rate limited.
- **Quota is not yours.** Google throttles by IP. If many people run this Actor from the same Apify IP range at the same time, everybody sees more 429s.
- **Not an official API.** It uses internal endpoints that Google can change. When that happens rows come back as `PARSE_ERROR` or `HTTP_ERROR`, nobody is charged, and the Actor will be updated.

### FAQ

**Why not rotate proxies like the other Trends actors?** Google's terms forbid bypassing protective measures, and a 429 is one. We accept a slower Actor to stay on the right side. Rows that cannot be fetched are free.

**Is the data the same as the Trends website?** Same source and same index. Open the `trendsUrl` of a row to compare.

**Why `average` and `peak`?** Common questions ("what was the high point?") answered without post-processing.

**Do I need to pass cookies or a login?** No. The Actor gets the same anonymous session cookie any visitor gets. You never provide credentials.

**Is it legal?** The technical ability to read an endpoint is not a legal green light. Google's terms of service apply, and so does what you do with the data. You are responsible for your use.

**What happens if my run hits the maximum cost?** Rows already produced stay. The rest are written as `SKIPPED`, not charged.

### Changelog

**1.0.0** First release. Interest over time, regions, related queries, compare (up to 5), trending now, optional cache, 429 backoff on the same session, adaptive pacing, per-term errors, pay per successful term.

### Support

Open an issue on the Actor page with your input and the run link. Reproducible cases come first.

# Actor input Schema

## `mode` (type: `string`):

terms: one item per term, each term analysed on its own scale (0-100). compare: terms are grouped in sets of up to 5 and compared on the SAME scale. trendingNow: what people are searching for right now in a country.

## `terms` (type: `array`):

One per line, up to 500. Ignored in trendingNow mode. Duplicates are removed.

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

ISO code: BR, US, GB, or a region like US-CA, BR-SP. Empty means worldwide (trendingNow uses US when empty).

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

Google presets, or custom with the two dates below. Short windows (past hour/4 hours) return minute-level data and are the most likely to be rate limited.

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

YYYY-MM-DD. Only for Period = Custom dates.

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

YYYY-MM-DD. Only for Period = Custom dates.

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

Google Trends category number. 0 is all categories. Examples: 7 Finance, 5 Computers & Electronics, 71 Food & Drink, 16 News, 18 Shopping, 3 Arts & Entertainment, 45 Health.

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

Where the searches happened.

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

Interface language for labels and formatted dates, e.g. en-US, pt-BR, es-419. It does not filter searches; use Country for that.

## `timezoneOffsetMinutes` (type: `integer`):

Minutes behind UTC, as the Trends site sends it. 180 = Brasilia, 0 = UTC, 300 = New York (winter).

## `blocks` (type: `array`):

Which data to fetch for each term (terms and compare modes). Each extra block is one more request to Google, so fewer blocks means faster and less chance of rate limiting. The price per term is the same. relatedTopics is experimental: Google currently returns an empty list to anonymous API sessions, so it is off by default and the item carries a warning when empty.

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

Granularity for the by-region block. Empty lets Google pick (country-wide geo gives states/regions; worldwide gives countries).

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

Also list regions with very little search volume.

## `maxTrendingItems` (type: `integer`):

trendingNow mode only.

## `cacheTtlHours` (type: `integer`):

0 disables. When set, an identical request (same terms, geo, period, blocks) answered within this window is served from your own named key-value store 'google-trends-cache', is not sent to Google and is not charged. Items served from cache have fromCache: true.

## `minDelayMs` (type: `integer`):

Plus 0-1.5 s of random jitter. Lowest allowed is 1000. The default is deliberately slow: this actor favours finishing over speed.

## `maxRetriesOn429` (type: `integer`):

Waits 20 s, 40 s, 80 s... (or Retry-After if Google sends it) and retries on the same session. The actor never changes IP or session to get around a 429.

## `stopAfterConsecutiveRateLimits` (type: `integer`):

If Google keeps answering 429 after all retries, the remaining terms are returned as SKIPPED (not charged) instead of hammering Google.

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

Optional. Normally not needed. If used, the same proxy IP is kept for the whole run.

## Actor input object example

```json
{
  "mode": "terms",
  "terms": [
    "bitcoin",
    "ethereum"
  ],
  "geo": "",
  "timeRange": "today 12-m",
  "category": 0,
  "property": "",
  "language": "en-US",
  "timezoneOffsetMinutes": 0,
  "blocks": [
    "timeline",
    "regions",
    "relatedQueries"
  ],
  "regionResolution": "",
  "includeLowVolumeRegions": false,
  "maxTrendingItems": 50,
  "cacheTtlHours": 0,
  "minDelayMs": 2500,
  "maxRetriesOn429": 4,
  "stopAfterConsecutiveRateLimits": 3,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

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

Dataset items with the Google Trends data for each term.

# 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 = {
    "terms": [
        "bitcoin",
        "ethereum"
    ],
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("pxdata/google-trends-api").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 = {
    "terms": [
        "bitcoin",
        "ethereum",
    ],
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("pxdata/google-trends-api").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 '{
  "terms": [
    "bitcoin",
    "ethereum"
  ],
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call pxdata/google-trends-api --silent --output-dataset

```

## MCP server setup

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

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/JuowVFST7oD51mhVM/builds/h9g903YebQ8LIdiAl/openapi.json
