{ "openapi": "3.0.1", "info": { "title": "Keyword Research API: Search Volume, CPC, Difficulty, Intent", "description": "Keyword search volume (Google, plus Bing on 300+ keywords), AI search volume, CPC, difficulty, intent and SERP features in bulk, plus long-tail ideas and keywords of up to 10 competitors. Keyword Planner alternative. $2 per 1,000.", "version": "0.1", "x-build-id": "PGsa5K8sD1h3mNxvY" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/gaelasao~keyword-research-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-gaelasao-keyword-research-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/gaelasao~keyword-research-api/runs": { "post": { "operationId": "runs-sync-gaelasao-keyword-research-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/gaelasao~keyword-research-api/run-sync": { "post": { "operationId": "run-sync-gaelasao-keyword-research-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": { "keywords": { "title": "Keywords", "minItems": 1, "maxItems": 10000, "type": "array", "description": "Metrics mode: 1 to 10,000 keywords, one per line. Duplicates and extra spaces are removed and keywords are lowercased. Each keyword can have up to 80 characters and 10 words. Ideas mode: 1 to 20 seed keywords. Domain mode: not used.", "items": { "type": "string" } }, "mode": { "title": "Mode", "enum": [ "metrics", "ideas", "domain" ], "type": "string", "description": "Metrics returns one row per keyword you provide. Ideas returns related keywords for your seed keywords. Domain returns the keywords a website ranks for on Google, with its position, ranking URL and estimated traffic.", "default": "metrics" }, "ideasMethod": { "title": "Ideas method (ideas mode)", "enum": [ "ideas", "suggestions", "related" ], "type": "string", "description": "Ideas: broad keyword ideas from the same topics. Suggestions: long-tail phrases that contain your seed. Related: Google's related searches, up to 4 levels deep. Suggestions and related run once per seed.", "default": "ideas" }, "domain": { "title": "Domain or page (domain mode)", "type": "string", "description": "Domain mode only: a website such as \"example.com\", or one page URL. Returns the keywords it ranks for in the chosen country, best traffic first." }, "domains": { "title": "More websites (domain mode)", "type": "array", "description": "Domain mode only: up to 10 websites in total with \"domain\", to compare competitors in one run. Maximum rows applies to each website.", "items": { "type": "string" } }, "location": { "title": "Country", "type": "string", "description": "Pick a country, or type an ISO code (US), a country name (United Kingdom) or a DataForSEO location_code (2840). The 94 listed countries have every metric. Other location codes, such as cities, return Google Ads metrics only (no difficulty, intent or trend) and do not support ideas mode.", "default": "US" }, "language": { "title": "Language", "type": "string", "description": "Leave empty to use the main language of the country (for example English for the US, German for Switzerland). A language the country does not support in DataForSEO Labs returns Google Ads metrics only." }, "includeTrend": { "title": "Include 12-month history and trend", "type": "boolean", "description": "Adds monthly search volumes for the last 12 months and the monthly, quarterly and yearly trend (%) to each row. Turn off for smaller exports. The price is the same.", "default": true }, "includeAiVolume": { "title": "Include AI search volume", "type": "boolean", "description": "Adds ai_search_volume to each row with data: an estimate of how often the keyword comes up in AI assistants such as ChatGPT (DataForSEO AI keyword data), with its 12-month history when the history option is on. Included at no extra cost. Null where DataForSEO has no AI data.", "default": true }, "includeSerpInfo": { "title": "Include SERP features", "type": "boolean", "description": "Adds serp_features (AI Overview, featured snippet, People Also Ask, local pack, video, shopping and more) and serp_url to each row with full metrics. Included at no extra cost.", "default": true }, "includeBing": { "title": "Include Bing search volume (runs of 300+ keywords)", "type": "boolean", "description": "On runs of 300 keywords or more, adds bing_search_volume, bing_cpc and bing_competition from Bing Ads to each row with data, at no extra cost. English, French and German, in the countries Bing covers. Smaller runs skip it.", "default": true }, "maxIdeas": { "title": "Maximum rows (ideas and domain modes)", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Ideas mode: rows to return, up to 5,000 (per seed with the suggestions and related methods). Domain mode: rows per website. You pay only for the rows delivered.", "default": 100 }, "minSearchVolume": { "title": "Minimum monthly search volume", "minimum": 0, "maximum": 1000000000, "type": "integer", "description": "Only return keywords with at least this average monthly search volume. Keywords below it, or without volume data, are left out and not charged. 0 keeps everything.", "default": 0 }, "maxKeywords": { "title": "Maximum keywords per run", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Optional cap on billed rows. Metrics mode looks up only the first N unique keywords; the rest are listed in SUMMARY. Your maximum cost per run still applies." }, "includeTerms": { "title": "Keep keywords containing (ideas and domain modes)", "type": "array", "description": "Up to 3 words or phrases. Only keywords that contain at least one of them are returned, for example \"best\" or \"near me\".", "items": { "type": "string" } }, "excludeTerms": { "title": "Leave out keywords containing (ideas and domain modes)", "type": "array", "description": "Up to 3 words or phrases, such as brand names or \"free\". Keywords that contain any of them are left out and not charged.", "items": { "type": "string" } }, "minPosition": { "title": "Best ranking position (domain mode)", "minimum": 1, "maximum": 100, "type": "integer", "description": "Domain mode: only keywords where the website ranks at this position or lower. Use 4 with a maximum of 20 for striking-distance keywords." }, "maxPosition": { "title": "Worst ranking position (domain mode)", "minimum": 1, "maximum": 100, "type": "integer", "description": "Domain mode: only keywords where the website ranks at this position or better, for example 10 for its page-1 keywords." }, "sortBy": { "title": "Sort by (ideas and domain modes)", "enum": [ "volume", "cpc", "difficulty", "traffic", "position" ], "type": "string", "description": "Order in which ideas and domain rows are fetched. Default: search volume for ideas, estimated traffic for domain mode. Easiest first sorts by keyword difficulty, lowest first. Traffic and position work in domain mode only." } } }, "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 } } } } } } } } } }