{ "openapi": "3.0.1", "info": { "title": "Google Trends Scraper: Compare 100 Keywords", "description": "Get Google Trends data in bulk: interest over time, by country, state, metro or city, related and rising queries and topics, and Trending Now. Compare up to 100 keywords on one 0–100 scale. Paste Trends URLs. Runs finish before their timeout, no compute bills, failed terms are free.", "version": "1.1", "x-build-id": "SVxE6JLkILp5W6Zxb" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/aaronoptimus~google-trends-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-aaronoptimus-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/aaronoptimus~google-trends-scraper/runs": { "post": { "operationId": "runs-sync-aaronoptimus-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/aaronoptimus~google-trends-scraper/run-sync": { "post": { "operationId": "run-sync-aaronoptimus-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": { "searchTerms": { "title": "Search terms or Google Trends URLs", "type": "array", "description": "Keywords or phrases to look up, one per line (a line like \"pickleball, padel\" counts as two terms, as on Google Trends). You can also paste Google Trends Explore or Trending Now URLs (their location, dates, category and search type are used as-is) or topic IDs like /m/05zppz. Each term is charged once, only if data comes back.", "items": { "type": "string" } }, "mode": { "title": "Mode", "enum": [ "separate", "compare" ], "type": "string", "description": "Separate: each term gets its own 0–100 scale. Compare: terms are scaled against each other (100 = the highest point of any term), up to 100 terms on one scale — see \"Compare all terms on one scale\".", "default": "separate" }, "compareAllOnOneScale": { "title": "Compare all terms on one scale (up to 100)", "type": "boolean", "description": "Google compares at most 5 terms at once. With this on, up to 100 terms are fetched in groups that share an anchor term and rescaled onto one 0–100 scale (bigger lists are split into scales of 100). Put your most popular term first for the best precision. Off = separate groups of 5.", "default": true }, "geo": { "title": "Location(s)", "pattern": "^[\\s,]*([A-Za-z]{2}(-[A-Za-z0-9]{1,3}){0,2}([\\s,]*,[\\s,]*[A-Za-z]{2}(-[A-Za-z0-9]{1,3}){0,2})*)?[\\s,]*$", "type": "string", "description": "Country or region code, e.g. US, GB, DE, or a sub-region like US-CA. Separate several with commas (US, GB, CA) to get each term for each location. Leave empty for worldwide. Use codes, not names (US, not \"United States\")." }, "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": "Period to look at. Ignored if a custom time range is set. An empty value (as sent by other Google Trends scrapers) means past 12 months.", "default": "today 12-m" }, "customTimeRange": { "title": "Custom time range", "pattern": "^\\s*(\\d{4}-\\d{2}-\\d{2} \\d{4}-\\d{2}-\\d{2}|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)?\\s*$", "type": "string", "description": "Optional. Exact dates as \"YYYY-MM-DD YYYY-MM-DD\", e.g. \"2025-01-01 2025-12-31\". Overrides Time range." }, "searchProperty": { "title": "Search type", "enum": [ "web", "images", "news", "youtube", "shopping" ], "type": "string", "description": "Which Google search to measure.", "default": "web" }, "category": { "title": "Category", "enum": [ "0", "3", "47", "44", "22", "12", "5", "7", "71", "8", "45", "65", "11", "13", "958", "19", "16", "299", "14", "66", "29", "533", "174", "18", "20", "67", "" ], "type": "string", "description": "Narrow results to a topic area (helps with ambiguous terms like \"jaguar\").", "default": "0" }, "customCategoryId": { "title": "Custom category ID", "minimum": 0, "type": "integer", "description": "Optional. Any Google Trends category ID (the number after \"cat=\" in a Trends URL), e.g. 276 for Restaurants. Overrides Category." }, "language": { "title": "Language", "pattern": "^\\s*([A-Za-z]{2,3}([-_][A-Za-z0-9]{2,8})*)?\\s*$", "type": "string", "description": "Language for related queries/topics and date labels, e.g. en-US, de, fr, es, ja.", "default": "en-US" }, "maxItems": { "title": "Max search terms", "minimum": 0, "type": "integer", "description": "Optional. Look up at most this many search terms (in the order given, URLs included); 0 = no limit. Same name and meaning as \"maxItems\" in Apify's Google Trends Scraper. For Trending Now, use \"Max trending topics per location\".", "default": 0 }, "outputFormat": { "title": "Output format", "enum": [ "items", "rows" ], "type": "string", "description": "Items: one rich JSON record per term (best for API / code). Rows: one flat row per data point with the same columns everywhere (best for CSV, Excel, Google Sheets, BI tools).", "default": "items" }, "includeInterestByRegion": { "title": "Interest by region", "type": "boolean", "description": "Include the breakdown by country / state / metro / city.", "default": true }, "regionResolution": { "title": "Region level", "enum": [ "AUTO", "COUNTRY", "REGION", "DMA", "CITY" ], "type": "string", "description": "AUTO picks countries for worldwide, states/regions for a country, and cities for a sub-region. US metro areas (DMA) work for the US only.", "default": "AUTO" }, "includeLowVolumeRegions": { "title": "Include low-volume regions", "type": "boolean", "description": "Also return regions with little search volume.", "default": false }, "includeRelatedQueries": { "title": "Related queries", "type": "boolean", "description": "Top and rising related searches (including Breakout terms).", "default": true }, "includeRelatedTopics": { "title": "Related topics", "type": "boolean", "description": "Top and rising related topics (Separate mode only). Google often withholds topics from automated requests; if the first 3 terms come back without topics, the rest of the run skips them to save time. Related queries are not affected.", "default": true }, "trendingNowGeos": { "title": "Trending Now locations", "type": "array", "description": "Optional. Country codes (e.g. US, GB) or supported regions (e.g. US-CA, GB-ENG), one per line or comma-separated, to fetch what is trending, like trends.google.com/trending: search volume, % increase, start and end time, related searches (breakdown) and news articles. Charged per trending topic delivered.", "items": { "type": "string", "pattern": "^[\\s,]*([A-Za-z]{2}(-[A-Za-z0-9]{1,3}){0,2}([\\s,]*,[\\s,]*[A-Za-z]{2}(-[A-Za-z0-9]{1,3}){0,2})*)?[\\s,]*$" }, "default": [] }, "trendingNowHours": { "title": "Trending Now window", "enum": [ "4", "24", "48", "168" ], "type": "string", "description": "How far back to look, as on the website.", "default": "24" }, "trendingNowCategory": { "title": "Trending Now category", "enum": [ "0", "1", "2", "3", "20", "4", "5", "6", "7", "8", "9", "10", "11", "13", "14", "15", "16", "17", "18", "19" ], "type": "string", "description": "Only topics in this category (Trending Now has its own categories, different from the Explore categories above).", "default": "0" }, "trendingNowActiveOnly": { "title": "Active trends only", "type": "boolean", "description": "Only searches that are still trending (no end time yet).", "default": false }, "trendingNowMaxItems": { "title": "Max trending topics per location", "minimum": 0, "maximum": 5000, "type": "integer", "description": "Most topics to return per location, in Google's order (the US often lists 400+ for 24 hours and 2,000+ for 7 days). 0 = all. Each topic is charged.", "default": 50 }, "trendingNowNewsPerTopic": { "title": "News articles per trending topic", "minimum": 0, "maximum": 10, "type": "integer", "description": "News articles to include for each topic (0 = none, which is a little faster). No extra charge.", "default": 3 }, "onlyNew": { "title": "Only new items (monitor mode)", "type": "boolean", "description": "For scheduled runs: return only trending topics and rising related queries that no earlier run with the same memory store returned. The first run returns everything and remembers it. Search terms are still delivered (and charged) with their full data; only their rising queries are filtered.", "default": false }, "monitorStoreName": { "title": "Monitor memory (key-value store name)", "pattern": "^[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$", "type": "string", "description": "Named key-value store in your account that remembers what was already returned. Use a different name per schedule to keep separate memories. Letters, digits and hyphens.", "default": "google-trends-monitor" }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Google throttles repeated requests. Apify Proxy is recommended; sessions and IPs rotate automatically.", "default": { "useApifyProxy": true } }, "useResidentialFallback": { "title": "Fall back to residential proxy when blocked", "type": "boolean", "description": "If Google keeps blocking the default proxy, switch to Apify residential proxy automatically. No extra cost to you.", "default": true }, "maxConcurrency": { "title": "Parallel sessions", "minimum": 1, "maximum": 10, "type": "integer", "description": "How many terms to look up at the same time, each with its own session and IP. Higher is faster for big lists.", "default": 5 }, "maxRetries": { "title": "Max retries per request", "minimum": 0, "maximum": 15, "type": "integer", "description": "How many times to retry with a fresh session and IP when Google throttles a request.", "default": 8 }, "maxSecondsPerTerm": { "title": "Time limit per term (seconds)", "minimum": 20, "maximum": 600, "type": "integer", "description": "Stop retrying a term after this long so one stubborn keyword can't stall the run. The term is reported as failed and not charged. The run also stops starting new terms shortly before its own timeout, so it finishes cleanly instead of timing out.", "default": 90 }, "delayBetweenRequestsSecs": { "title": "Delay between requests (seconds)", "minimum": 0, "maximum": 30, "type": "integer", "description": "Pause between requests in each session to stay under Google’s rate limits.", "default": 1 } } }, "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 } } } } } } } } } }