La tabla que verá el cliente en Apify, definida por Argon (13 columnas):

keywords · geo · timeRange · category · property · timeline · regions · relatedQueries · relatedTopics · exploreUrl · fetchedAt · source · attribution

Apify Store Listing Copy — google-trends

1. Title (<= 60 characters)

Google Trends Explorer: Timeline, Regions & Queries (51 characters)

2. Short Description (<= 1000 characters)

Extract public Google Trends data including Interest Over Time (timeline), regional breakdown, and related queries or topics for single or compared keywords. Includes automatic HTTP 429 backoff, session rotation, and Apify Proxy support. Data source: Google Trends (https://www.google.com/trends). (298 characters)

3. Long Description

Google Trends Explorer: Timeline, Regions & Queries extracts structured public metadata from Google Trends without headless browser overhead. Designed for SEO teams, market researchers, data journalists, and autonomous AI agents, it queries Google Trends' public JSON widget endpoints (/trends/api/explore, /trends/api/widgetdata/multiline, /trends/api/widgetdata/comparedgeo, and /trends/api/widgetdata/relatedsearches) in strict compliance with trends.google.com/robots.txt.

Key Capabilities

• Interest Over Time (includeTimeline): Clean UTC ISO-8601 time series normalized to Google Trends' 0–100 scale across presets (now 1-H, now 7-d, today 3-m, today 12-m, today 5-y, all) or custom "YYYY-MM-DD YYYY-MM-DD" date ranges.
• Regional Breakdown (includeRegions): Subregion, state, or country-level interest scores (geoCode, geoName, value).
• Related Queries & Topics (includeRelated): Both top and rising (breakout) queries and Knowledge Graph topics (mid, title, type, formattedValue).
• Single or Comparative Mode (compare): Analyze keywords individually or compare up to 5 terms per group on a shared scale.
• Resilient HTTP 429 Recovery & Apify Proxy Support: Polite rate limiting (>= 1.5s interval), automatic exponential backoff with jitter, anonymous NID session rotation, and configurable Apify Proxy support (proxyGroup: "DATACENTER" or "RESIDENTIAL").
• Fair Pay-Per-Event Billing: $0.00 startup fee and $0.00 charge for failed terms. Every output record includes Google's required attribution ("Data source: Google Trends (https://www.google.com/trends)").

4. Categories & Keywords

• Categories: SEO_TOOLS, AI, MARKETING
• Keywords: google trends, interest over time, related queries, rising keywords, regional search interest, seo keyword research, market intelligence, search demand, pay per event, ai agent tool

5. Pricing Summary

• Model: Pay-Per-Event (PAY_PER_EVENT)
• Actor Start (apify-actor-start): $0.00 USD
• Dataset Item (apify-default-dataset-item): $0.005 USD per successful keyword or comparison group ($5.00 per 1,000 items)

6. Frequently Asked Questions (FAQ)

Q1: What does this Actor cost to run?

It costs $0.005 USD per successfully extracted dataset item ($5.00 per 1,000 keywords or comparison groups) under Apify's Pay-Per-Event model, with a $0.00 startup fee. Platform compute (256 MB) and proxy traffic are included in the per-item price.

Q2: Why does this Actor charge per item instead of charging a startup or monthly fee?

Charging per dataset item (apify-default-dataset-item) guarantees that you only pay when Google Trends returns valid data for your keyword. Failed terms are written to failures in the Key-Value Store at $0.00 charge, and the $0.00 start fee makes small 1–10 keyword calls economical for AI agents and scheduled automations.

Q3: What data fields does each output item return?

Every item includes keywords, geo, timeRange, category, property, timeline (array of {date, value, isPartial}), regions (array of {geoCode, geoName, value} when includeRegions: true), relatedQueries ({top, rising} when includeRelated: true), relatedTopics ({top, rising} when includeRelated: true), exploreUrl, fetchedAt, source, and attribution.

Q4: Do I need a Google API key or logged-in Google account?

No. The Actor requires no API key, no browser cookies from personal accounts, and no login credentials. It uses only the anonymous NID session cookie issued by https://trends.google.com/trends/.

Q5: What are the rate limits, proxy options, and operational limits?

Google Trends enforces strict rate limits (HTTP 429). This Actor runs at concurrency 1 (~3.5s–6s per keyword in normal conditions, up to ~14s when 429 retries occur), supports switching between "DATACENTER" and "RESIDENTIAL" Apify Proxy groups via proxyGroup, limits comparative groups to 5 terms per chart (compare: true), and halts cleanly after 3 consecutive failed terms to prevent wasted runs.

Q6: What are common usage examples for this Actor?

1. SEO Breakout Keyword Discovery: Pass 50 niche terms with includeRelated: true and timeRange: "today 3-m" to capture rising search queries (+250%, Breakout).
2. Multi-Brand Comparison: Pass keywords: ["python", "rust", "typescript"] with compare: true and includeRegions: true to benchmark relative developer interest across US states.
3. Autonomous AI Agent Tooling: Connect via Apify MCP server to let LLM agents verify real-time search demand for 1–5 topics at $0.005–$0.025 per invocation.

Google Trends Explorer: Timeline, Regions & Queries

Extract Google Trends Interest Over Time (timeline), Interest by Region (comparedgeo), Related Queries, and Related Topics (Top & Rising) into a clean, structured JSON dataset, with automatic HTTP 429 rate-limit backoff, anonymous session rotation, and Apify Proxy (DATACENTER / RESIDENTIAL) support.

Attribution Notice: All data extracted by this Actor comes from Google Trends. When reusing or publishing these datasets, please include the attribution required by Google:

Data source: Google Trends (https://www.google.com/trends) (automatically included in every output item under source and attribution).

Why Use This Google Trends Actor?

This Actor queries the same lightweight JSON widget endpoints that power the Google Trends interface (no headless browser overhead), keeping memory usage low (256 MB) and outputs deterministic. When Google responds with HTTP 429 Too Many Requests, the Actor backs off with jitter, rotates to a fresh anonymous session (new_session_id()) and new proxy IP, and retries automatically. There is no startup fee ($0.00 apify-actor-start): you pay only for successfully extracted dataset items.

1. Direct Widget Endpoint Integration (httpx): Queries /trends/api/explore, /trends/api/widgetdata/multiline, /trends/api/widgetdata/comparedgeo, and /trends/api/widgetdata/relatedsearches (permitted by trends.google.com/robots.txt), strips the )]}' XSSI prefix, and normalizes timestamps to UTC ISO-8601.
2. Multi-Stage 429 Recovery & Per-Request Proxy Rotation:

