Google Trends Content Planner — Evidence-backed Topic Ideas

Turn seed keywords into a prioritized content plan instead of a folder of raw Trends exports. The Actor discovers related searches, validates the best candidates with a second lookup, and returns deterministic content cards with reproducible evidence.

Workflow

1. Fetch Trends data for 1–5 seed keywords.
2. Merge related Top and Rising queries across seeds, retaining every source.
3. Spend the remaining maxQueries budget validating each selected candidate.
4. Score discovery signal (up to 35), support across seeds (20), within-query momentum (30), and goal-specific keyword intent (15).
5. Return ranked titles, angles, target queries, supporting evidence, and caveats.

No LLM or additional data provider is used. Titles and explanations come from transparent templates. Google Trends values are normalized, sampled relative interest—not absolute search volume. Scores are ranking heuristics, not traffic forecasts. Independent 0–100 curves are never concatenated into a single time series.

Candidates must contain all word anchors from at least one source seed before using a validation query. Matching ignores case, Unicode width and punctuation; CJK anchors may occur inside a longer CJK phrase. Candidates longer than 100 Unicode characters are excluded as an application limit. This conservative rule can omit useful synonyms and translations; it is not semantic relevance verification. Original candidates remain in the exclusions with seed_mismatch or query_too_long. Breakout priority applies only after these checks.

Input

{
  "seedKeywords": ["AI video", "video marketing"],
  "contentGoal": "educate",
  "searchType": "web",
  "timeRange": "today 3-m",
  "geo": "US",
  "category": "",
  "maxOpportunities": 5,
  "maxQueries": 12
}

Field	Default	Meaning
seedKeywords	required	1–5 non-empty topics; case/whitespace duplicates are removed
contentGoal	traffic	traffic, educate, or convert; changes intent scoring and templates
searchType	web	web, news, youtube, images, or shopping
timeRange	past 12 months	Standard Google Trends preset
customTimeRange	empty	YYYY-MM-DD YYYY-MM-DD; overrides timeRange
geo	worldwide	Data region such as US or US-CA
category	all	Non-negative Trends category ID
maxOpportunities	10	1–20 returned content cards
maxQueries	12	2–30 total discovery + validation queries; must cover all unique seeds
maxConcurrency	10	Concurrent query workers
maxRequestRetries	7	Full-query retries; 0 disables retries
pageLoadTimeoutSecs	180	Browser navigation limit; component requests use at most 10 seconds
viewedFrom	US on Apify	Residential proxy country, independent of geo

Output

The default Dataset contains one row per opportunity:

• Identity and decision: opportunityId, rank, keyword, score, confidence, contentGoal.
• Actionable brief: suggestedFormat, suggestedTitle, contentAngle, whyNow, targetQueries.
• Evidence: supportingTopics, recommendedRegions, metrics, and evidence (query ID, source URL, source seeds, filters, retrieval time).
• Quality: caveats and missingSections.

Nested arrays/objects remain JSON structures. CSV export serializes those cells rather than creating one row per evidence item.

The key-value store also contains:

• CONTENT_PLAN: complete JSON plan, algorithm version, filters, exclusions, and data-quality counts.
• CONTENT_PLAN.md: readable editorial checklist with evidence links and caveats.
• OUTPUT: succeeded, partial, or insufficient_data, query/opportunity counts, missing components, charging, and stop reason.

A candidate passes validation only when its own original timeline has at least four valid buckets in each chronological half and at least 50% valid buckets overall. Valid means non-partial, hasData: true, and a finite interest value from 0 through 100. This fixed coverage rule prevents a few isolated points from becoming a normal ranked card; it is not a statistical-significance test or an absolute-demand estimate.

Momentum is calculated from the valid values in the original first and second halves, not from a compressed array. Metrics include originalPointCount, validPointCount, coverageRatio, previousValidPointCount, recentValidPointCount, and latestValidTime. Momentum needs at least eight valid points; a zero baseline followed by positive interest leaves momentum unknown. When the previous average is above zero but below 5, the raw percentage is retained with a low-baseline caveat, but momentum score and momentum confidence are both zero. Corroboration counts only additional independent seeds: one seed scores 0, two score 10, and three or more score 20.

