Google Trends API

catalyst-labs/google-trends-api

catalyst-labs--google-trends-api

Destructive

This tool calls the Actor "catalyst-labs/google-trends-api" and retrieves its output results. Actor description: Tested Oct 25, 2026: 39/39 keywords returned Google Trends data, vs 0/40 for apify/google-trends-scraper; values match Google within 3 points. Interest over time, regions, related queries as JSON. Low-volume terms return NO_DATA, never zeros. $0.0025/keyword.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "catalyst-labs--google-trends-api"
  }
}

Input Schema

Name	Required	Description	Default
`geo`	No	Country or region code, e.g. `US`, `GB`, `US-IA`. Empty = worldwide.
`compare`	No	On: keywords share one 0-100 scale (Google's comparison mode, groups of 5). Off: each keyword is scaled on its own. Example values: true
`category`	No	Google Trends category ID (0 = all categories).
`keywords`	No	Search terms (max 25). With compare on, each group of up to 5 is fetched together so values are on one shared 0-100 scale. Example values: ["chatgpt","claude"]
`language`	No	Language for region and topic names, e.g. en-US, de. Example values: "en-US"	en-US
`property`	No	Which Google search to measure. Default web. Example values: "web"	web
`sections`	No	What to fetch: `timeline` (interest over time + summary), `regions` (interest by region), `related` (related queries and topics, top and rising). Fewer sections = faster. Example values: ["timeline","regions","related"]
`waitSecs`	No	Max seconds (0–45, default 30) to cap the wait for the Actor run to reach terminal state. For long-running Actors the response returns at the cap with the current run status; follow `nextStep` to poll via get-actor-run. Set to 0 to fire-and-forget.
`timeRange`	No	Window: 1h, 4h, 1d, 7d, 30d, 90d, 12m (default), 5y, all (2004-). Custom: "YYYY-MM-DD YYYY-MM-DD" via API. Example values: "12m"	12m
`maxRegions`	No	Top regions to return per keyword. Default 15. Example values: 15
`maxRelated`	No	Items per related list (top and rising, queries and topics). Default 10. Example values: 10
`outputMode`	No	`full` includes every timeline point; `summary` drops the points and keeps latest/peak/average/changePct/trend to save tokens. Same price. Example values: "full"	full
`referrer_id`	No	Referral code from another user's receipt (ref_...). They earn 10% of this run's price as credit.
`buyerPublicKey`	No	Base64 Ed25519 public key (SPKI). Lets you sign a useful/not useful verdict on this run's receipt for 5% off your next run.

Output Schema

Name	Required	Description
`tip`	No	Advisory guidance RAG Web Browser wrote to its key-value store under the reserved "TIP" key
`runId`	Yes	Actor run ID
`stats`	No	Run statistics
`status`	Yes	Run status: READY \| RUNNING \| TIMING-OUT \| TIMED-OUT \| ABORTING \| ABORTED \| SUCCEEDED \| FAILED
`actorId`	Yes	Stable Apify Actor ID from the run record
`summary`	Yes	Past-tense summary of the run state
`exitCode`	No	Actor process exit code; populated for terminal states (especially FAILED)
`nextStep`	Yes	One primary follow-up action with identifiers interpolated
`storages`	Yes	Dataset and key-value store metadata, keyed by alias. "default" is always the primary entry.
`actorName`	No	"username/actor-name"
`startedAt`	No	ISO timestamp when the run started
`finishedAt`	No	ISO timestamp when the run finished (terminal states only)
`statusMessage`	No	Pass-through from Apify run.statusMessage
`apifyConsoleUrl`	No	Personalized Apify Console link to the run; present only for Console sessions

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 26, 2026

addedOutput schema / properties / storages / properties / datasets / properties / default / properties / itemsSchema

Added value: +{
+  "description": "JSON Schema for rows in the dataset at `storages.datasets.default.id` — describes row shape only; the rows themselves are NOT returned inline in this response. Inferred from this Actor's historical successful runs. To fetch actual rows, call `get-dataset-items` with the dataset id and a `fields` projection drawn from this schema.",
+  "properties": {
+    "charged": {
+      "type": "boolean"
+    },
+    "comparedWith": {
+      "items": {},
+      "type": "array"
+    },
+    "errorCode": {
+      "type": "null"
+    },
+    "errorMessage": {
+      "type": "null"
+    },
+    "fetchedAt": {
+      "type": "string"
+    },
+    "geo": {
+      "type": "string"
+    },
+    "hint": {
+      "type": "null"
+    },
+    "interestByRegion": {
+      "type": "null"
+    },
+    "interestOverTime": {
+      "items": {
+        "properties": {
+          "date": {
+            "type": "string"
+          },
+          "partial": {
+            "type": "boolean"
+          },
+          "value": {
+            "type": "number"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "isPartial": {
+      "type": "boolean"
+    },
+    "keyword": {
+      "type": "string"
+    },
+    "normalization": {
+      "type": "string"
+    },
+    "outcome": {
+      "type": "string"
+    },
+    "property": {
+      "type": "string"
+    },
+    "receipt_key": {
+      "type": "string"
+    },
+    "receipt_verify_url": {
+      "type": "string"
+    },
+    "referral_code": {
+      "type": "string"
+    },
+    "relatedQueries": {
+      "type": "null"
+    },
+    "relatedTopics": {
+      "type": "null"
+    },
+    "retryable": {
+      "type": "boolean"
+    },
+    "sourceUrl": {
+      "type": "string"
+    },
+    "status": {
+      "type": "string"
+    },
+    "summary": {
+      "properties": {
+        "average": {
+          "type": "number"
+        },
+        "changePct": {
+          "type": "number"
+        },
+        "latest": {
+          "type": "number"
+        },
+        "peak": {
+          "type": "number"
+        },
+        "peakDate": {
+          "type": "string"
+        },
+        "points": {
+          "type": "number"
+        },
+        "trend": {
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "timeRange": {
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

Changed2 schema fields changedOct 26, 2026

addedInput schema / properties / buyerPublicKey

Added value: +{
+  "description": "Base64 Ed25519 public key (SPKI). Lets you sign a useful/not useful verdict on this run's receipt for 5% off your next run.",
+  "title": "Your verdict public key (optional)",
+  "type": "string"
+}

addedInput schema / properties / referrer_id

Added value: +{
+  "description": "Referral code from another user's receipt (ref_...). They earn 10% of this run's price as credit.",
+  "title": "Referral code (optional)",
+  "type": "string"
+}

First observedOct 25, 2026

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With annotations already declaring write/open-world behavior, the description still adds real behavioral context: per-keyword pricing ($0.0025/keyword), NO_DATA instead of zeros for low-volume terms, and dated accuracy evidence versus a competitor. It stops short of stating plainly that every invocation kicks off a billable Actor run and may return partially-complete results at the waitSecs cap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Compact and mostly front-loaded, with the useful data-quality and pricing facts up front. The framing sentence restating that it calls an Actor and retrieves results is redundant with the name and costs a little space, and the 'Tested Oct 25, 2026' marketing line reads as promotional rather than operational.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 14-parameter tool with a full output schema, the description covers the essentials an agent cannot get from structured fields: cost, NO_DATA behavior, and output shapes. The remaining gap is run lifecycle semantics — whether a call starts a new billable run and how to recover results after the wait cap — which is only partially implied by the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% across all 14 parameters, so fields like sections, compare, timeRange and waitSecs are already fully explained in the schema (including the nextStep polling note). The description contributes no parameter-level detail, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the concrete resource and outputs: interest over time, regions, and related queries returned as JSON, so an agent knows exactly what it gets. The opening meta-sentence ('calls the Actor ... and retrieves its output results') is boilerplate, and it never distinguishes itself from the sibling get-dataset-items / get-actor-run tools that also surface Actor output.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implicit: a trends/keyword-research task is the obvious fit, and the comparison against apify/google-trends-scraper implies 'prefer this one for reliability.' But there is no explicit when-to-use, when-not-to-use, or routing to siblings (e.g. what to do when waitSecs caps and the run is still pending, which only the schema hints at via get-actor-run).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Google Trends API tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.