{ "openapi": "3.0.1", "info": { "title": "Google Trends Scraper | Regions & Topics | from $2.5/1K", "description": "Google Trends for any keyword list: interest over time, by region (down to city), related queries and topics, comparisons and Trending Now with news. Built-in proxies and quota retries, so runs don't fail. From $2.50 per 1,000 keywords with data, $3.00 with related topics. Empty keywords are free.", "version": "1.0", "x-build-id": "WpwjQnBAredJVaArJ" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/thermostatic~google-trends-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-thermostatic-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/thermostatic~google-trends-scraper/runs": { "post": { "operationId": "runs-sync-thermostatic-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/thermostatic~google-trends-scraper/run-sync": { "post": { "operationId": "run-sync-thermostatic-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": "What to scrape", "enum": [ "explore", "trending", "catalog", "yearInSearch" ], "type": "string", "description": "Explore returns Google Trends data for your keywords. Trending now returns the list from trends.google.com/trending (search volume, growth, trend breakdown, news). Catalog lists the location codes, category IDs and topic IDs you can search with. Year in Search returns the ranked lists from trends.google.com/trends/yis.", "default": "explore" }, "keywords": { "title": "Keywords", "maxItems": 10000, "type": "array", "description": "Search terms, one per line. Google Trends topic IDs such as '/m/02vqfm' also work. Required in Explore mode unless you add explore URLs or a keywords file. Up to 10,000 per run (keywords file included).", "items": { "type": "string" } }, "compare": { "title": "Compare keywords with each other", "type": "boolean", "description": "Off: each keyword gets its own report, scaled 0-100 on its own. On: keywords are compared on one relative scale in groups of up to 5 (Google's limit), like typing them side by side on trends.google.com. One result per group.", "default": false }, "normalizeAcrossGroups": { "title": "Put more than 5 keywords on one scale", "type": "boolean", "description": "Compare mode with more than 5 keywords: repeats an anchor keyword in every group and rescales all groups onto one shared 0-100 scale, so keyword #3 and keyword #30 are directly comparable. Only interest over time is rescaled.", "default": false }, "anchorKeyword": { "title": "Anchor keyword", "type": "string", "description": "Keyword repeated in every group when putting more than 5 keywords on one scale. Default: your first keyword. Choose one with steady, mid-to-high interest; a very dominant anchor rounds small keywords to 0." }, "compareGeos": { "title": "Compare locations", "maxItems": 5, "type": "array", "description": "Compare each keyword across 2-5 locations on one scale, e.g. US, GB, DE (like 'coffee' in three countries on trends.google.com). One result per keyword. Replaces the Location field.", "items": { "type": "string" } }, "compareTimeRanges": { "title": "Compare time ranges", "maxItems": 5, "type": "array", "description": "Compare each keyword across 2-5 periods of the same length, e.g. '2025-01-01 2025-06-30' and '2024-01-01 2024-06-30'. Points are aligned by position (day 1 next to day 1). One result per keyword.", "items": { "type": "string" } }, "geo": { "title": "Location", "type": "string", "description": "Country or region code: 'US', 'GB', 'DE', a state like 'US-CA', or a US metro like 'US-CA-807'. Leave empty for worldwide. Catalog mode lists every code.", "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": "Period to analyze. Past hour and 4 hours give one point per minute, past day every 8 minutes, past 7 days hourly, up to 90 days daily, 12 months and 5 years weekly, 2004-present monthly.", "default": "today 12-m" }, "customTimeRange": { "title": "Custom time range", "pattern": "^$|^\\d{4}-\\d{2}-\\d{2}(T\\d{2})? \\d{4}-\\d{2}-\\d{2}(T\\d{2})?$", "type": "string", "description": "Overrides the time range: 'YYYY-MM-DD YYYY-MM-DD', e.g. '2024-01-01 2024-06-30' (daily up to about 9 months, then weekly, then monthly). Hourly: '2024-05-01T00 2024-05-03T12', up to 7 days." }, "category": { "title": "Category", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Google Trends category ID; 0 = all categories. Examples: 7 Finance, 45 Health, 71 Food & Drink, 12 Business & Industrial, 5 Computers & Electronics. Catalog mode lists every ID.", "default": 0 }, "property": { "title": "Search type", "enum": [ "web", "images", "news", "youtube", "froogle" ], "type": "string", "description": "Which Google search property to measure.", "default": "web" }, "dataTypes": { "title": "Data to collect", "maxItems": 4, "uniqueItems": true, "type": "array", "description": "Pick only what you need; fewer data types make runs faster. Related topics add $0.50 per 1,000 keywords that have them (free plan); the other types do not change the price.", "items": { "type": "string", "enum": [ "interestOverTime", "interestByRegion", "relatedQueries", "relatedTopics" ], "enumTitles": [ "Interest over time", "Interest by region", "Related queries", "Related topics" ] }, "default": [ "interestOverTime", "interestByRegion", "relatedQueries", "relatedTopics" ] }, "regionResolution": { "title": "Region resolution", "enum": [ "auto", "COUNTRY", "REGION", "DMA", "CITY" ], "type": "string", "description": "Breakdown for interest by region. Worldwide searches are by country only; a country by region (default), city, and metro area in the US; a US state by metro area (default) or city; other regions and metros by city. Unavailable combinations fall back to Google's default with a note in the result.", "default": "auto" }, "includeLowVolumeRegions": { "title": "Include regions with low search volume", "type": "boolean", "description": "Ask Google for low-search-volume regions too (its 'Include low search volume regions' checkbox): many more countries and cities get a value. Regions still without data are listed with value 0.", "default": false }, "resolveTopics": { "title": "Search topics instead of terms", "type": "boolean", "description": "Looks up each keyword's best-matching Google topic (e.g. 'coffee' -> Coffee, beverage) and searches the topic, which also counts other spellings and languages. The topic ID and type are added to the result. Keywords that already are topic IDs are used as they are.", "default": false }, "exploreUrls": { "title": "Google Trends URLs", "maxItems": 1000, "type": "array", "description": "Paste trends.google.com/trends/explore links: each becomes one result with the link's keywords, locations, time ranges, category and search type (links comparing locations or periods work too).", "items": { "type": "string" } }, "keywordsFileUrl": { "title": "Keywords file (CSV / Google Sheet)", "type": "string", "description": "Link to a CSV or TXT file, or a Google Sheet shared as 'Anyone with the link can view'. Keywords are read from the first column (a 'keyword' header is skipped) and added to the list above. It must be on a public web address." }, "trendingGeo": { "title": "Countries or states", "type": "string", "description": "Where to read trending searches, e.g. 'US', 'GB', 'IN', or a state/region like 'US-CA'. Several, comma separated: 'US, GB, DE'. Catalog mode (trendingGeos) lists every supported location; there is no worldwide list.", "default": "US" }, "trendingTimeWindow": { "title": "Trending in the past", "enum": [ "4", "24", "48", "168" ], "type": "string", "description": "Time window of the trending list.", "default": "24" }, "trendingCategories": { "title": "Categories", "maxItems": 19, "uniqueItems": true, "type": "array", "description": "Only trends in these categories. Empty = all 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": "Only trends still active", "type": "boolean", "description": "Skip trends whose search spike has already ended.", "default": false }, "trendingSort": { "title": "Sort by", "enum": [ "relevance", "title", "search-volume", "recency" ], "type": "string", "description": "Order of the trending searches, as in the page's sort menu. Google's own position is kept in googleRank.", "default": "relevance" }, "maxTrendingItems": { "title": "Max trending searches per location", "minimum": 0, "maximum": 5000, "type": "integer", "description": "Stop after this many trending searches per location (in the chosen order). 0 = all of them (a big country has several hundred per day and over a thousand per week).", "default": 50 }, "includeNews": { "title": "Include news articles", "type": "boolean", "description": "Add the news articles Google shows for each trend (title, source, link, image, time).", "default": true }, "maxNewsPerTrend": { "title": "News articles per trend", "minimum": 1, "maximum": 30, "type": "integer", "description": "Maximum number of news articles per trending search.", "default": 3 }, "catalogTypes": { "title": "Catalogs", "maxItems": 3, "uniqueItems": true, "type": "array", "description": "Reference lists to download, one row each. Names follow the Language setting.", "items": { "type": "string", "enum": [ "geos", "categories", "trendingGeos" ], "enumTitles": [ "Locations (countries, regions, US metros) with their codes", "Categories with their IDs and paths", "Locations with a Trending Now list" ] } }, "autocompleteTerms": { "title": "Find topic IDs for", "maxItems": 500, "type": "array", "description": "Catalog mode: Google's topic suggestions (ID, title, type) for each term, as in the search box on trends.google.com. Use the IDs as keywords.", "items": { "type": "string" } }, "yisYears": { "title": "Year in Search: years", "maxItems": 30, "type": "array", "description": "Years to download, e.g. 2025, 2024. Default: last year. Google publishes a year's lists after it ends; some countries skip some years. At most 200 editions (years × countries) per run.", "items": { "type": "string" } }, "yisGeos": { "title": "Year in Search: countries", "maxItems": 50, "type": "array", "description": "Country codes (e.g. US, GB, DE) or GLOBAL. Default: GLOBAL. Lists are in the country's language. At most 200 editions (years × countries) per run.", "items": { "type": "string" } }, "language": { "title": "Language", "type": "string", "description": "Interface language (hl) for names of regions, topics, categories and formatted dates, e.g. 'en-US', 'de', 'es-419', 'ja'.", "default": "en-US" }, "includeRaw": { "title": "Include Google's raw responses", "type": "boolean", "description": "Adds a 'raw' field with Google's unmodified responses (widgets, timelines, maps, related lists, trending entries) for anything the tidy fields leave out. Makes results much larger.", "default": false }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Optional. The Actor brings its own rotating proxy network at no extra cost to you. Add Apify Proxy or your own proxy URLs only if you need a specific exit; your own proxy URLs replace the built-in network.", "default": { "useApifyProxy": false } }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 50, "type": "integer", "description": "Requests to Google in parallel. Leave empty for automatic (8 through the built-in proxy network, 5 through your proxy, 2 on a direct connection)." } } }, "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 } } } } } } } } } }