Apify actor · whoareyouanas/google-trends-batch-research

Google Trends Scraper: Bulk Keyword Research

Research Google Trends keywords across geographies and time windows. Export relative interest, regions, and related-query reports with explicit analysis outcomes, quality notes, and resumable batches.

Documentation checked 2026-10-29 · deployed build 1.1.8 · run through your Apify account

01 / Overview

Match the actor to the job.

Plan a research matrix

Expand keywords or comparison groups across selected countries and time windows.

Shared comparison scales

Use native comparison groups when keywords need a shared timeline scale.

Review analysis quality

Keep completion status, coverage, effective periods, and source quality distinct.

02 / Input

Start with a clear, bounded input.

Supply keywords for independent research or comparisonGroups for compare mode. The geography/time-window matrix determines planned analyses. maxAnalyses bounds the plan, and planOnly can preview it without a completed-analysis event.

input.json · example based on the deployed schema
{
  "keywords": [
    "running shoes",
    "trail running",
    "yoga mat"
  ],
  "geographies": [
    "US",
    "GB",
    "IN"
  ],
  "timeWindows": [
    "today 3-m"
  ],
  "surfaces": [
    "timeline",
    "regions",
    "relatedQueries"
  ]
}

Replace example targets and credential placeholders before running. These are documentation examples, not a promise of currently available source results.

Deployed actor input fields, types, defaults, and descriptions
FieldType / requiredDefaultPurpose
modestringNot specifiedResearch each keyword independently or compare explicit groups on a native shared timeline scale.

Options: independent, compare

keywordsarrayNot specifiedSearch terms or Google topic IDs. Required in independent mode.
comparisonGroupsarrayNot specifiedCompare mode only. Each object contains keywords (2–5 distinct terms) and an optional label. Related queries require independent mode.
geographiesarrayNot specifiedCountry/subregion codes, such as US, GB, IN or US-CA. Use an empty string for worldwide.
timeWindowsarrayNot specifiedGoogle preset or YYYY-MM-DD YYYY-MM-DD. Use fixed dates for repeatable research.
surfacesarrayNot specifiedTimeline is required. Related queries are available for independent keyword research.
All other input controls (14)
Deployed actor input fields, types, defaults, and descriptions
FieldType / requiredDefaultPurpose
categoryintegerNot specifiedGoogle Trends category ID; zero includes all categories.

Minimum: 0 · Maximum: 100000

propertystringNot specifiedThe Google search surface to measure.

Options: web, images, news, youtube, shopping

languagestringNot specifiedInterface language for source labels; does not translate keywords.
timezoneOffsetMinutesintegerNot specifiedGoogle/JavaScript convention: India is -330, UTC is 0. Does not set research geography.

Minimum: -1439 · Maximum: 1439

maxAnalysesintegerNot specifiedReject a larger expanded matrix before any source requests; maximum 1,000.

Minimum: 1 · Maximum: 1000

maxRunSecondsintegerNot specifiedStop new work before this runtime budget and preserve results for resume.

Minimum: 30 · Maximum: 3600

concurrencyintegerNot specifiedMaximum analyses in flight; requests also follow a shared pacing limit.

Minimum: 1 · Maximum: 8

requestDelayMillisintegerNot specifiedMinimum time between source requests across all workers. Increase when Google rate-limits requests.

Minimum: 250 · Maximum: 60000

maxRetriesintegerNot specifiedMaximum additional attempts per source operation, excluding the first attempt.

Minimum: 0 · Maximum: 3

requestTimeoutSecondsintegerNot specifiedMaximum duration of one HTTP request.

Minimum: 5 · Maximum: 60

reviewRelatedQueriesbooleanNot specifiedAdd literal seed-token overlap, URL-looking text and exact promotional-phrase annotations. Never filters or ranks relevance. Disable without changing the research plan, including on resume.
planOnlybooleanNot specifiedProduce a workload and charge estimate without fetching Google or charging research events.
proxyConfigurationobjectNot specifiedResidential sessions are recommended for production. Set useApifyProxy to false for direct local tests.
resumeFromRunIdstringNot specifiedImports the original plan. Remove keywords, geographies, date windows and other research fields when resuming.

03 / Output

Know what each returned row represents.

Illustrative output shape · not a live run
{
  "keyword": "coffee",
  "geography": "US",
  "time": "today 12-m",
  "effectiveTime": "2025-10-15 2026-10-15",
  "analysisStatus": "complete",
  "qualityState": "available",
  "latestCompleteInterest": 70,
  "latestCompleteDate": "2026-10-04T00:00:00.000Z",
  "recentChangePercent": 1.0344827586206806,
  "changeLabel": "Last 4 complete weekly intervals vs previous 4",
  "coverageLabel": "52 / 52 returned complete intervals usable"
}