• Enforces a polite request cadence (<= 1 request per 1.5s, concurrency 1).
• Supports Apify Proxy (proxyGroup: "DATACENTER" or "RESIDENTIAL") on port 8000 with fresh per-request HTTP client connections so each request or session rotation receives a new exit IP, plus automatic fallback to direct connection when running locally without proxy credentials.
• On HTTP 429 or 5xx, waits with progressive exponential backoff + jitter and rotates the anonymous session cookie (NID) and proxy session token.

1. Zero Charge on Failed Terms: If a keyword fails after all retries and session rotations, it is never pushed to the dataset and never billed. Failed terms are recorded under the failures key in the default Key-Value Store (failures.json) with the failure reason.
2. Single-Term or 5-Term Comparison Mode (compare): Query keywords individually (compare: false) or batch them into comparative groups of up to 5 keywords (compare: true) on a shared 0–100 scale.

Input Parameters

Example Input

{
  "keywords": ["python", "rust", "typescript"],
  "compare": false,
  "geo": "US",
  "timeRange": "today 3-m",
  "category": 0,
  "property": "",
  "includeTimeline": true,
  "includeRegions": true,
  "includeRelated": true,
  "hl": "en-US",
  "maxItems": 20,
  "proxyGroup": "DATACENTER",
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}

Output Schema

Each dataset item represents one keyword (when compare: false) or one group of up to 5 keywords (when compare: true):