Timeline is required. Related queries, regions, and related topics are optional enrichment. Each missing enrichment component reduces confidence by 0.10 without changing the ranking score. Candidate-owned related queries must also retain every source-seed anchor and add up to four secondary targetQueries (five including the candidate); unrelated secondary queries are removed rather than presented as editorial targets. Supporting topics retain at least one seed anchor, and topics/regions are each capped at five entries for readability. Seed evidence is never substituted for candidate evidence. Google may omit hasData from ranked rows, especially Rising rows. Such rows remain evidence when present in a successfully retrieved component; explicit hasData: false is excluded and the original flag is preserved. Each evidence query retains its original retrievedAt; the card timestamp is the latest of its own contributing queries. Confidence is a heuristic, not a calibrated probability.

Coverage and exclusions

CONTENT_PLAN.coverage.validationAttempts counts attempted candidate lookups, including failed ones; validationPassed counts candidates that passed all evidence requirements before maxOpportunities truncation. failedQueries and the JSON failures list expose seed and candidate failures with query ID, input, and reason. OUTPUT.queriesUsed and CONTENT_PLAN.budget count logical seed and candidate queries. Retries and component HTTP requests consume compute/proxy resources but do not increase this logical query count; maxQueries is not a dollar cap.

Each discovered candidate omitted from the Dataset appears in CONTENT_PLAN.exclusions and the Markdown plan. Coverage exclusions include the original/valid counts, ratio, per-half counts, and query ID:

Reason	Meaning
seed_mismatch	Candidate does not retain all anchors of any source seed
query_too_long	Candidate exceeds the 100-character application limit
query_budget	Not selected within the remaining query budget
validation_unavailable	Selected but no candidate lookup result is available
validation_failed	Candidate lookup failed
required_sections_missing	Required candidate timeline is unavailable
no_valid_timeline	No complete usable candidate-specific interest points
insufficient_coverage	Some valid points exist, but a half has fewer than four or overall coverage is below 50%
rank_limit	Evidence passed, but the candidate falls below maxOpportunities

A budget, rank, or coverage cutoff does not imply low demand. Use maxQueries greater than the unique seed count to leave room for validation. If no candidate passes, the plan is insufficient_data. A plan with usable cards and failed/unusable queries is partial; budget/rank cutoffs alone do not make it partial.

Charging and recovery

A single content-plan event is emitted after an evidence-backed plan is persisted, including a partial plan with at least one usable card. Invalid input, insufficient data, and runs with no passing candidate emit no event. Apify compute and proxy usage are separate. The event price is configured when the Actor is published.

Completed query evidence, retrieval timestamps, Dataset delivery, and charging are journaled. Resuming the same run with unchanged input avoids repeating completed queries, delivered rows, or the plan charge. Changed input requires fresh storage.

Stored evidence is checked for valid data structure, status, query identity, and matching input before it is reused. Corrupted or mismatched records stop the run with a fresh-storage error. Completed failed lookups are also retained; start a new run to collect new evidence.

The current algorithm version is 10. An older algorithm's storage cannot be resumed with this version; use fresh storage to avoid mixing evidence or delivery records.

OUTPUT.stoppedBy is chargeLimit when the plan event could not be charged within the event budget, or chargeUncertain when the charging ledger cannot confirm its outcome. Uncertain charges are not blindly repeated.

Use the Dataset API, Apify Schedules, Zapier, or Make to hand the ranked cards to an editorial workflow. This Actor does not publish to a CMS or generate unsupported claims with an AI model.

Local development

From the repository root, use pnpm dev:content-planner to run with local INPUT storage, pnpm vitest run actors/google-trends-content-planner for offline tests, pnpm verify for repository checks, and pnpm bundle:content-planner to create the deployment bundle. A normal development run contacts Google; tests use local fixtures. Deployment and cloud validation are separate steps.

Related data is checked against its query keyword, geography, time-range parameter, category and search property. A nonempty ordinary Google widget response can recover an unavailable embedded component; an empty fallback remains missing. Optional topics use the shared HTTP session pool and ordinary-widget fallback rather than a serial browser reader, so optional enrichment does not block other query components. Failed queries retain the configured total request retry budget and backoff. A partial result with only optional enrichment missing is accepted without repeating the whole query, preventing optional-topic quota limits from multiplying traffic and cost. These controls reduce unnecessary traffic but cannot guarantee that Google will not rate-limit a run.

Development status

This is an independent Actor and does not call or modify google-trends-scraper. Private cloud validation precedes any public release. Local fixture, recovery, bundled-entry, and small cloud samples do not constitute long-term reliability, performance, or commercial guarantees. Check the current Store page for deployment status and pricing.