{ "openapi": "3.0.1", "info": { "title": "Google Trends Scraper API: Bulk, Compare, YouTube", "description": "Scrape Google Trends keyword data as JSON or CSV: interest over time, interest by region down to US metro and city, and related queries. Compare up to 5 keywords on one shared 0-100 scale, or bulk-scrape an unlimited list. Web, Images, News, Shopping, YouTube. No start fee; empty runs are free.", "version": "0.0", "x-build-id": "odhxRlSMgY6xx8oOn" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/nimait~google-trends-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-nimait-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/nimait~google-trends-scraper/runs": { "post": { "operationId": "runs-sync-nimait-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/nimait~google-trends-scraper/run-sync": { "post": { "operationId": "run-sync-nimait-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", "required": [ "keywords" ], "properties": { "keywords": { "title": "Keywords", "minItems": 1, "type": "array", "description": "One search term per line. There is no limit on how many keywords you can scrape in a single run when \"Compare keywords\" is off — each one is looked up independently, one after another. Comparison mode is capped at 5 keywords, which is Google's own limit.", "items": { "type": "string" } }, "compare": { "title": "Compare keywords", "type": "boolean", "description": "Off (default): every keyword is scraped independently, so each one gets its own 0-100 scale where 100 is that keyword's own peak. This is what you want for scraping a keyword list. On: all keywords go into one comparison, which puts them on a single shared scale — the peak of the most searched term becomes 100 and everything else is measured against it. That is the only way the numbers are comparable between terms, and it is why a niche keyword next to a huge one often sits in single digits. Comparison mode needs 2 to 5 keywords.", "default": false }, "includeTimeseries": { "title": "Interest over time", "type": "boolean", "description": "The trend line: one value per time bucket for every keyword, plus the period average per keyword. This is the surface most people want.", "default": true }, "includeGeo": { "title": "Interest by region", "type": "boolean", "description": "Where the searches come from, broken down by subregion of your chosen location (or by country when the location is worldwide). Granularity is set by \"Region granularity\" below. Adds one request per keyword.", "default": false }, "includeRelatedQueries": { "title": "Related queries", "type": "boolean", "description": "The searches people also ran, split into top (most common over the period) and rising (fastest growing, where \"Breakout\" means growth above 5000%). Adds one request per keyword.", "default": false }, "includeRelatedTopics": { "title": "Related topics (experimental)", "type": "boolean", "description": "The subjects people also searched for, as Google Knowledge Graph topics rather than raw text. Be warned: Google currently returns nothing for this surface on every keyword we have tested, including keywords resolved to topic entities first. It is left in because it costs you nothing when it is empty — no-data results are never charged for — and it will start working by itself if Google restores the surface. Adds up to three requests per keyword.", "default": false }, "geo": { "title": "Location", "type": "string", "description": "Where to measure search interest. Leave empty for worldwide. Otherwise use a two-letter country code (US, GB, DE, AU) or a country subregion (US-NY, GB-ENG).", "default": "" }, "time": { "title": "Time range", "type": "string", "description": "A preset — 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 — or your own range as two dates, \"2024-01-01 2024-12-31\", or two hours, \"2024-01-01T00 2024-01-07T23\". The bucket size follows the range: hourly for the \"now\" presets and hourly ranges, daily up to about 9 months, weekly for a year, monthly for 5 years and longer. Anything Google cannot read is rejected before the run makes a single request.", "default": "today 12-m" }, "searchType": { "title": "Search type", "enum": [ "web", "images", "news", "shopping", "youtube" ], "type": "string", "description": "Which Google search surface to measure interest on. Web search is the default and the one all the familiar Trends numbers come from. The others measure the same terms inside Google Images, Google News, Google Shopping and YouTube search — useful when a term behaves differently on video or retail than it does on the web.", "default": "web" }, "geoResolution": { "title": "Region granularity", "enum": [ "auto", "country", "region", "dma", "city" ], "type": "string", "description": "How finely to break down \"Interest by region\". Automatic follows Google's own choice for your location: countries when the location is worldwide, subregions when it is a country. Metro (DMA) is a United States concept and only returns data for US locations. City is the finest available and returns fewer rows, because Google only reports places with enough search volume to be meaningful.", "default": "auto" }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Google rate-limits Trends requests by IP. Datacenter proxy is the default: it is included in every Apify plan and measured on the platform it was three times faster than residential while returning identical data. Rate limiting does happen occasionally, and the Actor answers it by rotating to a fresh IP and cookie jar and retrying. Switch to residential if you are running very large batches and want the widest IP pool. Running with no proxy at all works too for occasional small runs.", "default": { "useApifyProxy": true } }, "category": { "title": "Category", "minimum": 0, "type": "integer", "description": "Restricts the search to one Google Trends category, which is the cleanest way to separate meanings of an ambiguous word — \"jaguar\" in Autos & Vehicles (id 47) is a very different trend from \"jaguar\" in Pets & Animals (id 66). Leave at 0 for all categories. Category ids are the ones in the Trends web interface URL (the cat= parameter).", "default": 0 }, "resolveEntities": { "title": "Resolve keywords to topics", "type": "boolean", "description": "Only affects the related-topics surface. When on, each keyword is first matched to a Google topic entity (for example \"coffee\" to the topic Coffee, a Beverage) and the topic lookup uses that entity. Turn it off to query the literal text instead.", "default": true }, "hl": { "title": "Interface language", "type": "string", "description": "Language Google formats the results in. It changes the wording of the human-readable date labels and topic names, not the numbers.", "default": "en-US" }, "tz": { "title": "Time zone offset", "minimum": -1440, "maximum": 1440, "type": "integer", "description": "Minutes from UTC, used to decide where time buckets start and end. 0 (UTC) keeps results reproducible between runs, which is usually what you want for a dataset. Use -300 for US Eastern, 60 for Central European, and so on.", "default": 0 }, "maxRequestRetries": { "title": "Max retries per request", "minimum": 0, "maximum": 5, "type": "integer", "description": "How many times a request to Google is retried before that surface is reported as failed. Retries wait about 2, 6 and 15 seconds, and the Actor switches to a fresh IP and cookie jar from the second retry onwards.", "default": 3 } } }, "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 } } }, "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 } } } } } } } } } }