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.
{
"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.
| Field | Type / required | Default | Purpose |
|---|---|---|---|
| mode | string | Not specified | Research each keyword independently or compare explicit groups on a native shared timeline scale. Options: independent, compare |
| keywords | array | Not specified | Search terms or Google topic IDs. Required in independent mode. |
| comparisonGroups | array | Not specified | Compare mode only. Each object contains keywords (2–5 distinct terms) and an optional label. Related queries require independent mode. |
| geographies | array | Not specified | Country/subregion codes, such as US, GB, IN or US-CA. Use an empty string for worldwide. |
| timeWindows | array | Not specified | Google preset or YYYY-MM-DD YYYY-MM-DD. Use fixed dates for repeatable research. |
| surfaces | array | Not specified | Timeline is required. Related queries are available for independent keyword research. |
All other input controls (14)
| Field | Type / required | Default | Purpose |
|---|---|---|---|
| category | integer | Not specified | Google Trends category ID; zero includes all categories. Minimum: 0 · Maximum: 100000 |
| property | string | Not specified | The Google search surface to measure. Options: web, images, news, youtube, shopping |
| language | string | Not specified | Interface language for source labels; does not translate keywords. |
| timezoneOffsetMinutes | integer | Not specified | Google/JavaScript convention: India is -330, UTC is 0. Does not set research geography. Minimum: -1439 · Maximum: 1439 |
| maxAnalyses | integer | Not specified | Reject a larger expanded matrix before any source requests; maximum 1,000. Minimum: 1 · Maximum: 1000 |
| maxRunSeconds | integer | Not specified | Stop new work before this runtime budget and preserve results for resume. Minimum: 30 · Maximum: 3600 |
| concurrency | integer | Not specified | Maximum analyses in flight; requests also follow a shared pacing limit. Minimum: 1 · Maximum: 8 |
| requestDelayMillis | integer | Not specified | Minimum time between source requests across all workers. Increase when Google rate-limits requests. Minimum: 250 · Maximum: 60000 |
| maxRetries | integer | Not specified | Maximum additional attempts per source operation, excluding the first attempt. Minimum: 0 · Maximum: 3 |
| requestTimeoutSeconds | integer | Not specified | Maximum duration of one HTTP request. Minimum: 5 · Maximum: 60 |
| reviewRelatedQueries | boolean | Not specified | Add 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. |
| planOnly | boolean | Not specified | Produce a workload and charge estimate without fetching Google or charging research events. |
| proxyConfiguration | object | Not specified | Residential sessions are recommended for production. Set useApifyProxy to false for direct local tests. |
| resumeFromRunId | string | Not specified | Imports the original plan. Remove keywords, geographies, date windows and other research fields when resuming. |
03 / Output
Know what each returned row represents.
- 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.
{
"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.
| Billable event | Rate (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.
# 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.jsonThe 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.
- Do not compare independently scaled request values as if they were one shared popularity ranking.
- Availability, low-volume data, rate limits, and selected surfaces can affect completeness. Keep effective source periods and quality notes.
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