{ "openapi": "3.0.1", "info": { "title": "Google Trends Scraper & API", "description": "Google Trends interest over time, by region, related queries and topics as JSON, CSV or Excel. Pay only for keywords that return data. No browser, never hangs, unlimited keywords on one scale, daily data over years, works with AI agents (MCP).", "version": "0.1", "x-build-id": "FfnKKZ0Q0fnmBSdB6" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/curiousanand~google-trends-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-curiousanand-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/curiousanand~google-trends-scraper/runs": { "post": { "operationId": "runs-sync-curiousanand-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/curiousanand~google-trends-scraper/run-sync": { "post": { "operationId": "run-sync-curiousanand-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", "type": "array", "description": "Keywords to look up. With 'Comma = compare' on, \"tea, coffee\" charts both terms together.", "items": { "type": "string" } }, "startUrls": { "title": "Google Trends URLs", "type": "array", "description": "Paste trends.google.com/trends/explore URLs. Their own terms, region, dates, category and property are used.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "mode": { "title": "Mode", "type": "string", "description": "separate: each term on its own 0–100 scale. compare: up to 5 terms on one chart. normalize: any number of terms on ONE shared scale (anchor method).", "default": "separate" }, "anchorTerm": { "title": "Anchor term (normalize mode)", "type": "string", "description": "Optional. A term of medium popularity included in every batch. Leave empty to pick one automatically." }, "isMultiple": { "title": "Comma = compare", "type": "boolean", "description": "Treat commas inside a search term as a comparison of up to 5 terms (same as apify/google-trends-scraper).", "default": false }, "timeRange": { "title": "Time range", "type": "string", "description": "Preset range, or plain English like \"past 7 days\" or \"last 3 months\". Ignored if a custom range is set.", "default": "today 12-m" }, "customTimeRange": { "title": "Custom time range", "type": "string", "description": "\"YYYY-MM-DD YYYY-MM-DD\", e.g. \"2024-01-01 2024-12-31\". Overrides the preset." }, "dailyResolution": { "title": "Daily data for long ranges", "type": "boolean", "description": "Google only gives daily points for ranges up to ~9 months. Turn this on to get daily data for any range (stitched from overlapping windows). Uses more requests.", "default": false }, "geo": { "title": "Region", "type": "string", "description": "Country or region code (US, GB, US-CA) or a country name (\"Germany\"). Empty = worldwide.", "default": "" }, "geos": { "title": "Several countries (optional)", "maxItems": 50, "type": "array", "description": "Run every keyword in each of these countries or regions, e.g. [\"US\", \"GB\", \"Germany\"]. Each keyword × country is billed as one keyword. Leave empty to use \"Region\" above.", "items": { "type": "string" } }, "category": { "title": "Category id", "type": "string", "description": "Google Trends category id, e.g. 71 for Food & Drink (the cat= number in a Trends URL). Empty or 0 = all categories.", "default": "" }, "property": { "title": "Search type", "type": "string", "description": "Which Google search to measure: web, image, news, YouTube or Google Shopping searches.", "default": "web" }, "sections": { "title": "Data to fetch", "minItems": 1, "type": "array", "description": "Fewer sections = faster and fewer requests. Related topics add a small `related-topics` charge, applied only to keywords that actually returned topics.", "items": { "type": "string", "enumSuggestedValues": [ "timeline", "regions", "relatedQueries", "relatedTopics" ], "enumTitles": [ "Interest over time", "Interest by region", "Related queries", "Related topics" ] }, "default": [ "timeline", "regions", "relatedQueries", "relatedTopics" ] }, "regionResolution": { "title": "Region detail", "type": "string", "description": "How detailed the \"interest by region\" data is. Automatic uses Google's default for the chosen region.", "default": "AUTO" }, "includeLowVolumeRegions": { "title": "Include low-volume regions", "type": "boolean", "description": "Also return regions with too little search volume for Google to score (they appear with no data).", "default": false }, "useTopics": { "title": "Use topics instead of search terms", "type": "boolean", "description": "Looks up each term's Knowledge Graph topic (merges spellings and languages), like picking the 'Topic' suggestion on Google Trends.", "default": false }, "outputFormat": { "title": "Output format", "type": "string", "description": "nested (default): one item per keyword using the main field names of apify/google-trends-scraper — cheapest. rows: one row per date / region / related item, ideal for CSV, Excel and Sheets; billed per 1,000 rows because it stores ~100+ items per keyword.", "default": "nested" }, "language": { "title": "Language", "type": "string", "description": "Language for region names and related items, e.g. en-US, de, fr.", "default": "en-US" }, "maxItems": { "title": "Max inputs", "minimum": 0, "type": "integer", "description": "Process at most this many inputs (0 = all).", "default": 0 }, "maxConcurrency": { "title": "Max parallel keywords", "minimum": 1, "maximum": 50, "type": "integer", "description": "How many keywords are fetched in parallel. The scraper also slows itself down automatically if Google throttles.", "default": 10 }, "maxRequestRetries": { "title": "Max retries per request", "minimum": 0, "maximum": 10, "type": "integer", "description": "How many times a failed request is retried (on a fresh IP, with backoff) before the keyword is marked failed.", "default": 5 }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Starts on Apify datacenter proxies and switches to residential automatically if Google blocks them.", "default": { "useApifyProxy": true } }, "residentialFallback": { "title": "Auto-switch to residential proxies", "type": "boolean", "description": "If Google blocks the datacenter IPs, switch to Apify residential proxies automatically for the rest of the run.", "default": true }, "viewedFrom": { "title": "Proxy country", "type": "string", "description": "Optional country for proxy IPs (e.g. 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 } } } } } } } } } }