# Google Trends API for AI agents (interest JSON, no API key)

When a user asks an agent to check keyword interest, compare search momentum, or pair trends with a live SERP, call machine-payable Google Trends endpoints that return interest_over_time JSON — no Google Cloud / Trends API key, settlement via x402 USDC on Base after three free evaluation calls.

When a user asks you to "is this keyword rising," "compare interest in X vs Y," "what are related rising queries," or "check momentum then show me the current SERP," you need structured Trends JSON — interest over time plus related queries. Not scraped trends.google.com HTML, and not a Google Cloud / unofficial Trends scraper key.

Marketplace for AI Agents exposes a machine-payable trends endpoint for this: GET /api/public/v1/google-trends turns one or more keywords into interest_over_time (plus related queries when returned). When the user also wants live Google organic results for the same keyword, GET /api/public/v1/trend-then-serp chains google-trends + google-search server-side. The first 3 calls per agent identity are free; after that each single-engine call costs $0.005 USDC on Base, settled over x402 with an X-PAYMENT header. Intents are priced $0.005 × steps.

## Endpoint contracts

| Endpoint | Required | Results key | Typical use |
| --- | --- | --- | --- |
| GET /api/public/v1/google-trends | q | interest_over_time | Keyword interest time series (+ related queries when returned) |
| GET /api/public/v1/trend-then-serp | q | results | Trends interest + live Google SERP in one intent |

google-trends required: q (trend query; comma-separated to compare up to 5 terms). Optional: geo (country code, e.g. US), date (time range, e.g. today 12-m), data_type (defaults to TIMESERIES).

trend-then-serp required: q (keyword to measure and search). Optional: geo and date (passed to Trends), gl (SERP country, defaults to us), hl (interface language, defaults to en). The intent chain is google-trends → google-search (2 steps). Intents cost $0.005 × steps — the 402 challenge advertises the chain and step count. One intent invocation consumes one free-tier call, not one per step.

The free tier is 3 successful calls total per agent identity (a hash of IP + User-Agent), shared across every endpoint on the marketplace — it is not 3 per endpoint. Settlement uses the x402 exact scheme on Base mainnet; append ?network=base-sepolia to the endpoint for testnet USDC and sandbox mock data. The gateway settles only on upstream 2xx — failed upstream calls are not charged.

- Listing: https://marketplaceforaiagents.com/listings/google-trends
- Listing: https://marketplaceforaiagents.com/listings/trend-then-serp
- Markdown twins: /agent/listings/google-trends.md, /agent/listings/trend-then-serp.md

## Minimal calls (free tier first)

Spend the 3 free evaluation calls before signing anything. These run on the free tier (if you still have quota) and return real JSON:

```bash
curl -si "https://marketplaceforaiagents.com/api/public/v1/google-trends?q=AI+agents"

curl -si "https://marketplaceforaiagents.com/api/public/v1/google-trends?q=x402,micropayments&geo=US&date=today+12-m"

curl -si "https://marketplaceforaiagents.com/api/public/v1/trend-then-serp?q=AI+agents&geo=US&gl=us&hl=en"
```

An interest_over_time series looks like this (illustrative — always trust the live JSON, not this sample):

```json
{
  "interest_over_time": [
    { "timestamp": "2026-01-01", "value": 42 }
  ],
  "related_queries": [
    { "query": "autonomous agents", "value": 100 }
  ]
}
```

Note: a 400 missing_required_parameters response does not consume a free call, and the discovery endpoints (/.well-known/x402, catalog.json, openapi.json) never consume free tier. Field names above are illustrative — cite only keys present in the live interest_over_time / related_queries JSON.

## What interest_over_time returns

Cite only fields present in the live JSON. Typical fields agents should expect when present:

- interest_over_time — time series of relative interest (timestamp/date + value when returned)
- related_queries / related_rising_queries — related or rising query strings with relative values when returned
- interest_by_region — regional interest breakdown when the upstream includes it
- search_parameters / search_metadata — echo of the engine query and status when returned

Never invent interest values, rising queries, or regional ranks. If a field is missing from a result, say so — do not fill gaps from training data. Trends values are relative interest indexes, not absolute search volumes — never claim a specific search-volume number unless the live JSON provides one.

## When to use trend-then-serp instead of google-trends alone

- google-trends alone — the user only asked about interest, momentum, or related rising queries
- google-search alone — the user only needs live citations / organic results (see the Google Search for agents learn post)
- trend-then-serp — the user asked whether a topic is rising AND wants the current SERP evidence in one call
- google-news / news-brief — the user wants recent coverage rather than interest indexes
- google-autocomplete — the user wants typeahead suggestions for a seed query (separate endpoint)

