{ "openapi": "3.0.1", "info": { "title": "Google Trends Scraper API & Breakout Monitor", "description": "Google Trends scraper and API for keywords or pasted Trends links: interest over time, regions, related and rising queries, Trending Now topics. Schedule a watchlist to catch new Breakout signals. No Google account or API key needed.", "version": "1.10", "x-build-id": "Dlj9IvxF1yWvmOUSL" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/automa-flow~google-trends-monitor/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-automa-flow-google-trends-monitor", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/automa-flow~google-trends-monitor/runs": { "post": { "operationId": "runs-sync-automa-flow-google-trends-monitor", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/automa-flow~google-trends-monitor/run-sync": { "post": { "operationId": "run-sync-automa-flow-google-trends-monitor", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "keywords": { "title": "Keywords or Google Trends links", "maxItems": 200, "type": "array", "description": "Fast start: paste up to 200 search terms or Google Trends explore links, one per line. Each term becomes its own independently scaled Google Trends group. A link such as https://trends.google.com/trends/explore?q=meal%20prep&geo=US is checked with the settings it shows: its own terms (up to 5, compared together), location, time range, category and search type. Settings the link leaves out use the Google Trends defaults (worldwide, past 12 months), not the run settings below. Use Comparison groups below only when you need 2-5 keywords normalized against each other with your own externalId.", "items": { "type": "string", "minLength": 1, "maxLength": 2000, "pattern": "\\S" } }, "geo": { "title": "Location", "pattern": "^\\s*([A-Za-z]{2}(-[A-Za-z0-9]{1,3})?|[Ww][Oo][Rr][Ll][Dd]([Ww][Ii][Dd][Ee])?|[Gg][Ll][Oo][Bb][Aa][Ll])?\\s*$", "type": "string", "description": "ISO code deciding which country or subregion Google measures, for example US, DE, GB, or a subregion such as US-CA. Leave empty for worldwide. Changing this changes the scaling basis, so values are not comparable across locations. Left out, the run uses US (worldwide for input in the official Google Trends Scraper's format)." }, "timeframe": { "title": "Timeframe", "pattern": "^(now (1-H|4-H|1-d|7-d)|today (1-m|3-m|12-m|5-y)|all|(?:(?!0000)[0-9]{4}-(?:(?:01|03|05|07|08|10|12)-(?:0[1-9]|[12][0-9]|3[01])|(?:04|06|09|11)-(?:0[1-9]|[12][0-9]|30)|02-(?:0[1-9]|1[0-9]|2[0-8]))|(?:[0-9]{2}(?:0[48]|[2468][048]|[13579][26])|(?:0[48]|[2468][048]|[13579][26])00)-02-29) (?:(?!0000)[0-9]{4}-(?:(?:01|03|05|07|08|10|12)-(?:0[1-9]|[12][0-9]|3[01])|(?:04|06|09|11)-(?:0[1-9]|[12][0-9]|30)|02-(?:0[1-9]|1[0-9]|2[0-8]))|(?:[0-9]{2}(?:0[48]|[2468][048]|[13579][26])|(?:0[48]|[2468][048]|[13579][26])00)-02-29))$", "type": "string", "description": "How far back Google measures. Presets: now 1-H, now 4-H, now 1-d, now 7-d, today 1-m, today 3-m, today 12-m, today 5-y, all. Or a custom window as YYYY-MM-DD YYYY-MM-DD, for example 2025-11-01 2026-01-31, to study a season or campaign. Both dates must exist and the start must not follow the end. Google picks the bucket size (hourly, daily, weekly or monthly) from the window and reports it on every row. Values are not comparable across different timeframes. Left out, the run uses today 3-m (today 12-m for input in the official Google Trends Scraper's format)." }, "category": { "title": "Category", "description": "Google Trends category ID to restrict the search to. 0 means all categories. Changing this changes the scaling basis. Text such as \"71\" from the official Google Trends Scraper is read as the number 71.", "default": 0 }, "property": { "title": "Google property", "enum": [ "web", "images", "news", "shopping", "youtube" ], "type": "string", "description": "Which Google search surface to measure. Values are not comparable across properties.", "default": "web" }, "dataTypes": { "title": "Data to collect", "minItems": 1, "type": "array", "description": "Which datasets to fetch per group. Fewer data types means fewer requests, a faster run and a lower chance of being throttled. Related topics is deliberately not offered: Google currently answers that endpoint with an empty list for every keyword, and publishing it would report 'no related topics' everywhere.", "items": { "type": "string", "enum": [ "interest_over_time", "related_queries", "interest_by_region", "trending_now" ], "enumTitles": [ "Interest over time", "Related queries (top + rising + breakout)", "Interest by region", "Trending now (no keywords needed)" ] }, "default": [ "interest_over_time", "related_queries", "interest_by_region" ] }, "mode": { "title": "Mode", "enum": [ "monitor", "snapshot" ], "type": "string", "description": "snapshot returns what Google says right now and stores nothing. monitor remembers the last successful check so later runs can report only what changed.", "default": "snapshot" }, "outputMode": { "title": "Output", "enum": [ "changesOnly", "all" ], "type": "string", "description": "changesOnly returns new and changed rising/breakout queries and new trending topics, plus a status row per group. all additionally returns every timeline point and region score. Timelines are measurements rather than events, so they are only returned by all.", "default": "all" }, "keywordSummaries": { "title": "Keyword summaries", "type": "boolean", "description": "Adds one keyword_summary row per checked keyword: up, down or stable against a comparable earlier period, the change in percent, the peak, the top rising query and one plain sentence. Not charged, no extra requests to Google. Left out of the input: on for runs started in Console or by AI agents, off for API and scheduled runs, so an existing integration keeps exactly the rows it had. Set true to get them in API or scheduled runs." }, "trendingGeos": { "title": "Trending Now countries", "maxItems": 50, "type": "array", "description": "Countries whose Trending Now feed to fetch, for example US, DE, JP. Only used when trending_now is selected above; defaults to the Location setting. Worldwide has no trending feed.", "items": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "default": [] }, "queries": { "title": "Comparison groups (advanced)", "maxItems": 200, "type": "array", "description": "Optional groups of 1-5 keywords that Google normalizes together, making values inside a group directly comparable. Keywords in different groups are NOT comparable. Each group may override the run's geo, timeframe, category or property, so one run can check the same keyword in several countries or windows. externalId is echoed onto every result and never sent to Google. The combined limit with Keywords is 200 groups. Repeated keywords within a group are collapsed ignoring case and whitespace. Duplicate groups with the same ordered keywords and settings are returned as INVALID_INPUT and are not requested or charged again, even if externalId differs.", "items": { "type": "object", "required": [ "keywords" ], "additionalProperties": false, "properties": { "keywords": { "title": "Keywords", "type": "array", "description": "1-5 search terms compared against each other in one chart.", "minItems": 1, "maxItems": 5, "items": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "\\S" } }, "externalId": { "title": "Your external ID", "type": "string", "editor": "textfield", "maxLength": 200, "description": "Your own stable identifier for this group. Echoed back, never sent to Google." }, "geo": { "title": "Location override", "type": "string", "description": "ISO code for this group only, for example DE or US-CA; empty string means worldwide. Defaults to the run's Location.", "pattern": "^([A-Za-z]{2}(-[A-Za-z0-9]{1,3})?)?$" }, "timeframe": { "title": "Timeframe override", "type": "string", "description": "A preset such as today 12-m or a custom YYYY-MM-DD YYYY-MM-DD window for this group only. Defaults to the run's Timeframe.", "pattern": "^(now (1-H|4-H|1-d|7-d)|today (1-m|3-m|12-m|5-y)|all|(?:(?!0000)[0-9]{4}-(?:(?:01|03|05|07|08|10|12)-(?:0[1-9]|[12][0-9]|3[01])|(?:04|06|09|11)-(?:0[1-9]|[12][0-9]|30)|02-(?:0[1-9]|1[0-9]|2[0-8]))|(?:[0-9]{2}(?:0[48]|[2468][048]|[13579][26])|(?:0[48]|[2468][048]|[13579][26])00)-02-29) (?:(?!0000)[0-9]{4}-(?:(?:01|03|05|07|08|10|12)-(?:0[1-9]|[12][0-9]|3[01])|(?:04|06|09|11)-(?:0[1-9]|[12][0-9]|30)|02-(?:0[1-9]|1[0-9]|2[0-8]))|(?:[0-9]{2}(?:0[48]|[2468][048]|[13579][26])|(?:0[48]|[2468][048]|[13579][26])00)-02-29))$" }, "category": { "title": "Category override", "type": "integer", "description": "Google Trends category ID for this group only. Defaults to the run's Category.", "minimum": 0 }, "property": { "title": "Google property override", "type": "string", "description": "web, images, news, shopping or youtube for this group only. Defaults to the run's Google property.", "enum": [ "web", "images", "news", "shopping", "youtube" ] } } } }, "monitorId": { "title": "Monitor ID", "pattern": "^\\s*([A-Za-z0-9_.-]{1,64})?\\s*$", "maxLength": 64, "type": "string", "description": "Optional name separating independent monitoring histories in the same Apify account, for example 'seo-team' and 'ecommerce-team'. Leave empty unless you run several unrelated watchlists." }, "cachedResultOnRefusal": { "title": "Use the last verified result when Google refuses", "type": "boolean", "description": "When Google does not answer a fresh check (rate limit, outage or the run's time running out), deliver this account's verified result of the same check from an earlier run, up to 24 hours old (1 hour for 'now 1-d', 6 hours for 'now 7-d', never for 'now 1-H' or 'now 4-H'). Every such row is marked freshness CACHED with its age and original scraped_at, and the group is not charged. Snapshot mode only. Results are kept in the named key-value store google-trends-monitor-cache in your account. Turn off to get a FAILED status instead.", "default": true }, "failRunOnRefusal": { "title": "Fail the run when Google answers no check", "type": "boolean", "description": "Off (default): when Google refuses or does not answer every check in time, the run still ends SUCCEEDED. Each check is a group_status row with status FAILED and its reason (THROTTLED, SOURCE_UNAVAILABLE or RUN_DEADLINE), nothing is charged, and the status message says Google gave no data. Turn on to get a FAILED run instead, for example when your integration retries failed runs. A changed Google response format or an error in the Actor always fails the run.", "default": false }, "datasetFormat": { "title": "Dataset format", "enum": [ "compact", "flat" ], "type": "string", "description": "Leave empty for the default: compact, except runs started in Console or by AI agents through Apify MCP or Apify AI, which store flat rows because Console's Export button and the MCP dataset tool read stored items as they are. compact: each keyword group is a status row plus a few row_page items whose rows field holds every observation unchanged; the Output tab, the API link with unwind=rows and CSV/JSON exports with unwind=rows return the same flat rows as before, at a fraction of the storage cost. flat: one Dataset item per row, the format used until October 2026; choose it if your integration reads raw items and cannot pass unwind=rows." }, "searchTerms": { "title": "Search terms (official scraper input)", "maxItems": 200, "type": "array", "description": "Official Google Trends Scraper input: like keywords, but a left-out geo or timeframe means worldwide and past 12 months, as in that scraper. Ignored when keywords or queries are set. See the README section 'Switching from the official Google Trends Scraper'.", "items": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "isMultiple": { "title": "Comma separates compared terms (official scraper input)", "type": "boolean", "description": "Official Google Trends Scraper input: with true, 'a, b, c' in searchTerms is one comparison chart of up to 5 terms." }, "timeRange": { "title": "Time range (official scraper input)", "pattern": "^(|now 1-H|now 4-H|now 1-d|now 7-d|today 1-m|today 3-m|today 12-m|today 5-y|all)$", "type": "string", "description": "Official Google Trends Scraper input: same codes as timeframe; empty means past 12 months. Ignored when timeframe is set." }, "customTimeRange": { "title": "Custom time range (official scraper input)", "pattern": "^(\\d{4}-\\d{2}-\\d{2} \\d{4}-\\d{2}-\\d{2})?$", "type": "string", "description": "Official Google Trends Scraper input: YYYY-MM-DD YYYY-MM-DD; wins over timeRange." }, "spreadsheetId": { "title": "Google Sheet ID (official scraper input)", "type": "string", "description": "Official Google Trends Scraper input: ID or link of a public Google Sheet; terms are read from the first column below the header row. Ignored when searchTerms or startUrls are set." }, "maxItems": { "title": "Maximum groups (official scraper input)", "minimum": 0, "type": "integer", "description": "Official Google Trends Scraper input: checks only the first N searchTerms or startUrls; the rest are INVALID_INPUT rows, not charged. 0 means no limit." }, "viewedFrom": { "title": "Viewed from (official scraper input)", "type": "string", "description": "Official Google Trends Scraper input: ignored." }, "skipDebugScreen": { "title": "Skip debug screen (official scraper input)", "type": "boolean", "description": "Official Google Trends Scraper input: ignored." }, "maxConcurrency": { "title": "Max concurrency (official scraper input)", "type": "integer", "description": "Official Google Trends Scraper input: ignored." }, "maxRequestRetries": { "title": "Max request retries (official scraper input)", "type": "integer", "description": "Official Google Trends Scraper input: ignored." }, "pageLoadTimeoutSecs": { "title": "Page load timeout (official scraper input)", "type": "integer", "description": "Official Google Trends Scraper input: ignored." }, "payload": { "title": "Integration payload", "type": "object", "description": "Added by Apify when another Actor starts this one through an integration; not used." }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Required for keyword data. Google Trends rate-limits its data endpoints per IP address. Production verification showed four Residential sessions with automatic country selection receiving HTTP 429, while RESIDENTIAL with US country targeting succeeded immediately. RESIDENTIAL@US is therefore the reliability-first default. This setting is ignored by Trending Now-only runs because that public RSS feed needs no proxy.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ], "apifyProxyCountry": "US" } } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }