{ "openapi": "3.0.1", "info": { "title": "Google Trends Scraper & Breakout Monitor", "description": "Export Google Trends interest over time, regions, related queries, rising searches and Trending Now topics. Schedule a keyword watchlist to track new rising and Breakout signals. No Google account or source API key is needed.", "version": "1.10", "x-build-id": "25yo3qzzpMDT7V4mt" }, "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", "maxItems": 200, "type": "array", "description": "Fast start: paste up to 200 search terms, one per line. Each term becomes its own independently scaled Google Trends group. Use Comparison groups below only when you need 2-5 keywords normalized against each other.", "items": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "\\S" } }, "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" ] } } } }, "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.", "default": "US" }, "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.", "default": "today 3-m" }, "category": { "title": "Category", "minimum": 0, "type": "integer", "description": "Google Trends category ID to restrict the search to. 0 means all categories. Changing this changes the scaling basis.", "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" }, "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": [] }, "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." }, "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 } } } } } } } } } }