Prefer trend-then-serp when the user wants both momentum and live SERP evidence so you spend one free-tier slot instead of two single-engine calls. Intents cost $0.005 × steps (2 steps for this chain when both run); trust the live 402 for the billed chain.

```bash
# Momentum + live Google SERP in one intent
curl -si "https://marketplaceforaiagents.com/api/public/v1/trend-then-serp?q=AI+agents&geo=US&date=today+12-m&gl=us&hl=en"
```

## Paying after the free tier (x402 / USDC)

Once your identity has spent its 3 free calls, the same request returns HTTP 402 with an accepts[] payment requirement. Decode it, verify every field against your policy, sign the EIP-3009 USDC authorization, base64 the x402 payload, and resend with X-PAYMENT:

```json
{
  "x402Version": 1,
  "error": "payment_required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "5000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x05e82e03753c7bc99fb24d10a876cce53f24b7b7",
      "resource": "https://marketplaceforaiagents.com/api/public/v1/google-trends?q=AI+agents"
    }
  ]
}
```

- maxAmountRequired is 5000 atomic units = $0.005 USDC (6 decimals) per single-engine call. For trend-then-serp, trust accepts[0].amount / maxAmountRequired and extra.steps / extra.chain from the live 402 — do not hard-code the intent total.
- Allowlist payTo 0x05e82e03753c7bc99fb24d10a876cce53f24b7b7 and USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 before signing.
- Budget your spend before signing: see How AI agents budget x402 API calls (https://marketplaceforaiagents.com/learn/budget-x402-api-calls).
- Test the full payment path with zero real cost: see the Base Sepolia smoke test (https://marketplaceforaiagents.com/learn/x402-base-sepolia-smoke-test).
- A paid 200 carries the settlement receipt in X-PAYMENT-RESPONSE — store it for reconciliation. Settlement occurs only on upstream 2xx.
- Prefer the MCP server (https://marketplaceforaiagents.com/mcp) for discovery; payment is the auth, no OAuth.

Protocol background: x402 protocol explained. Free-tier mechanics: how the x402 free tier and agent identity work.

## Agent playbook (Grok Bot / Claude Cowork / Cursor)

- Interest / momentum asks → google-trends with a precise q; add geo/date only when the user specifies a country or window; comma-separate up to 5 terms to compare.
- Momentum + current SERP → trend-then-serp; pass gl/hl when the user wants a specific SERP locale.
- On 402, settle with x402 USDC — do not ask for a Google Cloud Trends key or scrape trends.google.com.
- Cite interest values and related queries only from the live interest_over_time / related_queries JSON; never invent volumes.
- Allowlist payTo 0x05e82e03753c7bc99fb24d10a876cce53f24b7b7 and USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 before signing.

| User ask | First call | Follow-up |
| --- | --- | --- |
| Is ‘AI agents’ rising? | google-trends?q=AI+agents | Cite interest_over_time + related_queries from live JSON |
| Compare x402 vs micropayments (US, 12m) | google-trends?q=x402,micropayments&geo=US&date=today+12-m | Report relative series only — no invented volumes |
| Is this keyword rising AND what’s ranking? | trend-then-serp?q=… | google-search alone if they only need citations |
| Related rising queries for a seed | google-trends?q=… | google-autocomplete for typeahead suggestions |
| News coverage instead of interest | google-news or news-brief | Skip trends |

## Related entrypoints

- Google Trends listing: https://marketplaceforaiagents.com/listings/google-trends
- Trend-then-SERP listing: https://marketplaceforaiagents.com/listings/trend-then-serp
- Markdown twins: /agent/listings/google-trends.md, /agent/listings/trend-then-serp.md
- x402 manifest: https://marketplaceforaiagents.com/.well-known/x402
- Catalog: https://marketplaceforaiagents.com/api/public/v1/catalog.json
- OpenAPI: https://marketplaceforaiagents.com/api/public/v1/openapi.json
- MCP: https://marketplaceforaiagents.com/mcp
- llms.txt: https://marketplaceforaiagents.com/llms.txt
- Marketplace: https://marketplaceforaiagents.com/marketplace
- Docs: https://marketplaceforaiagents.com/docs
- MCP + x402 guide: https://marketplaceforaiagents.com/learn/mcp-x402-marketplace
- How agents discover APIs: https://marketplaceforaiagents.com/learn/how-ai-agents-discover-apis
- Google Search for agents: https://marketplaceforaiagents.com/learn/google-search-api-for-agents
- Google News for agents: https://marketplaceforaiagents.com/learn/google-news-api-for-agents

Capability first, payment second — find the trends endpoint, prove it with free calls, then settle unpaid traffic with x402 USDC on Base.

Canonical HTML: https://marketplaceforaiagents.com/learn/google-trends-api-for-agents