{
  "keywords": ["python"],
  "geo": "US",
  "timeRange": "today 3-m",
  "category": 0,
  "property": "",
  "timeline": [
    {
      "date": "2026-07-19T00:00:00Z",
      "value": 95,
      "isPartial": false
    },
    {
      "date": "2026-07-20T00:00:00Z",
      "value": 100,
      "isPartial": false
    }
  ],
  "regions": [
    {
      "geoCode": "US-CA",
      "geoName": "California",
      "value": 100
    }
  ],
  "relatedQueries": {
    "top": [
      {
        "query": "what is python",
        "value": 100,
        "formattedValue": "100",
        "link": "https://trends.google.com/trends/explore?q=what+is+python&date=today+3-m&geo=US"
      }
    ],
    "rising": [
      {
        "query": "python 3.13",
        "value": 450,
        "formattedValue": "+450%",
        "link": "https://trends.google.com/trends/explore?q=python+3.13&date=today+3-m&geo=US"
      }
    ]
  },
  "relatedTopics": {
    "top": [
      {
        "title": "Python",
        "type": "Programming language",
        "mid": "/m/05z1_",
        "value": 100,
        "formattedValue": "100",
        "link": "https://trends.google.com/trends/explore?q=/m/05z1_&date=today+3-m&geo=US"
      }
    ],
    "rising": []
  },
  "exploreUrl": "https://trends.google.com/trends/explore?q=python&date=today+3-m&geo=US&hl=en-US",
  "fetchedAt": "2026-10-19T16:55:00Z",
  "source": "Google Trends",
  "attribution": "Data source: Google Trends (https://www.google.com/trends)"
}

Pricing (Pay-Per-Event)

You only pay for successfully extracted dataset items (apify-default-dataset-item). Startup (apify-actor-start) and failed terms cost $0.00:

• Price per item (apify-default-dataset-item): $0.005 USD per item ($5.00 per 1,000 keywords or comparison groups), all-inclusive of platform compute (256 MB) and proxy usage.
• Spending Cap Enforcement: Checks is_event_charge_limit_reached("apify-default-dataset-item") before emitting each item and halts cleanly when your budget limit is reached.

Limits, Rate Limiting & Terms Compliance

