{ "openapi": "3.0.1", "info": { "title": "Google Trends Scraper API | Keywords & Regions", "description": "Google Trends API for interest over time, regional interest, related queries and Trending Now searches. Compare keywords and countries, export JSON/CSV and request optional charts. Each keyword report contains its time series; scores show relative interest, not search volume.", "version": "0.1", "x-build-id": "ixzV7wtEPWAKCeiIu" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/peerless_columbine~google-trends-scraper-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-peerless_columbine-google-trends-scraper-api", "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/peerless_columbine~google-trends-scraper-api/runs": { "post": { "operationId": "runs-sync-peerless_columbine-google-trends-scraper-api", "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/peerless_columbine~google-trends-scraper-api/run-sync": { "post": { "operationId": "run-sync-peerless_columbine-google-trends-scraper-api", "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": { "searchTerms": { "title": "Search terms", "type": "array", "description": "One or more Google Trends search terms. With Multiple terms enabled, comma-separated terms are compared in the same Google Trends request.", "items": { "type": "string" } }, "isMultiple": { "title": "Multiple terms", "type": "boolean", "description": "Treat commas inside each searchTerms entry as comparison separators. Google Trends supports up to five terms per comparison group.", "default": false }, "timeRange": { "title": "Time range", "type": "string", "description": "Choose a predefined Google Trends time window. Empty means Past 12 months." }, "geo": { "title": "Geo area", "type": "string", "description": "Choose Worldwide or a country; custom subdivisions such as US-CA remain accepted. A geo in a start URL takes precedence for that URL. Source availability determines regional/city/metro coverage.", "default": "" }, "category": { "title": "Category ID", "type": "string", "description": "Choose a named Google Trends category or enter a numeric category ID. Blank/0 means all categories.", "default": "" }, "startUrls": { "title": "Google Trends URLs", "type": "array", "description": "Paste Google Trends Explore URLs. q, geo, date, cat and gprop parameters are preserved.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "spreadsheetId": { "title": "Public Google Sheet ID or URL", "type": "string", "description": "Optional public one-column Google Sheet. The first row is treated as a header." }, "requestDelayMillis": { "title": "Minimum request spacing", "minimum": 0, "maximum": 2000, "type": "integer", "description": "Minimum spacing in milliseconds between Google Trends HTTP request starts across all workers.", "default": 0 }, "viewedFrom": { "title": "Compatibility: viewedFrom", "type": "string", "description": "Optional proxy-origin country, separate from the data geography. Requires available Apify residential proxies; custom two-letter country codes remain accepted." }, "mode": { "title": "mode", "enum": [ "keyword", "trending" ], "type": "string", "description": "Historical keyword reports or live trending searches.", "default": "keyword" }, "keyword": { "title": "keyword", "type": "string", "description": "Single search term alias." }, "predefinedTimeframe": { "title": "predefinedTimeframe", "enum": [ "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": "Alias for timeRange." }, "trendingSearchesCountry": { "title": "trendingSearchesCountry", "enum": [ "US", "FR", "AL", "DZ", "AO", "AR", "AM", "AU", "AT", "AZ", "BH", "BD", "BY", "BE", "BJ", "BO", "BA", "BR", "BG", "BF", "KH", "CM", "CA", "CL", "CO", "CR", "HR", "CU", "CY", "CZ", "CD", "DK", "DO", "EC", "EG", "SV", "EE", "ET", "FI", "GE", "DE", "GH", "GR", "GT", "HT", "HN", "HK", "HU", "IN", "ID", "IR", "IQ", "IE", "IL", "IT", "CI", "JM", "JP", "JO", "KZ", "KE", "KW", "KG", "LV", "LB", "LY", "LT", "MY", "ML", "MX", "MD", "MA", "MZ", "MM", "NP", "NL", "NZ", "NI", "NG", "MK", "NO", "OM", "PK", "PS", "PA", "PY", "PE", "PH", "PL", "PT", "PR", "QA", "RO", "RU", "SA", "SN", "RS", "SG", "SK", "SI", "ZA", "KR", "ES", "LK", "SE", "CH", "SY", "TW", "TZ", "TH", "TT", "TN", "TR", "TM", "UG", "UA", "AE", "GB", "UY", "UZ", "VE", "VN", "YE", "ZM", "ZW" ], "type": "string", "description": "Trending-search input; same field name as data_xplorer." }, "trendingSearchesTimeframe": { "title": "trendingSearchesTimeframe", "enum": [ "4", "24", "48", "168" ], "type": "string", "description": "Trending-search input; same field name as data_xplorer." }, "trendingSearchesCategories": { "title": "trendingSearchesCategories", "type": "array", "description": "Trending-search input; same field name as data_xplorer.", "items": { "type": "string" } }, "trendingSearchesMaxItems": { "title": "trendingSearchesMaxItems", "type": "integer", "description": "Trending-search input; same field name as data_xplorer." }, "fetchRegionalData": { "title": "Fetch Regional Data", "type": "boolean", "description": "Fetch regional and city data. Disable to skip regional requests while retaining timeline and related data.", "default": true }, "dataXplorerInput": { "title": "Data Xplorer compatibility input", "type": "object", "description": "Explicit data_xplorer input object. Defaults to trending mode and fetchRegionalData=false using the frozen competitor contract. Put all settings inside this object, including optional native snapshot/URL settings. Outer non-default settings cannot be mixed. Omit this field to retain native defaults." }, "maxItems": { "title": "Maximum report rows", "minimum": 0, "maximum": 1000, "type": "integer", "description": "Maximum number of report rows. Zero means no limit.", "default": 0 }, "maxRequestRetries": { "title": "Maximum request retries", "minimum": 0, "maximum": 8, "type": "integer", "description": "Retries for transient network errors and 403/408/429/5xx responses.", "default": 4 }, "rateLimitRecoverySeconds": { "title": "429 recovery wait", "minimum": 0, "maximum": 120, "type": "integer", "description": "Wait before each direct-only 429 recovery round. When an Apify fallback proxy is available, proxy recovery starts immediately. Zero disables waiting.", "default": 30 }, "rateLimitRecoveryRounds": { "title": "Maximum 429 recovery rounds", "minimum": 0, "maximum": 3, "type": "integer", "description": "Maximum number of bounded batch-level 429 recovery rounds. Each round retries only groups that are still rate-limited.", "default": 2 }, "customTimeRange": { "title": "Custom time range", "type": "string", "description": "Optional YYYY-MM-DD YYYY-MM-DD range. Takes precedence over timeRange." }, "proxyConfiguration": { "title": "Proxy connection (optional)", "type": "object", "description": "The form starts with direct requests. Enable Apify proxy or supply proxy URLs to route requests through the configured proxy from the first request. Proxy access and charges depend on your account.", "default": { "useApifyProxy": true } }, "maxConcurrency": { "title": "Maximum concurrency", "minimum": 1, "maximum": 10, "type": "integer", "description": "Maximum number of independent Google Trends comparison groups processed in parallel.", "default": 4 }, "pageLoadTimeoutSecs": { "title": "Request timeout seconds", "minimum": 5, "maximum": 180, "type": "integer", "description": "Per-request timeout in seconds for Google Trends HTTP calls.", "default": 30 }, "skipDebugScreen": { "title": "Compatibility: skipDebugScreen", "type": "boolean", "description": "When false, save a real Chromium PNG and HTML snapshot for every requested Explore or trending page to the run key-value store. Optional browser diagnostics run after data delivery; failure does not discard results. Defaults to true to avoid browser overhead.", "default": true }, "enableTrendingSearches": { "title": "Legacy trending mode switch", "type": "boolean", "description": "Legacy Data Xplorer alias. When supplied, overrides mode: true selects trending, false selects keyword. Leave unset for normal mode selection." }, "outputSchema": { "title": "Output format", "enum": [ "native", "data-xplorer" ], "type": "string", "description": "Native preserves detailed widget rows. data-xplorer returns timeline_data reports, or one bundled trending_searches report per run. A delivered bundle counts as one report event; platform usage is additional. Use native for multi-term comparisons." } } }, "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 } } } } } } } } } }