{ "openapi": "3.0.1", "info": { "title": "Google Trends & Keyword Research API", "description": "Google Trends for many keywords per run: interest over time with growth %, YoY and seasonality, rising and top related queries and topics, interest by region, Trending Now, and Google Autocomplete keyword ideas. Pay per keyword. Works as an MCP server for AI agents.", "version": "0.0", "x-build-id": "nkGuXsEOxdglCUaPL" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/jixiaohao~google-trends-keyword-research/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-jixiaohao-google-trends-keyword-research", "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/jixiaohao~google-trends-keyword-research/runs": { "post": { "operationId": "runs-sync-jixiaohao-google-trends-keyword-research", "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/jixiaohao~google-trends-keyword-research/run-sync": { "post": { "operationId": "run-sync-jixiaohao-google-trends-keyword-research", "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": { "keywords": { "title": "Seed keywords", "type": "array", "description": "Keywords or phrases to research. One dataset item is produced per keyword. Free Apify plan runs are capped at 10 keywords.", "items": { "type": "string" } }, "geo": { "title": "Country", "type": "string", "description": "Two-letter country code (e.g. US, GB, DE). Leave empty for worldwide. Also used as the Autocomplete market.", "default": "US" }, "language": { "title": "Language", "type": "string", "description": "Language code for Trends and Autocomplete (e.g. en, de, es).", "default": "en" }, "timeframe": { "title": "Timeframe", "enum": [ "now 7-d", "today 1-m", "today 3-m", "today 12-m", "today 5-y", "all" ], "type": "string", "description": "Google Trends time range.", "default": "today 12-m" }, "category": { "title": "Trends category ID", "minimum": 0, "type": "integer", "description": "Google Trends category ID (0 = all categories).", "default": 0 }, "searchProperty": { "title": "Search property", "enum": [ "", "youtube", "images", "news", "froogle" ], "type": "string", "description": "Which Google search to measure.", "default": "" }, "includeTrends": { "title": "Fetch Google Trends", "type": "boolean", "description": "Interest over time, growth metrics, related queries and topics.", "default": true }, "includeRegions": { "title": "Include interest by region", "type": "boolean", "description": "Sub-region breakdown (states for a country, countries for worldwide).", "default": true }, "includeYoY": { "title": "Include year-over-year growth", "type": "boolean", "description": "Compare the latest 4 weeks with the same weeks a year earlier, so seasonal keywords aren't mistaken for growing ones. Adds one Trends query per keyword when the timeframe is shorter than 5 years.", "default": true }, "includeTrendingNow": { "title": "Include Trending Now", "type": "boolean", "description": "Add one item with today's trending searches for the selected country (approximate traffic, start time, news links). Works with an empty keyword list.", "default": false }, "includeAutocomplete": { "title": "Fetch Autocomplete keyword ideas", "type": "boolean", "description": "Google Autocomplete suggestions for the keyword plus the expansion modifiers below.", "default": true }, "autocompleteExpansion": { "title": "Autocomplete expansion", "enum": [ "none", "questions", "full" ], "type": "string", "description": "How many query variants to send to Autocomplete per keyword. 'questions' adds how/what/why/best/vs style prefixes and suffixes; 'full' also adds a-z.", "default": "questions" }, "compareInOneChart": { "title": "Compare keywords on one scale", "type": "boolean", "description": "Also query Trends with up to 5 keywords at once so their 0-100 values are directly comparable. Adds one extra item with type 'comparison' per group of 5.", "default": false }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Google rate-limits Trends aggressively. Residential proxies are strongly recommended.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }, "maxRetries": { "title": "Max retries per request", "minimum": 0, "maximum": 20, "type": "integer", "description": "Retries with a fresh proxy session on 429 or blocked responses.", "default": 6 }, "maxConcurrency": { "title": "Keywords in parallel", "minimum": 1, "maximum": 5, "type": "integer", "description": "How many keywords to research at once, each on its own proxy session. Higher is faster but more likely to hit Google rate limits.", "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 }, "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 } } } } } } } } } }