{ "openapi": "3.0.1", "info": { "title": "Google Trends API – Interest, Regions & Related", "description": "Google Trends data at scale: interest over time, by region, related queries and related topics. Compare unlimited terms on one scale, across countries or years, get daily data for 5+ years, plus Google's methodology notes.", "version": "0.1", "x-build-id": "PbWp6Rp7dOkK5FK1i" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/datarelay~google-trends-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-datarelay-google-trends-api", "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/datarelay~google-trends-api/runs": { "post": { "operationId": "runs-sync-datarelay-google-trends-api", "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/datarelay~google-trends-api/run-sync": { "post": { "operationId": "run-sync-datarelay-google-trends-api", "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", "suggest", "reference" ], "type": "string", "description": "`explore` – Google Trends data for search terms (default). `suggest` – find topic ids for terms (e.g. \"Apple – Technology company\"), usable as search terms. `reference` – list of all category ids or location codes.", "default": "explore" }, "searchTerms": { "title": "Search terms", "type": "array", "description": "Search terms or topic ids (`/m/0k8z`) to analyze. Google search operators work: `\"exact phrase\"`, `a + b` (or), `-word` (exclude). Leave empty to get what people search for in the chosen location and category (top and rising queries).", "default": [], "items": { "type": "string" } }, "startUrls": { "title": "Google Trends URLs", "type": "array", "description": "Explore URLs copied from trends.google.com (each URL is one comparison, with its own location, time and category).", "default": [], "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "spreadsheetUrl": { "title": "Google Sheets with search terms", "type": "string", "description": "Link to a Google Sheet shared as \"Anyone with the link can view\". Search terms are read from the first column (a header like \"keyword\" is skipped)." }, "comparison": { "title": "Comparison", "enum": [ "separate", "together", "acrossGeos", "acrossTimes" ], "type": "string", "description": "`separate` – each term on its own 0–100 scale. `together` – all terms on one scale (any number of terms; more than 5 are combined through an anchor term, chosen automatically). `acrossGeos` – each term in several locations on one scale. `acrossTimes` – each term in several periods on one scale (e.g. year over year).", "default": "separate" }, "geo": { "title": "Location", "type": "string", "description": "Country (`US`), region (`US-CA`) or metro (`US-CA-803`) code. Empty = worldwide. Use mode `reference` with `geos` to list all 3,600+ codes.", "default": "" }, "geos": { "title": "Locations to compare", "type": "array", "description": "For comparison `acrossGeos`: location codes compared on one scale, e.g. `US`, `DE`, `PL`.", "default": [], "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", "custom" ], "type": "string", "description": "Period of the data. Choose `custom` to set start and end dates.", "default": "past-12-months" }, "startDate": { "title": "Start date", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2})?$", "type": "string", "description": "For a custom time range: `YYYY-MM-DD`, or `YYYY-MM-DDTHH` for hourly precision (UTC)." }, "endDate": { "title": "End date", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2})?$", "type": "string", "description": "For a custom time range: `YYYY-MM-DD`, or `YYYY-MM-DDTHH` for hourly precision (UTC)." }, "timeRanges": { "title": "Periods to compare", "maxItems": 5, "type": "array", "description": "For comparison `acrossTimes`: periods as `YYYY-MM-DD YYYY-MM-DD` (or presets like `past-12-months`), e.g. `2024-10-01 2024-12-31` and `2025-10-01 2025-12-31`. 2–5 periods (Google compares up to 5 on one scale).", "default": [], "items": { "type": "string" } }, "granularity": { "title": "Data granularity", "enum": [ "native", "daily", "hourly" ], "type": "string", "description": "Google returns weekly or monthly points for long ranges. `daily` / `hourly` fetch overlapping windows and stitch them onto one scale (works with comparison `separate`; each extra window is charged).", "default": "native" }, "category": { "title": "Category id", "minimum": 0, "type": "integer", "description": "Google Trends category (0 = all). Examples: 7 Finance, 71 Food & Drink, 5 Computers & Electronics, 958 Jobs. Mode `reference` lists all 1,426 categories.", "default": 0 }, "property": { "title": "Search type", "enum": [ "web", "images", "news", "shopping", "youtube" ], "type": "string", "description": "Which Google search to analyze.", "default": "web" }, "includeTimeline": { "title": "Interest over time", "type": "boolean", "description": "Timeline with values 0–100 plus metrics (average, peak, recent change, direction) and Google's methodology notes.", "default": true }, "includeRegions": { "title": "Interest by region", "type": "boolean", "description": "Where the term is most popular.", "default": true }, "regionResolution": { "title": "Region resolution", "enum": [ "auto", "COUNTRY", "REGION", "CITY", "DMA" ], "type": "string", "description": "`auto` = countries for worldwide, regions for a country. `CITY` gives cities; `DMA` = US metro areas.", "default": "auto" }, "extraRegionResolutions": { "title": "Additional region resolutions", "type": "array", "description": "Further resolutions in the same run, e.g. `CITY` and `DMA` besides states – one extra request each, returned in `regionsByResolution` (no extra charge).", "items": { "type": "string", "enum": [ "COUNTRY", "REGION", "CITY", "DMA" ], "enumTitles": [ "Countries", "Regions / states", "Cities", "US metro areas (DMA)" ] }, "default": [] }, "includeLowVolumeRegions": { "title": "Include low-volume regions", "type": "boolean", "description": "Also return regions with little search volume.", "default": false }, "includeRelatedQueries": { "title": "Related queries", "type": "boolean", "description": "Top and rising queries searched together with the term.", "default": true }, "includeRelatedTopics": { "title": "Related topics", "type": "boolean", "description": "Top and rising topics (entities) related to the term, with topic ids.", "default": true }, "outputLayout": { "title": "Output layout", "enum": [ "nested", "flat" ], "type": "string", "description": "`nested` – one row per term with all data. `flat` – one row per term and date (best for spreadsheets).", "default": "nested" }, "referenceType": { "title": "Reference list", "enum": [ "categories", "geos" ], "type": "string", "description": "For mode `reference`: which list to return.", "default": "categories" }, "language": { "title": "Language", "type": "string", "description": "Language of topic names and labels, e.g. `en-US`, `de`, `pl`.", "default": "en-US" }, "timezoneOffset": { "title": "Timezone offset (minutes)", "type": "integer", "description": "Google's timezone offset in minutes (0 = UTC, -60 = UTC+1, 300 = UTC-5). Affects hourly data.", "default": 0 }, "maxTerms": { "title": "Max search terms", "minimum": 0, "type": "integer", "description": "Safety limit for long lists (e.g. from a spreadsheet or an AI agent): terms above it are not processed. 0 = no limit.", "default": 0 }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 10, "type": "integer", "description": "How many terms are processed in parallel. Higher is faster but more likely to hit Google's rate limits.", "default": 3 }, "maxRunSecs": { "title": "Max run time (seconds)", "minimum": 0, "type": "integer", "description": "Stop starting new terms after this time and finish with partial results (0 = only the run timeout applies).", "default": 0 }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Google rate-limits by IP. Default: Apify residential proxies with a new IP for every unit of work (most reliable). If your account cannot use residential proxies, the run falls back to your default Apify Proxy.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } } }, "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 } } } } } } } } } }