Example values illustrate the published contract. Available fields and populated values depend on the source, mode, and result status.

Fields in the documented output view

keyword

Keyword

geography

Country / region

time

Requested period

effectiveTime

Effective timeline period

analysisStatus

Extraction

qualityState

Timeline quality

latestCompleteInterest

Latest complete index

latestCompleteDate

Latest interval start (UTC)

recentChangePercent

Descriptive change (%)

changeLabel

Change period

coverageLabel

Returned interval coverage

regionMetricLabel

Regional metric

topRegionsText

Regional highlights

risingQueriesText

Rising leads for review

queryReviewEnabled

Lexical review enabled

risingReviewFlagsText

Literal query-review facts

qualityNotesText

Quality notes

metricNotesText

Metric notes

analysisId

Analysis / comparison identifier

keywords

Terms in this analysis

captureScope

Timeline scale scope

sourceUrl

Timeline source context

report

report

Output views select columns. They do not necessarily filter record types or exhaust the full JSON payload. Use structured JSON when you need nested arrays or objects.

Dataset links and run artifacts (14)
Analyst report CSV
Available through the actor's Output tab for your run.
Analyst report JSON with provenance
Available through the actor's Output tab for your run.
Analyst dataset view
Available through the actor's Output tab for your run.
Analysis bundles
Available through the actor's Output tab for your run.
Keyword summaries
Available through the actor's Output tab for your run.
Timeline CSV
Available through the actor's Output tab for your run.
Regional CSV
Available through the actor's Output tab for your run.
Related queries CSV
Available through the actor's Output tab for your run.
Related-query lexical review CSV
Available through the actor's Output tab for your run.
Related-query lexical review JSON
Available through the actor's Output tab for your run.
Completeness manifest
Available through the actor's Output tab for your run.
Resume input
Available through the actor's Output tab for your run.
n8n workflow template
Available through the actor's Output tab for your run.
n8n setup instructions
Available through the actor's Output tab for your run.

04 / Pricing

Understand the billable unit.

These are the active public event prices checked on 2026-10-29, in USD. They describe each event, not a universal flat price for a run. Confirm your current Apify plan and run budget before starting.

Actor event prices and billing units
Billable eventRate (USD)When it applies

Completed research analysis

research-analysis-complete

$0.01 / event

One newly completed keyword or comparison-group analysis for one geography and date window, including supported selected surfaces and report exports. No new event for partial, failed, wholly empty, deferred, preview or inherited completed work.

$10.00 per 1,000 of this event. Other events and separate services are additional.

  • The configured charge is per newly completed research analysis, not per dataset row or exported file.
  • Partial, failed, wholly empty, deferred, preview, and inherited completed work do not create a new completion event. Resume continues the recorded research; it is not an automatic source refresh.

A result limit and a spending cap are different controls. Account charges, applicable taxes, and separately billed providers or proxies must be considered where relevant. A cap setting is not a minimum invoice charge.

05 / API & automation

Use the same input from your workflow.

Test a small run in Apify Console, inspect its records and charges, then save a task or call the actor from your own application. Keep your Apify token in an environment variable. Source-specific credentials, if required, are separate from the Apify API token.

cURL · start an asynchronous actor run
# Save the input example as input.json and set APIFY_TOKEN.
# This request starts an asynchronous, potentially billable run.
curl --request POST \
  'https://api.apify.com/v2/acts/whoareyouanas~google-trends-batch-research/runs' \
  --header "Authorization: Bearer $APIFY_TOKEN" \
  --header 'Content-Type: application/json' \
  --data @input.json

The response identifies the run. Wait for it to finish, inspect its status, and use its default dataset and key-value store to retrieve results. A successful run can still contain partial or failed records; check the output contract above before continuing downstream.

Coverage & interpretation

Check the result before relying on it.

Questions

Before you build an integration.

What do I need to provide?

Supply keywords for independent research or comparisonGroups for compare mode. The geography/time-window matrix determines planned analyses. maxAnalyses bounds the plan, and planOnly can preview it without a completed-analysis event.

What should I check in the output?
  • Analyst rows include relative-interest summaries, effective periods, status, quality notes, and report references.
  • Independent requests have independent scales. Google Trends is relative interest, not absolute search volume or keyword difficulty. Quality state and extraction status answer different questions.
How do I budget the run?
  • The configured charge is per newly completed research analysis, not per dataset row or exported file.
  • Partial, failed, wholly empty, deferred, preview, and inherited completed work do not create a new completion event. Resume continues the recorded research; it is not an automatic source refresh.

Keep exploring

Practical guides for the next step.