• Respects robots.txt: Accesses only /trends/ and /trends/api/* endpoints permitted by https://trends.google.com/robots.txt. Never requests disallowed /explore? or /trends/explore? HTML pages.
• Anonymous Public Access Only: Uses only the standard anonymous NID cookie issued by trends.google.com. Never uses logged-in accounts or CAPTCHA bypass services.
• Required Attribution: Per Google Trends Help, cite "Data source: Google Trends (https://www.google.com/trends)" when publishing or redistributing data.

Frequently Asked Questions (FAQ)

1. What does this Actor cost?

This Actor uses Apify's Pay-Per-Event (PPE) model at $0.005 USD per successful dataset item ($5.00 per 1,000 keywords or comparison groups), with a $0.00 startup fee. Platform compute and proxy costs are included in the per-item price.

2. Why does this Actor charge per item instead of a startup fee or monthly rental?

Per-item billing (apify-default-dataset-item) ensures you only pay for keywords that succeed. If an upstream HTTP 429 block prevents a keyword from being extracted after all retries, it is logged to failures in the Key-Value Store and you are charged $0.00 for it. With zero startup fee, even a 1-keyword AI agent call costs just half a cent ($0.005).

3. What data fields does each output item return?

Each dataset item returns keywords, geo, timeRange, category, property, timeline (UTC ISO-8601 dates and 0–100 normalized interest scores), regions (when includeRegions: true), relatedQueries and relatedTopics with top and rising lists (when includeRelated: true), a human-verifiable exploreUrl, fetchedAt timestamp, source, and Google's required attribution string.

4. Do I need a Google API key or logged-in Google account?

No. The Actor connects anonymously to Google Trends' public widget endpoints, acquires a standard anonymous NID session cookie automatically, and requires zero external API keys or Google account credentials.

5. What are the rate limits, proxy options, and safety controls?

Google Trends actively rate-limits burst traffic with HTTP 429. To protect reliability, this Actor runs at concurrency 1 (>= 1.5s between requests), supports both "DATACENTER" and "RESIDENTIAL" Apify Proxy groups (proxyGroup), rotates anonymous sessions on 429, and stops early if 3 consecutive terms fail so a throttled run never wastes time.

6. How can I use this Actor in practical workflows or AI agent pipelines?

• SEO & Content Research: Run 20–100 seed keywords with includeRelated: true to discover breakout (rising) queries and topics.
• Brand Share-of-Search Benchmarking: Set compare: true with up to 5 competitor brand names (["openai", "anthropic", "gemini"]) and includeRegions: true to compare relative interest across countries or US states.
• AI Agent / MCP Tool Calls: Trigger single-term or 5-term runs on demand with maxItems: 5 for $0.025 total cost and zero fixed overhead.

Terms of Service, robots.txt & Rule 0 Compliance Verification — google-trends

• Actor: google-trends (Google Trends Explorer: Timeline, Regions & Queries)
• Target Source: Google Trends (https://trends.google.com)
• Initial Verification Date: 2026-10-19 (Reviewed & updated for Store kit: 2026-10-21)
• Rule 0 Verdict: APPROVED (GO) — Public aggregate search-interest metadata only; zero personal data (PII), zero authenticated sessions, strict adherence to robots.txt, and built-in Google Trends attribution.

1. Executive Rule 0 Checklist

2. Literal Quotes & Official Sources

A. Google Terms of Service (https://policies.google.com/terms?hl=en-US)

Under "Respect others / Don't abuse our services", Google defines the boundary of permissible automated access by referencing machine-readable instructions (robots.txt):

"Don't abuse, harm, interfere with, or disrupt the services — for example, by accessing or using them in fraudulent or deceptive ways, introducing malware, or spamming, hacking, or bypassing our systems or protective measures. Note that when you use the services, you shouldn't access them in an automated way in violation of the machine-readable instructions on our web pages (for example, robots.txt files that disallow crawling, training, or other activities)."

B. https://trends.google.com/robots.txt (Literal Capture on 2026-10-19)

# trends.google.com/robots.txt

User-agent: *
Disallow: /explore?
Disallow: /trends/explore?

• Disallowed paths (never requested by this Actor): /explore? and /trends/explore? (interactive HTML views with query strings). Note that the exploreUrl field in the output dataset is constructed purely offline as a string reference for human readers.
• Allowed paths used by this Actor (100% permitted by robots.txt):

1. GET https://trends.google.com/trends/?geo=US (anonymous NID session cookie initialization)
2. GET https://trends.google.com/trends/api/explore
3. GET https://trends.google.com/trends/api/widgetdata/multiline
4. GET https://trends.google.com/trends/api/widgetdata/comparedgeo
5. GET https://trends.google.com/trends/api/widgetdata/relatedsearches

C. Google Trends Help Center — Export, embed, and cite Trends data (https://support.google.com/trends/answer/4365538?hl=en)

Literal quote from "How to use and cite Trends data":

"How to use and cite Trends data

You can use any information from Google Trends, subject to the Google Terms of Service. If you reuse Trends data, attribute the information to Google with a citation.

Example: To use a screenshot of Trends data, add "Data source: Google Trends (https://www.google.com/trends)."

Note: Google Trends is a different data source from Google Ads. Please do not cite these sources together."

3. Technical Controls & Honest Residual Risk Assessment

1. Strict robots.txt Compliance: The Actor never sends HTTP requests to /explore?... or /trends/explore?....
2. Anonymous Access Only (Zero Auth / Zero CAPTCHA Solving): Uses only the standard anonymous NID cookie issued by https://trends.google.com/trends/. Never uses logged-in Google accounts or CAPTCHA solvers.
3. Honest Residual Risk (Upstream Rate Limiting & Schema Changes):

• IP Rate Limiting (HTTP 429): Google Trends aggressively rate-limits shared datacenter IPs (such as VPS or cloud ranges) with HTTP 429 Too Many Requests or google.com/sorry redirects. While this does not violate robots.txt, it is the primary operational risk.
• Mitigation Without Circumvention: Rather than bypassing protective challenges (CAPTCHA), the Actor respects rate limits by enforcing a >= 1.5s interval at concurrency 1, backing off exponentially with jitter, rotating anonymous proxy sessions (DATACENTER or RESIDENTIAL via Apify Proxy), stopping cleanly after 3 consecutive failed terms, and charging $0.00 for any term that fails.
• Internal Widget Format Risk: Because /trends/api/* endpoints power Google Trends' web frontend rather than a versioned public REST contract, Google may change response structures at any time. Offline fixture regression tests (tests/test_unit.py) and pre-release proxy canary checks (batches/B6/canary.py) detect breaking format changes before publication.