# Google Trends API: Reliable Interest, Regions & Related Queries (`appgild/google-trends-api`) Actor

Google Trends interest over time, interest by region and related queries and topics for up to 200 keywords a run, compared in groups of up to 5, with retries and a clear error row instead of a failed run. Pay per keyword. Google Trends data via DataForSEO.

- **URL**: https://apify.com/appgild/google-trends-api.md
- **Developed by:** [AppGild Team](https://apify.com/appgild) (community)
- **Categories:** AI, SEO tools
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$45.00 / 1,000 keyword checkeds

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 API: Reliable Interest, Regions & Related Queries

Google Trends data that comes back: interest over time, interest by region, and related queries and topics, for up to 200 keywords a run, compared in groups of up to 5 as on Google Trends. Each group is retried on a data-source error, and a group that still fails comes back as a clear error row, not charged, instead of failing the whole run.

**Tested for reliability:** 20 of 20 runs succeeded in testing on 2026-10-23, from 1 keyword to 200 (309 keywords in all), across all 5 properties, all 7 time ranges and 7 locations. No keyword failed.

**Simple pricing:** $0.045 per keyword checked, nothing per run start or per row. Checking 100 keywords costs $4.50.

Google Trends data via DataForSEO.

Not affiliated with or endorsed by Google. Google and Google Trends are trademarks of Google LLC.

### Who it is for

- **SEO and content teams** choosing topics and timing posts by seasonal interest.
- **Market researchers and analysts** comparing brands, products or categories over time and by region.
- **AI agents and automations** that need a trends signal as plain JSON.

### What you get

One row per keyword group:

| Field | What it means |
| --- | --- |
| `keywords` | The keywords compared in this row (1 to 5). |
| `status` | `ok`, or `failed` with an `error` (not charged). |
| `interestOverTime` | One point per step of the period: `date` (its start), `dateTo`, `values` (each keyword, 0 to 100) and `partial` (Google marks the step as incomplete, usually the latest). |
| `averageInterest` | Each keyword's average interest over the period. |
| `interestByRegion` | Interest by region: `geoId` (for example `US-TX`), `geoName`, and `values` per keyword. |
| `relatedQueries` | For a keyword checked on its own: the `top` and `rising` related searches, each `{title, value}`. |
| `relatedTopics` | For a keyword checked on its own: the `top` and `rising` related topics, each `{title, topicType, value}`. |
| `googleTrendsUrl` | The same comparison on Google Trends. |
| `location`, `language`, `property`, `timeRange` | What was checked. |
| `source`, `checkedAt` | `"Google Trends data via DataForSEO"`, and when it was checked (UTC). |

Interest is relative, as on Google Trends: 100 is the highest point of any keyword in the group during the period, and 0 means too little data. Compare numbers within a row, not across rows. Top related values are on the same 0 to 100 scale; rising values are the increase in percent, or `"Breakout"` for a very large one.

### Example output

One real row from a test run on 2026-10-23: "chatgpt" in the United States over the past 12 months, with every data type on. The timeline is cut to its first and last weeks (it has 53), and the regions and related lists to their first few. Keywords are search terms only; AppGild is not affiliated with the brands they name.

```json
{
  "keywords": [
    "chatgpt"
  ],
  "location": "United States",
  "language": "en",
  "property": "web",
  "timeRange": "past_12_months",
  "source": "Google Trends data via DataForSEO",
  "checkedAt": "2026-10-23T13:27:07.341Z",
  "status": "ok",
  "interestOverTime": [
    {
      "date": "2025-10-19",
      "dateTo": "2025-10-25",
      "values": {
        "chatgpt": 100
      },
      "partial": false
    },
    {
      "date": "2026-10-18",
      "dateTo": "2026-10-23",
      "values": {
        "chatgpt": 85
      },
      "partial": true
    }
  ],
  "averageInterest": {
    "chatgpt": 77.1
  },
  "interestByRegion": [
    {
      "geoId": "US-CA",
      "geoName": "California",
      "values": {
        "chatgpt": 100
      }
    },
    {
      "geoId": "US-WY",
      "geoName": "Wyoming",
      "values": {
        "chatgpt": 95
      }
    },
    {
      "geoId": "US-DC",
      "geoName": "District of Columbia",
      "values": {
        "chatgpt": 94
      }
    }
  ],
  "relatedQueries": {
    "top": [
      {
        "title": "what is chatgpt",
        "value": 100
      },
      {
        "title": "ai chatgpt",
        "value": 96
      },
      {
        "title": "openai",
        "value": 72
      }
    ],
    "rising": [
      {
        "title": "chatgpt caricature",
        "value": 3150
      },
      {
        "title": "how to use chatgpt effectively",
        "value": 2050
      }
    ]
  },
  "relatedTopics": {
    "top": [
      {
        "title": "ChatGPT",
        "topicType": "Topic",
        "value": 100
      },
      {
        "title": "OpenAI",
        "topicType": "Generative AI company",
        "value": 3
      },
      {
        "title": "OpenAI Codex",
        "topicType": "Language model",
        "value": 0
      }
    ],
    "rising": [
      {
        "title": "OpenAI Codex",
        "topicType": "Language model",
        "value": 1450
      },
      {
        "title": "OpenAI",
        "topicType": "Generative AI company",
        "value": 200
      }
    ]
  },
  "googleTrendsUrl": "https://trends.google.com/trends/explore?hl=en&geo=US&date=today%2012-m&q=chatgpt",
  "charged": true
}
```

### Input

- **Keywords**: one per line, each checked on its own. This is also how you get its related queries and topics.
- **Comparison groups**: one comparison per line, up to 5 keywords separated by commas (for example `chatgpt, gemini, claude`).
- **Location**: a country by name ("United States", "United Kingdom", "Germany"), a US state by name or code ("Texas", "TX"), or "Worldwide". Default: United States.
- **Time range**: past day, 7 days, 30 days, 90 days, 12 months (default) or 5 years, or custom start and end dates.
- **Property**: web search (default), news, images, shopping or YouTube.
- **Data**: interest over time (on by default), interest by region, related queries, related topics.
- **Language**: a language code (default `en`).

### Use from an AI agent / MCP

Agents can call this Actor as a tool through Apify's MCP server (`https://mcp.apify.com`) or the Apify API, by its ID `appgild/google-trends-api`. Every input has a default except the keywords themselves, and every row is plain JSON with the fields above.

```json
{
  "keywordGroups": ["chatgpt, gemini, claude"],
  "keywords": ["electric bike"],
  "location": "United States",
  "timeRange": "past_12_months",
  "interestOverTime": true,
  "interestByRegion": false,
  "relatedQueries": true,
  "relatedTopics": false
}
```

The results are the run's default dataset, one row per keyword group. The run's summary (keywords checked, failed and not checked, with its status message) is the `OUTPUT` record in the run's key-value store.

### Pricing

Pay per result: **$0.045 per keyword checked** (`keyword-checked`). A comparison group of 5 keywords is 5 checks. Twelve months of interest for 50 keywords is 50 checks, $2.25. There is no charge to start a run and none per row. Apify platform usage is billed to you as well.

You are charged only for keywords whose data came back. A group that fails at the data source after its retries is saved with its error and is not charged. Set a maximum charge on the run and the Actor stops before it would go over it.

### Limits

- Up to **200 keywords per run**, and up to 5 in a comparison group. A longer group is split into groups of 5; a longer list is cut, and the run's status message says how many were not checked or charged.
- **Related queries and topics** come per keyword: Google gives them for one keyword at a time, so they are filled for keywords checked on their own and left out of comparison groups.
- A run of up to 20 groups is checked right away, in seconds per group. A run with **more than 20 groups** goes to the data source's standard queue, which takes minutes instead of seconds, and its status message says so.
- **Daily capacity**: the Actor has a daily data budget shared by all its users. When it is used up, runs stop cleanly with a status message, charge nothing more, and work again after 00:00 UTC.
- Google Trends works from a sample of searches, so the same check repeated later can differ slightly.
- Rising lists for a narrow location or period can include odd or spam-like searches. They are reported as Google returns them, without filtering.

### Terms of use

By running this Actor you agree to the following.

- **As is.** The data is provided as is, without any warranty of accuracy, completeness or availability. Google Trends data is a sample of searches that changes over time, and nothing here is advice.
- **No competing search engine.** You may not use the data, or any part of it, to build or train a search engine, a search index, or any service that substitutes for one.
- **Your use is your responsibility.** You must comply with all laws that apply to you and with the terms of the platforms involved, including Apify and Google.
- **No affiliation.** Not affiliated with or endorsed by Google. Google and Google Trends are trademarks of Google LLC. Brands and products used as keywords in the examples are named only as search terms, with no affiliation or endorsement.
- **Limitation of liability.** To the extent the law allows, AppGild's total liability for any claim is limited to the amount you paid for the runs involved.
- **Indemnity.** You agree to hold Meridian Data LLC (AppGild) harmless from claims that arise from your use of the data in breach of these terms.
- **Support:** support@appgild.ai

Published by AppGild. AppGild is a brand of Meridian Data LLC, Washington, USA.

# Actor input Schema

## `keywords` (type: `array`):

One keyword per line, each checked on its own (a group of one), which is also how you get its related queries and topics. Up to 200 keywords a run across this list and the comparison groups. An empty list and no groups means nothing to check.

## `keywordGroups` (type: `array`):

One comparison per line: up to 5 keywords separated by commas (for example "chatgpt, gemini, claude"). Interest is relative within a group, as in Google Trends: 100 is the highest point of any keyword in the group for the period. A longer line is split into groups of 5.

## `location` (type: `string`):

A country by name ("United States", "United Kingdom", "Germany"), a US state by name or code ("Texas", "TX"), or "Worldwide".

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

The period to compare. Choose Custom to set your own start and end dates below.

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

Only for a custom time range: YYYY-MM-DD, 2004-01-01 or later for web search (2008-01-01 for the other properties).

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

Only for a custom time range: YYYY-MM-DD. Leave empty for today.

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

Which Google search the interest is measured on.

## `interestOverTime` (type: `boolean`):

The timeline of interest (0 to 100) for each keyword, plus each keyword's average over the period.

## `interestByRegion` (type: `boolean`):

Interest (0 to 100) by sub-region of the location: states of a country, or areas of a state.

## `relatedQueries` (type: `boolean`):

Top and rising related searches. Google Trends gives these per keyword, so they come for keywords checked on their own (the Keywords list, or a group of one).

## `relatedTopics` (type: `boolean`):

Top and rising related topics, per keyword, like related queries.

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

Language code for Google Trends (for example "en", "de", "es").

## Actor input object example

```json
{
  "keywords": [
    "chatgpt"
  ],
  "keywordGroups": [],
  "location": "United States",
  "timeRange": "past_12_months",
  "dateFrom": "",
  "dateTo": "",
  "property": "web",
  "interestOverTime": true,
  "interestByRegion": false,
  "relatedQueries": false,
  "relatedTopics": false,
  "language": "en"
}
```

# Actor output Schema

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

One row per keyword group: interest over time, average interest, interest by region, related queries and topics, or the error (not charged).

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

Counts for the run (requested, checked, failed, not checked) and its status message.

# 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 = {
    "keywords": [
        "chatgpt"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("appgild/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 = { "keywords": ["chatgpt"] }

# Run the Actor and wait for it to finish
run = client.actor("appgild/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 '{
  "keywords": [
    "chatgpt"
  ]
}' |
apify call appgild/google-trends-api --silent --output-dataset

```

## MCP server setup

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