{ "openapi": "3.0.1", "info": { "title": "Google Trends Scraper — Interest, Regions & Rising Queries", "description": "Google Trends for many keywords and countries at once: interest over time, by region and city, top and rising related queries, trend metrics (peak, change, direction), comparisons and Trending now. All data in one row. Pay per keyword × location; errors are free.", "version": "0.1", "x-build-id": "7yb40jLsqR1SLiZJC" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/cleancut~google-trends-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-cleancut-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/cleancut~google-trends-scraper/runs": { "post": { "operationId": "runs-sync-cleancut-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/cleancut~google-trends-scraper/run-sync": { "post": { "operationId": "run-sync-cleancut-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 analyze, one per line, e.g. \"coffee\" or \"electric cars\". No limit per run. Empty = demo term \"coffee\".", "items": { "type": "string" } }, "geos": { "title": "Locations", "type": "array", "description": "Country codes (US, GB, AR, DE…), regions (US-CA, GB-ENG, BR-SP) or US metros (US-CA-803). Empty = worldwide. Region and city breakdowns follow the location: countries for worldwide, states for a country, metros for a US state.", "items": { "type": "string" } }, "timeRange": { "title": "Time range", "enum": [ "today 12-m", "now 1-H", "now 4-H", "now 1-d", "now 7-d", "today 1-m", "today 3-m", "today 5-y", "all" ], "type": "string", "description": "Period of the interest-over-time chart. Google picks the point size: minutes for the last hours, days up to 90 days, weeks up to 5 years, months for all time.", "default": "today 12-m" }, "customTimeRange": { "title": "Custom date range", "type": "string", "description": "Optional, replaces the time range above: \"YYYY-MM-DD YYYY-MM-DD\", e.g. \"2024-01-01 2024-12-31\". Data starts on 2004-01-01." }, "mode": { "title": "Mode", "enum": [ "terms", "compare", "trending" ], "type": "string", "description": "Terms: one row per term × location, each term on its own 0–100 scale. Compare: terms in groups of up to 5 on one shared scale, with each term's share of interest and who wins in each region. Trending now: the searches trending in each country (section \"Trending now\"); search terms are ignored.", "default": "terms" }, "include": { "title": "Data to include", "type": "array", "description": "All included by default at no extra cost. Remove what you don't need to get smaller rows. Trend metrics (average, peak, latest value, recent and year-over-year change, direction) are always included.", "items": { "type": "string", "enum": [ "timeline", "regions", "cities", "relatedQueries" ], "enumTitles": [ "Interest over time (timeline)", "Interest by region (countries, states or metros)", "Interest by city (with coordinates)", "Related queries (top and rising, with breakouts)" ] }, "default": [ "timeline", "regions", "cities", "relatedQueries" ] }, "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 the search to a Google Trends category, e.g. \"apple\" in Food & Drink instead of the company.", "default": "0" }, "property": { "title": "Search type", "enum": [ "web", "images", "news", "shopping", "youtube" ], "type": "string", "description": "Which Google search to measure: web (default), images, news, Google Shopping or YouTube.", "default": "web" }, "startUrls": { "title": "Google Trends links (optional)", "type": "array", "description": "Paste links from Google Trends, e.g. https://trends.google.com/trends/explore?q=coffee,tea&geo=US&date=today%2012-m. Their terms, location, dates, category and search type are used as they are (several terms in one link = a comparison). The links are read, not opened.", "items": { "type": "string" } }, "trendingGeos": { "title": "Countries", "type": "array", "description": "2-letter country codes, one per line (US, GB, AR, IN…). Empty = US.", "default": [ "US" ], "items": { "type": "string" } }, "trendingHours": { "title": "Trending in the past", "enum": [ "24", "4", "48", "168" ], "type": "string", "description": "Time window of the trending searches.", "default": "24" }, "trendingCategories": { "title": "Trending categories", "type": "array", "description": "Only 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" ] } }, "onlyActiveTrends": { "title": "Only active trends", "type": "boolean", "description": "Skip trends that Google marks as ended.", "default": false }, "maxTrendingPerGeo": { "title": "Max trending searches per country", "minimum": 0, "maximum": 5000, "type": "integer", "description": "0 = all that Google lists (often 500–1,000 for large countries in 24 hours).", "default": 0 }, "language": { "title": "Language", "type": "string", "description": "Language for place names and date labels (hl), e.g. en-US, es, pt-BR, de. Dates are always in UTC.", "default": "en-US" }, "maxTotalResults": { "title": "Max results", "minimum": 0, "maximum": 1000000, "type": "integer", "description": "Stop after this many charged rows (term × location rows, or trending searches). 0 = no limit. The run's max cost is respected too.", "default": 0 }, "maxConcurrency": { "title": "Parallel searches", "minimum": 1, "maximum": 20, "type": "integer", "description": "Terms analyzed at the same time. Google Trends limits fast clients: 6 is fast and stable; raise it only if you see no \"RATE_LIMITED\" retries in the summary.", "default": 6 }, "connectDirectFirst": { "title": "Connect directly first", "type": "boolean", "description": "Try a direct connection first (fastest and cheapest) and use the proxy below only for temporary errors. Turn off to send every request through the proxy.", "default": true }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Fallback when Google Trends answers with a temporary error (HTTP 429 or 5xx): Apify datacenter proxy or your own proxy URLs. Residential and SERP groups are not supported (they cost more than the results) and are replaced by datacenter.", "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 } } } } } } } } } }