{ "openapi": "3.0.1", "info": { "title": "Google Trends Scraper & API - Interest, Regions, Trending", "description": "Reliable Google Trends scraper and API: interest over time, interest by region/city, top related queries, multi-keyword comparison and trending searches for any country. Decoy-filtered rising queries. Auto-retries, 429 handling and proxy rotation built in.", "version": "1.0", "x-build-id": "Y3CPaN14yhc3HivsK" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/ivan-petrus-g~google-trends-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-ivan-petrus-g-google-trends-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/ivan-petrus-g~google-trends-api/runs": { "post": { "operationId": "runs-sync-ivan-petrus-g-google-trends-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/ivan-petrus-g~google-trends-api/run-sync": { "post": { "operationId": "run-sync-ivan-petrus-g-google-trends-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": { "mode": { "title": "What to scrape", "enum": [ "explore", "trending" ], "type": "string", "description": "explore = keyword analysis (interest over time, by region, related queries/topics). trending = live 'Trending now' searches for one or more countries.", "default": "explore" }, "searchTerms": { "title": "Search terms", "type": "array", "description": "Keywords to analyze. Add as many as you like - they are processed in parallel. See 'Comparison mode' to compare terms against each other.", "items": { "type": "string" } }, "comparisonMode": { "title": "Comparison mode", "enum": [ "separate", "compareAll", "commaSeparated" ], "type": "string", "description": "separate = each term is its own query (values 0-100 per term). compareAll = terms are compared together in groups of up to 5 (values relative to each other, like the Compare box on Google Trends). commaSeparated = every line like 'iphone, samsung, pixel' is one comparison.", "default": "separate" }, "startUrls": { "title": "Google Trends URLs (optional)", "type": "array", "description": "Paste trends.google.com/trends/explore URLs; their q, geo, date, cat and gprop parameters are used as-is.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "geo": { "title": "Location (geo)", "type": "string", "description": "Country code (US, GB, DE, UA...) or region (US-CA, GB-ENG). Empty = Worldwide.", "default": "" }, "timeRange": { "title": "Time range", "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": "Predefined time range. Ignored when 'Custom time range' is filled.", "default": "today 12-m" }, "customTimeRange": { "title": "Custom time range", "type": "string", "description": "Format 'YYYY-MM-DD YYYY-MM-DD', e.g. '2024-01-01 2024-12-31'." }, "category": { "title": "Category ID", "minimum": 0, "type": "integer", "description": "Google Trends category id. 0 = all categories. Examples: 7 Finance, 18 Shopping, 45 Health, 66 Pets, 71 Food & Drink, 174 Business, 958 Jobs, 5 Computers & Electronics, 47 Autos.", "default": 0 }, "property": { "title": "Search type", "enum": [ "web", "images", "news", "youtube", "froogle" ], "type": "string", "description": "Search type.", "default": "web" }, "includeInterestOverTime": { "title": "Interest over time", "type": "boolean", "description": "Timeline + summary stats (average, peak, latest, % change, rising/falling).", "default": true }, "includeInterestByRegion": { "title": "Interest by region", "type": "boolean", "description": "Countries (worldwide) or regions/cities (inside a country).", "default": true }, "regionResolution": { "title": "Region resolution", "enum": [ "auto", "COUNTRY", "REGION", "CITY", "DMA" ], "type": "string", "description": "Granularity of 'Interest by region'. If the chosen level has no data, the actor falls back automatically (City -> Metro/DMA for US -> Google default) and reports the level used in interestByRegionResolution.", "default": "auto" }, "includeLowVolumeRegions": { "title": "Include low-volume regions", "type": "boolean", "description": "Also return regions with too little data (value 0).", "default": false }, "includeRelatedQueries": { "title": "Related queries (top + rising)", "type": "boolean", "description": "Top and rising related search queries for each term.", "default": true }, "risingFilter": { "title": "Rising-queries decoy filter", "enum": [ "strict", "balanced", "off" ], "type": "string", "description": "Google mixes fake entries into 'rising' related queries when it flags a session as automated. Flagged entries are moved from 'rising' to 'suspectedDecoys' (with reasons), so nothing is lost. Use 'balanced' for celebrity/tech keywords where real rising terms often share no words with the keyword.", "default": "strict" }, "extraDecoyTerms": { "title": "Extra decoy terms", "type": "array", "description": "Optional: additional rising entries you always want treated as decoys (exact match, case-insensitive).", "default": [], "items": { "type": "string" } }, "includeRelatedTopics": { "title": "Related topics (top + rising)", "type": "boolean", "description": "Related topics (Knowledge Graph). Google currently withholds them for automated sessions; when it does, the result has relatedTopics: null and relatedTopicsStatus explains why. Off by default (saves one request per keyword).", "default": false }, "trendingGeos": { "title": "Trending: countries", "type": "array", "description": "2-letter country codes for 'Trending now' mode.", "items": { "type": "string" } }, "trendingHours": { "title": "Trending: time window", "enum": [ "4", "24", "48", "168" ], "type": "string", "description": "Time window for trending searches.", "default": "24" }, "trendingCategories": { "title": "Trending: categories", "type": "array", "description": "Only return trends in these categories (empty = all).", "items": { "type": "string", "enum": [ "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "13", "14", "15", "16", "17", "18", "19", "20" ], "enumTitles": [ "Autos and Vehicles", "Beauty and Fashion", "Business and Finance", "Entertainment", "Food and Drink", "Games", "Health", "Hobbies and Leisure", "Jobs and Education", "Law and Government", "Other", "Pets and Animals", "Politics", "Science", "Shopping", "Sports", "Technology", "Travel and Transportation", "Climate" ] } }, "trendingActiveOnly": { "title": "Trending: active trends only", "type": "boolean", "description": "Skip trends that have already ended.", "default": false }, "trendingMaxItems": { "title": "Trending: max trends per country", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Sorted by search volume.", "default": 50 }, "language": { "title": "Language (hl)", "type": "string", "description": "Interface language for topic names and formatted dates.", "default": "en-US" }, "timezoneOffsetMinutes": { "title": "Timezone offset (minutes)", "type": "integer", "description": "Google 'tz' parameter. 0 = UTC. Example: -180 for UTC+3.", "default": 0 }, "maxItems": { "title": "Max results", "minimum": 0, "type": "integer", "description": "Stop after this many results (0 = no limit). Useful to cap cost.", "default": 0 }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 10, "type": "integer", "description": "Parallel workers (each uses its own proxy session).", "default": 3 }, "maxRetries": { "title": "Max retries per request", "minimum": 0, "maximum": 20, "type": "integer", "description": "Retries with exponential backoff and proxy rotation on HTTP 429/5xx.", "default": 8 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Apify Proxy is strongly recommended. Datacenter is used first; see 'Residential fallback'.", "default": { "useApifyProxy": true } }, "residentialFallback": { "title": "Residential fallback", "type": "boolean", "description": "If Google keeps rate-limiting a datacenter IP, automatically switch to Apify RESIDENTIAL proxies for the rest of the run.", "default": true }, "legitDataRetries": { "title": "Clean-data retries", "minimum": 0, "maximum": 10, "type": "integer", "description": "Google often labels automated sessions as a scraper (USER_TYPE_SCRAPER). With a proxy enabled, the actor can re-fetch through a fresh IP up to this many times. In cloud tests (Oct 2026) fresh datacenter and residential IPs never cleared the flag, so the default is 0 (saves time and proxy cost). Every result reports googleUserType.", "default": 0 } } }, "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 } } } } } } } } } }