{ "openapi": "3.0.1", "info": { "title": "Google Trends Scraper & API", "description": "Google Trends API alternative for any number of terms: interest over time by country, region, city or metro, related queries and topics, Trending Now, and calibrated comparisons beyond 5 terms. Daily data across years. From $1.50 per 1,000 results; compact JSON for AI agents.", "version": "0.1", "x-build-id": "fIg2i9ZWnbxtDUMWW" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/cleanpull~google-trends-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-cleanpull-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/cleanpull~google-trends-scraper/runs": { "post": { "operationId": "runs-sync-cleanpull-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/cleanpull~google-trends-scraper/run-sync": { "post": { "operationId": "run-sync-cleanpull-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": { "mode": { "title": "Mode", "enum": [ "explore", "calibrated-comparison", "trending" ], "type": "string", "description": "Explore returns Google Trends data for each term. Calibrated comparison ranks any number of terms on one shared scale (Google compares at most 5 at a time), with error bounds and rescaled time series. Trending Now returns what is trending in a country, with search volume and growth.", "default": "explore" }, "searchTerms": { "title": "Search terms", "type": "array", "description": "Terms to look up, one per line (any number). Each term gets its own record. Example: [\"web scraping\", \"data extraction\"].", "items": { "type": "string" } }, "startUrls": { "title": "Google Trends URLs", "type": "array", "description": "Optional. Google Trends explore URLs (trends.google.com/trends/explore?q=...). Terms, countries, period, category and search type are read from each URL.", "items": { "type": "string", "pattern": "^\\s*https?://trends\\.google\\.com/.*explore" } }, "compare": { "title": "Compare terms on one scale", "type": "boolean", "description": "Compare your terms against each other on Google's shared 0-100 scale, in groups of up to 5 (Google's limit per comparison). Adds a comparison record with the winner, averages and the leading term in each region.", "default": false }, "geo": { "title": "Location", "type": "string", "description": "Where to measure interest. Empty = worldwide. A country code (US, GB, DE), a state or region (US-CA, GB-ENG) or a US metro (US-CA-807).", "default": "" }, "geos": { "title": "Several locations", "type": "array", "description": "Optional. Run every term for each of these locations in one run, for example [\"US\", \"GB\", \"DE\"]. Overrides Location.", "items": { "type": "string" } }, "timeRange": { "title": "Time range", "enum": [ "past-hour", "past-4-hours", "past-day", "past-7-days", "past-30-days", "past-90-days", "past-12-months", "past-5-years", "all-time" ], "type": "string", "description": "The period to measure. Shorter periods give finer points (minutes, hours, days); longer ones give weeks or months.", "default": "past-12-months" }, "customTimeRange": { "title": "Custom time range", "pattern": "^\\s*(\\d{4}-\\d{2}-\\d{2}(T\\d{2})?\\s+\\d{4}-\\d{2}-\\d{2}(T\\d{2})?)?\\s*$", "type": "string", "description": "Optional, overrides Time range. Dates as \"2024-01-01 2024-12-31\", or hours as \"2026-09-01T00 2026-09-03T12\"." }, "category": { "title": "Category", "minimum": 0, "type": "integer", "description": "Optional Google Trends category id to narrow ambiguous terms (0 = all categories). Top-level ids: 3 Arts & Entertainment, 47 Autos & Vehicles, 44 Beauty & Fitness, 22 Books & Literature, 12 Business & Industrial, 5 Computers & Electronics, 7 Finance, 71 Food & Drink, 8 Games, 45 Health, 65 Hobbies & Leisure, 11 Home & Garden, 13 Internet & Telecom, 958 Jobs & Education, 19 Law & Government, 16 News, 299 Online Communities, 14 People & Society, 66 Pets & Animals, 29 Real Estate, 533 Reference, 174 Science, 18 Shopping, 20 Sports, 67 Travel.", "default": 0 }, "property": { "title": "Search type", "enum": [ "web", "images", "news", "youtube", "shopping" ], "type": "string", "description": "Which Google search to measure.", "default": "web" }, "dataTypes": { "title": "Data to collect", "type": "array", "description": "What to collect for each term. Fewer types make runs faster. Related topics are returned only when Google provides them to logged-out visitors, which is often not the case.", "items": { "type": "string", "enum": [ "interestOverTime", "interestByRegion", "relatedQueries", "relatedTopics", "suggestions" ], "enumTitles": [ "Interest over time", "Interest by region", "Related queries (top and rising)", "Related topics (when Google returns them)", "Topic suggestions (Google's entity matches for the term)" ] }, "default": [ "interestOverTime", "interestByRegion", "relatedQueries" ] }, "regionResolution": { "title": "Region detail", "enum": [ "auto", "country", "region", "city", "metro" ], "type": "string", "description": "How fine the interest-by-region breakdown is.", "default": "auto" }, "includeLowVolumeRegions": { "title": "Include low-volume regions", "type": "boolean", "description": "Include regions with little search volume, which Google hides by default.", "default": false }, "dailyResolution": { "title": "Daily points for long ranges", "type": "boolean", "description": "For ranges longer than about 9 months, Google returns weekly or monthly points. Turn this on to get one point per day across the whole range, stitched from overlapping daily windows (one extra request per 7 months of range).", "default": false }, "trendingGeo": { "title": "Trending country", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BA", "BW", "BV", "BR", "IO", "VG", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "BQ", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "SZ", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "KP", "MK", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "KR", "SS", "ES", "LK", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "SD", "SR", "SJ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UM", "VI", "UG", "UA", "AE", "GB", "US", "UY", "UZ", "VU", "VA", "VE", "VN", "WF", "EH", "YE", "ZM", "ZW" ], "type": "string", "description": "Country for Trending Now.", "default": "US" }, "trendingHours": { "title": "Trending window", "enum": [ "4", "24", "48", "168" ], "type": "string", "description": "How far back Trending Now looks.", "default": "24" }, "trendingCategories": { "title": "Trending categories", "type": "array", "description": "Optional. Only trends in these categories.", "items": { "type": "string", "enum": [ "1", "2", "3", "20", "4", "5", "6", "7", "8", "9", "10", "11", "13", "14", "15", "16", "17", "18", "19" ], "enumTitles": [ "Autos and Vehicles", "Beauty and Fashion", "Business and Finance", "Climate", "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" ] } }, "trendingActiveOnly": { "title": "Active trends only", "type": "boolean", "description": "Only trends that are still rising (not ended).", "default": false }, "trendingMaxItems": { "title": "Max trending items", "minimum": 0, "maximum": 1000, "type": "integer", "description": "How many trends to return, highest volume first (0 = all Google lists, often several hundred).", "default": 100 }, "monitorMode": { "title": "Monitor mode", "type": "boolean", "description": "Return only what is new since the previous run with the same monitor name: new trending searches, or new rising queries for your terms. Use with a schedule.", "default": false }, "monitorName": { "title": "Monitor name", "type": "string", "description": "Keeps separate memories for separate monitors (for example \"us-tech\").", "default": "default" }, "outputFormat": { "title": "Output format", "enum": [ "nested", "flat" ], "type": "string", "description": "Nested keeps each term's data together; flat gives one row per date, region or related query.", "default": "nested" }, "fields": { "title": "Fields to return", "type": "array", "description": "Optional. Return only these fields (dotted paths allowed, such as summary.average) to keep output small for AI agents. Empty = everything.", "items": { "type": "string" } }, "maxItems": { "title": "Max results", "minimum": 1, "type": "integer", "description": "Stop after this many billed results (term records, comparisons or trending items). Caps the cost of a run.", "default": 1000 }, "language": { "title": "Language", "type": "string", "description": "Language for names and labels, such as en-US or de.", "default": "en-US" }, "timezone": { "title": "Timezone offset (minutes)", "type": "integer", "description": "Minutes west of UTC for hourly data (0 = UTC, 300 = New York in winter).", "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 } } } } } } } } } }