{ "openapi": "3.0.1", "info": { "title": "Google Trends Scraper: Keywords & Trending Searches", "description": "Bulk Google Trends API alternative: interest over time, by country, region and city, rising and Breakout queries, trending searches now. Compare more than 5 keywords on one scale. CSV for Sheets and Looker Studio, Slack alerts. $2.50 per 1,000 searches, all included.", "version": "0.1", "x-build-id": "TuGAG00PEEYvyjD2i" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/dgn-lab~google-trends-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-dgn-lab-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/dgn-lab~google-trends-scraper/runs": { "post": { "operationId": "runs-sync-dgn-lab-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/dgn-lab~google-trends-scraper/run-sync": { "post": { "operationId": "run-sync-dgn-lab-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 on Google Trends. One dataset item is saved per search term. A Knowledge Graph topic id such as /m/0k8z or /g/11b6d6l8xz is queried as a topic (all spellings and languages of the subject) instead of literal text.", "items": { "type": "string" } }, "compareTerms": { "title": "Compare terms together", "type": "boolean", "description": "Compare up to five terms using a native Google comparison. Larger lists use the first term as an anchor to estimate a common scale across separate requests. Inspect scale and errors; calibration is approximate.", "default": false }, "anchorTerm": { "title": "Anchor term (more than 5 terms)", "type": "string", "description": "Term used to link comparisons when more than 5 terms are compared. Pick a term of medium popularity among yours: a much more popular anchor crushes the other terms to values near 0. Defaults to the first search term.", "default": "" }, "trendsUrls": { "title": "Google Trends URLs", "type": "array", "description": "Paste explore URLs copied from trends.google.com, e.g. https://trends.google.com/trends/explore?q=chatgpt,claude&geo=FR&date=today%203-m. Each URL is one comparison and keeps its own terms (up to 5), location, period, category and search type; the options below apply only to Search terms.", "items": { "type": "object", "properties": { "url": { "type": "string", "title": "URL", "description": "Google Trends explore URL." } }, "required": [ "url" ], "additionalProperties": true }, "default": [] }, "trendingNowGeos": { "title": "Trending search countries", "type": "array", "description": "Country codes (e.g. US, FR, GB) to also get the searches trending right now in each country, with approximate traffic.", "items": { "type": "string" }, "default": [] }, "geo": { "title": "Location", "type": "string", "description": "Country or region code, e.g. US, FR, GB or US-CA. Leave empty for worldwide. Use \"Locations\" below to run the same terms in several countries.", "default": "" }, "geos": { "title": "Locations (several countries)", "type": "array", "description": "Run every search term in each of these country or region codes (e.g. US, FR, DE). One item per term and location; values are relative within each location. Overrides Location when set.", "items": { "type": "string" }, "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 covered by the data.", "default": "today 12-m" }, "customTimeRange": { "title": "Custom time range", "pattern": "^$|^\\d{4}-\\d{2}-\\d{2} \\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "Optional custom period as \"YYYY-MM-DD YYYY-MM-DD\", e.g. \"2024-01-01 2024-06-30\". Overrides Time range.", "default": "" }, "category": { "title": "Category", "minimum": 0, "type": "integer", "description": "Google Trends category ID, e.g. 0 = all categories, 5 = Computers & Electronics, 7 = Finance.", "default": 0 }, "property": { "title": "Search type", "enum": [ "", "images", "news", "froogle", "youtube" ], "type": "string", "description": "Google property the searches come from.", "default": "" }, "language": { "title": "Language", "type": "string", "description": "Language of labels such as region names and dates, e.g. en-US or fr.", "default": "en-US" }, "outputMode": { "title": "Output format", "enum": [ "summaries", "timeSeries", "both" ], "type": "string", "description": "summaries: one row per search term with the full interestOverTime array and analytics (default). timeSeries: one flat row per date, search term and location (columns searchTerm, geo, date, value...), ready to open as CSV in Excel, Sheets or Looker Studio; no summary rows. both: summary rows followed by their time-series rows. Billing is one search per search term and location with data, in every format, never per date.", "default": "summaries" }, "includeInterestByRegion": { "title": "Include interest by region", "type": "boolean", "description": "Add interest per country or sub-region.", "default": true }, "geoResolution": { "title": "Region resolution", "enum": [ "", "COUNTRY", "REGION", "CITY", "DMA" ], "type": "string", "description": "Level of detail for interest by region. Leave on Automatic for Google's default (countries worldwide, regions inside a country). COUNTRY works only worldwide; REGION only with a country location (US, FR); CITY and DMA (metro areas in the US, second-level subdivisions such as departments elsewhere) work for any location. An incompatible combination falls back to Google's default and is reported in errors.", "default": "" }, "includeRelated": { "title": "Include related queries", "type": "boolean", "description": "Add top and rising related queries.", "default": true }, "includeRelatedTopics": { "title": "Include related topics", "type": "boolean", "description": "Add top and rising related topics (Knowledge Graph entities such as brands, people or places). Google currently often returns empty topic lists to automated requests; empty lists are free and noted in errors.", "default": false }, "trendWindowPoints": { "title": "Trend comparison window", "minimum": 1, "maximum": 365, "type": "integer", "description": "Compare the last N complete observations with the preceding N. Points can be hourly, daily or weekly depending on the selected period. Partial and missing points are excluded. trendChangePercent is null if fewer than 2N complete points exist or the previous average is zero; trendDirection is null below 2N complete points.", "default": 7 }, "trendDirections": { "title": "Keep only these trend directions", "uniqueItems": true, "type": "array", "description": "Optional filter on keyword rows by trendDirection. Keyword rows with data whose direction is not in the list (including rows whose direction cannot be computed) are neither saved nor charged; they are counted in the SUMMARY record (filteredOut). With time series output, only the dates of kept terms are saved. Rows without data (noData, failed) are diagnostics and stay in the summaries. Trending-now rows are not filtered. Leave empty to keep every keyword.", "items": { "type": "string", "enum": [ "breakout", "rising", "steady", "declining", "dead" ], "enumTitles": [ "Breakout", "Rising", "Steady", "Declining", "Dead" ] }, "default": [] }, "includeMatchedTopics": { "title": "Include matched topics", "type": "boolean", "description": "Add matchedTopics: the Knowledge Graph topics Google Trends suggests for each search term (one extra autocomplete request per term). Useful to switch from a literal search term to a topic. No extra charge.", "default": false }, "resolveToMainTopic": { "title": "Query the main topic instead of the literal term", "type": "boolean", "description": "Replace each literal search term by the first Knowledge Graph topic Google Trends suggests for it (for example apple becomes Apple Inc., Technology company) and query that topic. Rows keep your searchTerm and add searchTermLabel, queriedAs and topicMid. A term without a suggestion is queried as typed. One extra autocomplete request per distinct term, no extra charge.", "default": false }, "notificationWebhookUrl": { "title": "Notification webhook URL", "type": "string", "description": "Optional. After the run, post one alert message listing keywords that are trending up and trending searches above the traffic threshold. Slack incoming webhooks (hooks.slack.com), Discord webhooks (discord.com/api/webhooks/...) and Telegram bots (https://api.telegram.org/bot/sendMessage?chat_id=) get a chat message; any other URL receives JSON. Nothing is sent when no row matches. A failed delivery is logged without the URL and never fails the run." }, "alertMinTrendChangePercent": { "title": "Alert: minimum trend change (%)", "type": "integer", "description": "Alert on a keyword when its trendChangePercent (recent window vs the previous one) is at least this value. Keywords whose trendDirection is breakout always alert when a webhook is set. Leave empty to alert on breakouts only." }, "alertMinTraffic": { "title": "Alert: minimum trending traffic", "minimum": 0, "type": "integer", "description": "Alert on a trending-now search when its approximate traffic (approxTrafficMin) is at least this number of searches. Leave empty to send no trending-now alerts." }, "onlyNewTrends": { "title": "Alert only on new trends", "type": "boolean", "description": "For scheduled runs. Remember, in the key-value store named in \"State store name\", which trending searches and keyword trend states earlier runs already alerted, and send the webhook only new ones: trending searches not seen in the last 48 hours, and keywords that newly entered breakout or rising (a keyword alerts again after its direction changed and came back). Each row gets isNewTrend. The dataset still holds every row unless \"Save only new rows\" is on. An alert that could not be delivered is retried by the next run.", "default": false }, "onlyNewRows": { "title": "Save only new rows", "type": "boolean", "description": "Also leave out of the dataset (and of the charge) the trending searches and keyword rows already seen by an earlier run with the same state store. A trending list is charged as one search only when at least one new trending search is saved. Rows without a trend to track (noData, failed, too few points) are always saved. Off by default: most schedules want the full data each run and only want alerts deduplicated.", "default": false }, "stateStoreName": { "title": "State store name", "pattern": "^[a-zA-Z0-9-]{1,63}$", "type": "string", "description": "Named key-value store that keeps what earlier runs saw (record TREND_MONITOR_STATE), used only when \"Alert only on new trends\" or \"Save only new rows\" is on. It outlives the run. Use one name per monitor: schedules sharing a name share their memory.", "default": "google-trends-monitor" }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 10, "type": "integer", "description": "How many keyword groups are fetched in parallel, each on its own session (and proxy IP). Google rate-limits hard: the Actor lowers this automatically after HTTP 429 responses and raises it back after a run of successes.", "default": 3 }, "maxRetries": { "title": "Max retries on rate limit", "minimum": 0, "maximum": 10, "type": "integer", "description": "How many times a rate-limited or slow request is retried with a new session (and a new IP when a proxy is used).", "default": 6 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Apify Proxy is enabled by default. Availability and traffic charges follow your account and plan. New proxy sessions can help with 429 responses but do not guarantee a different IP or a successful retry.", "properties": { "useApifyProxy": { "type": "boolean", "title": "Use Apify Proxy", "description": "Whether to use Apify Proxy." }, "apifyProxyGroups": { "type": "array", "items": { "type": "string" }, "title": "Apify Proxy groups", "description": "Proxy groups requested from Apify Proxy." }, "apifyProxyCountry": { "type": "string", "title": "Proxy country", "description": "Country code for the requested proxy exit." }, "proxyUrls": { "type": "array", "items": { "type": "string" }, "title": "Custom proxy URLs", "description": "URLs of custom proxy servers." } }, "default": { "useApifyProxy": true }, "additionalProperties": 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 } } } } } } } } } }