{ "openapi": "3.0.1", "info": { "title": "Google Trends Scraper", "description": "Scrape Google Trends interest over time, interest by region, related queries and topics, and trending-now — without the 429 failures. Successes are billed, failures are not, and every run finishes inside a wall-clock budget instead of hanging.", "version": "0.1", "x-build-id": "Lr58kuJ9yalYDPEVq" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/excellent_mustang~google-trends-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-excellent_mustang-google-trends-scraper", "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/excellent_mustang~google-trends-scraper/runs": { "post": { "operationId": "runs-sync-excellent_mustang-google-trends-scraper", "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/excellent_mustang~google-trends-scraper/run-sync": { "post": { "operationId": "run-sync-excellent_mustang-google-trends-scraper", "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": { "keyword": { "title": "Keyword", "type": "string", "description": "The search term to analyse. Use this for a single term; use the keyword list below for batches.", "default": "bitcoin" }, "keywords": { "title": "Keyword list", "maxItems": 500, "uniqueItems": true, "type": "array", "description": "Additional search terms. Combined with the single keyword above, de-duplicated. Google caps a comparison at 5 terms, so longer lists are split automatically — see 'Multi-keyword handling'.", "default": [], "items": { "type": "string" } }, "geo": { "title": "Geo", "type": "string", "description": "Two-letter country code (US, GB, IN, DE), a sub-region (US-CA, GB-ENG), or leave empty for worldwide.", "default": "US" }, "additionalGeos": { "title": "Additional geos", "maxItems": 50, "uniqueItems": true, "type": "array", "description": "Run the same keywords against more regions. Each row is tagged with its own geo.", "default": [], "items": { "type": "string" } }, "timeframe": { "title": "Timeframe", "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": "How far back to look. Shorter windows return finer resolution: 'now 1-d' is 8-minute buckets, 'now 7-d' is hourly, 'today 12-m' is weekly.", "default": "today 12-m" }, "customTimeframe": { "title": "Custom date range", "type": "string", "description": "Overrides the timeframe above. Format: 'YYYY-MM-DD YYYY-MM-DD', e.g. '2024-01-01 2024-06-30'." }, "category": { "title": "Category", "minimum": 0, "maximum": 1500, "type": "integer", "description": "Google Trends category id. 0 is all categories. Common ids: 7 Finance, 3 Arts & Entertainment, 5 Computers & Electronics, 8 Games, 12 Business & Industrial, 13 Internet & Telecom, 16 News, 20 Sports, 45 Health, 47 Autos & Vehicles, 71 Food & Drink, 174 Travel.", "default": 0 }, "searchType": { "title": "Search type", "enum": [ "", "images", "news", "youtube", "froogle" ], "type": "string", "description": "Which Google property to measure. Web search is the default.", "default": "" }, "dataTypes": { "title": "Data to scrape", "type": "array", "description": "Which datasets to pull. Each produces its own rows, tagged with dataType. Note: Google does not offer related topics for multi-keyword comparisons — that is upstream behaviour, not a failure.", "items": { "type": "string", "enum": [ "interest_over_time", "interest_by_region", "related_queries", "related_topics", "trending_now" ], "enumTitles": [ "Interest over time", "Interest by region", "Related queries (top + rising)", "Related topics (top + rising)", "Trending now (daily + realtime)" ] }, "default": [ "interest_over_time", "interest_by_region", "related_queries", "related_topics" ] }, "comparisonMode": { "title": "Multi-keyword handling", "enum": [ "individual", "compare" ], "type": "string", "description": "Google normalises interest WITHIN a comparison group — the top value in the group becomes 100. 'Individual' gives every keyword its own request and its own 0-100 scale, which is what a batch list almost always means. 'Compare' puts keywords into groups of 5 that are scaled against each other, and tags each row with its comparisonGroup.", "default": "individual" }, "outputMode": { "title": "Row shape", "enum": [ "flat", "nested" ], "type": "string", "description": "'Flat' emits one row per data point, ready for a spreadsheet or a database. 'Nested' emits one row per keyword per data type with the full series in a 'data' array — far fewer dataset items, so a far smaller bill.", "default": "flat" }, "trendingSource": { "title": "Trending-now source", "enum": [ "auto", "api", "rss" ], "type": "string", "description": "'Auto' uses Google's realtime trending API (hundreds of trends with search volume and growth) and falls back to the RSS feed if it is unavailable. RSS returns only 10 trends but carries full news articles.", "default": "auto" }, "trendingHours": { "title": "Trending window (hours)", "minimum": 1, "maximum": 168, "type": "integer", "description": "How far back the trending-now feed should look.", "default": 24 }, "fallbackToTrending": { "title": "Never return an empty run", "type": "boolean", "description": "If the keyword path returns nothing at all, fall back to the trending feed, which needs no token and no session. A run that returns trending data beats a run that returns nothing. Strongly recommended.", "default": true }, "maxItems": { "title": "Max dataset rows", "minimum": 1, "maximum": 200000, "type": "integer", "description": "Hard cap on billed rows. The run also clamps itself to whatever your maxTotalChargeUsd allows before it starts scraping.", "default": 1000 }, "maxRunTimeSecs": { "title": "Wall-clock budget (seconds)", "minimum": 30, "maximum": 3600, "type": "integer", "description": "Hard deadline for the whole run. When it expires the Actor stops scheduling work, pushes everything it already has and finishes successfully. This is what makes a partial result impossible to turn into an infinite loop. Raise it for large keyword lists.", "default": 240 }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 12, "type": "integer", "description": "Upper bound on parallel requests. The Actor lowers this automatically when Google starts throttling and raises it again when it stops, so the default is safe to leave alone.", "default": 4 }, "maxRetries": { "title": "Max attempts per request", "minimum": 1, "maximum": 10, "type": "integer", "description": "Each attempt uses exponential backoff with full jitter. A 429 additionally rotates to a fresh proxy session and a fresh cookie before retrying.", "default": 5 }, "language": { "title": "Language (hl)", "type": "string", "description": "Locale for labels Google returns, e.g. en-US, de-DE, es-ES.", "default": "en-US" }, "timezoneOffsetMinutes": { "title": "Timezone offset (minutes)", "minimum": -840, "maximum": 840, "type": "integer", "description": "Google's tz parameter: minutes to add to local time to reach UTC. 0 is UTC, -330 is IST, 300 is US Eastern. Only affects bucketing of sub-daily timeframes.", "default": 0 }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Apify Proxy with the datacenter group is enough for Google Trends and is what this Actor is tuned for — rotation, not residential bandwidth, is what defeats the rate limit. Leave it on.", "default": { "useApifyProxy": true } } } }, "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 } } } } } } } } } }