{ "openapi": "3.0.1", "info": { "title": "Keyword Research — Search Volume, CPC & Ideas", "description": "Google keyword search volume, CPC, competition & 12-month trends, plus keyword ideas, website keywords, difficulty and search intent. Pay per keyword.", "version": "1.0", "x-build-id": "fCcIIRb6uMqaaQs73" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/cheapapi~keyword-research-tool/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-cheapapi-keyword-research-tool", "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/cheapapi~keyword-research-tool/runs": { "post": { "operationId": "runs-sync-cheapapi-keyword-research-tool", "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/cheapapi~keyword-research-tool/run-sync": { "post": { "operationId": "run-sync-cheapapi-keyword-research-tool", "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 do you want?", "enum": [ "searchVolume", "keywordIdeas", "keywordSuggestions", "relatedKeywords", "websiteKeywords", "keywordDifficulty", "searchIntent", "keywordOverview", "historicalData", "aiSearchVolume" ], "type": "string", "description": "Choose the kind of keyword research. Search volume returns metrics for exactly the keywords you enter. The idea modes treat your keywords as seeds and return new keywords. Keywords for a website uses the Websites field below. AI search volume estimates how often each keyword is asked in AI assistants and AI search, with a 12-month trend.", "default": "searchVolume" }, "keywords": { "title": "Keywords", "type": "array", "description": "Required in every mode except Keywords for a website. One keyword or phrase per line (max 80 characters and 10 words each). In the search volume, difficulty, intent, overview, history and AI search volume modes you can enter up to 10,000 keywords. In the idea modes these are the seed keywords (up to 200).", "items": { "type": "string" } }, "country": { "title": "Country", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BA", "BW", "BV", "BR", "IO", "VG", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "BQ", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "SZ", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "KP", "MK", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "KR", "SS", "ES", "LK", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "SD", "SR", "SJ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TM", "TC", "TV", "TR", "UM", "VI", "UG", "UA", "AE", "GB", "US", "UY", "UZ", "VU", "VA", "VE", "VN", "WF", "EH", "YE", "ZM", "ZW" ], "type": "string", "description": "Country whose searches are measured. City or region targeting is available under Advanced.", "default": "US" }, "language": { "title": "Language", "type": "string", "description": "Optional. ISO language code such as en, de, pt, zh-TW (English names like \"German\" also work). Leave empty to use the main language of the country." }, "websites": { "title": "Websites", "type": "array", "description": "Domains or page URLs, one per line, e.g. example.com or https://example.com/blog/post. Returns keywords relevant to the site with volume, CPC and competition. Each analyzed website is charged, even if no keywords are found.", "items": { "type": "string" } }, "websiteScope": { "title": "Analyze", "enum": [ "site", "page" ], "type": "string", "description": "Whether to look at the whole domain or only the given page.", "default": "site" }, "dataSource": { "title": "Data source", "enum": [ "auto", "database", "realtime" ], "type": "string", "description": "Used by the search volume mode. Automatic reads the keyword database; keywords missing from it are listed in the run summary (switches to real-time only for real-time-only options). Real-time always asks the keyword planner (needed for custom date ranges, search partners and coordinates); every real-time request is charged, and a request that returns under 82 keywords with data (163 on Gold) adds a small-batch fee.", "default": "auto" }, "locationCode": { "title": "Location code (city / region)", "minimum": 1, "maximum": 999999999, "type": "integer", "description": "Optional numeric Google Ads geo-target code for a city or region (e.g. 1023191 = New York). Overrides Country. City/region targeting works with real-time planner data and website keywords." }, "locationName": { "title": "Location name (city / region)", "type": "string", "description": "Optional full location name in Google Ads format, e.g. London,England,United Kingdom. Overrides Country." }, "coordinates": { "title": "Coordinates", "type": "string", "description": "Optional \"latitude,longitude\" (e.g. 40.7128,-74.0060) to measure searches around a point. Real-time planner only." }, "processingSpeed": { "title": "Processing speed", "enum": [ "auto", "fast", "economy" ], "type": "string", "description": "Applies to real-time planner lookups and website keywords. The price is the same in every mode.", "default": "auto" }, "includeMonthlyTrend": { "title": "Include monthly trend", "type": "boolean", "description": "Adds a monthlyTrend array (aiMonthlyTrend in the AI mode) with the search volume of each recent month.", "default": true }, "trendMonths": { "title": "Months in trend", "minimum": 1, "maximum": 60, "type": "integer", "description": "How many most-recent months to keep in the trend (the default planner range is 12 months; the keyword database keeps up to about 4 years; AI search volume has 12 months).", "default": 12 }, "dateFrom": { "title": "Trend start date", "type": "string", "description": "Real-time planner only: first month of the trend (YYYY-MM-DD, up to 4 years back). Setting a date switches the data source to real-time." }, "dateTo": { "title": "Trend end date", "type": "string", "description": "Real-time planner only: last month of the trend (cannot be later than the last full month)." }, "includeSearchPartners": { "title": "Include Google search partners", "type": "boolean", "description": "Real-time planner and website keywords: count searches on Google search-partner sites too.", "default": false }, "includeAdultKeywords": { "title": "Include adult keywords", "type": "boolean", "description": "Real-time planner and website keywords: keep adult keywords in the results.", "default": false }, "includeSerpInfo": { "title": "Include search results info", "type": "boolean", "description": "Database modes: adds which result types appear on the Google results page (featured snippet, local pack, …) and the total number of results.", "default": false }, "includeDemographics": { "title": "Include audience demographics", "type": "boolean", "description": "Search volume (keyword database), overview and idea modes: adds age and gender distribution of searchers plus an alternative volume estimate. Charged as an extra event only for rows that come back with demographics; the data request (and any check/no-result fee) is charged twice because the lookup costs twice as much (see pricing).", "default": false }, "maxResults": { "title": "Maximum results (whole run)", "minimum": 1, "maximum": 100000, "type": "integer", "description": "Hard cap on the number of dataset rows for the whole run. The run stops cleanly when it is reached.", "default": 5000 }, "deduplicate": { "title": "Remove duplicate keywords", "type": "boolean", "description": "Idea modes: if several seeds return the same keyword it is output (and charged as a result) once; later copies cost the $0.0002 check fee.", "default": true }, "maxIdeasPerSeed": { "title": "Max ideas per seed", "minimum": 1, "maximum": 10000, "type": "integer", "description": "How many ideas to return for each seed keyword. In \"Keyword ideas\" mode all seeds are combined, so this is the total.", "default": 100 }, "sortBy": { "title": "Sort ideas by", "enum": [ "relevance", "searchVolumeDesc", "searchVolumeAsc", "cpcDesc", "competitionAsc", "keywordDifficultyAsc", "keywordDifficultyDesc" ], "type": "string", "description": "Order in which ideas are selected and returned. Also used by the real-time planner (difficulty sorting falls back to relevance there).", "default": "relevance" }, "relatedDepth": { "title": "Related keywords depth", "minimum": 0, "maximum": 4, "type": "integer", "description": "Related keywords mode: how many hops away from the seed to explore (0 = seed only, 4 = widest, up to thousands of keywords).", "default": 1 }, "includeSeedKeyword": { "title": "Include the seed keyword", "type": "boolean", "description": "Suggestions and related modes: also output a row for the seed keyword itself.", "default": false }, "closelyRelatedOnly": { "title": "Closely related only", "type": "boolean", "description": "Keyword ideas mode: return only ideas very close in meaning to the seeds.", "default": false }, "exactMatch": { "title": "Exact phrase match", "type": "boolean", "description": "Suggestions mode: only return phrases containing the seed words in the same order.", "default": false }, "ignoreSynonyms": { "title": "Ignore near-duplicate synonyms", "type": "boolean", "description": "Idea modes: skip keywords that are only word-order or plural variants of another result.", "default": false }, "replaceWithCoreKeyword": { "title": "Use core keyword", "type": "boolean", "description": "Related keywords mode: replace each keyword with the main keyword of its synonym group.", "default": false }, "offset": { "title": "Skip first N ideas", "minimum": 0, "maximum": 9999, "type": "integer", "description": "Idea modes: start from the N-th idea (useful to continue a previous run).", "default": 0 }, "minSearchVolume": { "title": "Min search volume", "minimum": 0, "maximum": 1000000000, "type": "integer", "description": "Only keep keywords with at least this monthly search volume (AI search volume in the AI mode)." }, "maxSearchVolume": { "title": "Max search volume", "minimum": 0, "maximum": 1000000000, "type": "integer", "description": "Only keep keywords with at most this monthly search volume (AI search volume in the AI mode)." }, "minCpc": { "title": "Min CPC (USD)", "minimum": 0, "maximum": 10000, "type": "number", "description": "Only keep keywords with a cost-per-click (USD) of at least this amount, e.g. 0.5." }, "maxCpc": { "title": "Max CPC (USD)", "minimum": 0, "maximum": 10000, "type": "number", "description": "Only keep keywords with a cost-per-click (USD) of at most this amount, e.g. 5." }, "minKeywordDifficulty": { "title": "Min keyword difficulty", "minimum": 0, "maximum": 100, "type": "integer", "description": "Idea modes: only keep keywords with difficulty ≥ this value (0–100)." }, "maxKeywordDifficulty": { "title": "Max keyword difficulty", "minimum": 0, "maximum": 100, "type": "integer", "description": "Idea modes: only keep keywords with difficulty ≤ this value (0–100). Great for finding easy wins." }, "searchIntents": { "title": "Search intent", "type": "array", "description": "Idea modes: only keep keywords with one of these main intents.", "items": { "type": "string", "enum": [ "informational", "navigational", "commercial", "transactional" ], "enumTitles": [ "Informational", "Navigational", "Commercial", "Transactional" ] } }, "mustContain": { "title": "Keyword must contain", "maxLength": 80, "type": "string", "description": "Only keep keywords containing this word or phrase." }, "mustNotContain": { "title": "Keyword must not contain", "maxLength": 80, "type": "string", "description": "Drop keywords containing this word or phrase." } } }, "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 } } } } } } } } } }