{ "openapi": "3.0.1", "info": { "title": "Keyword Search Volume & Ideas — Google Ads Data API", "description": "Keyword research API: bulk Google search volume, CPC, competition and 24-month trends for up to 10,000 keywords, plus keyword ideas and seasonality. Bring your own DataForSEO account (BYOK): $0.50 per 1,000 keywords on top of your own DataForSEO usage.", "version": "1.0", "x-build-id": "NwFV3rmjY7u1v0BSd" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/tiger19935~keyword-search-volume-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-tiger19935-keyword-search-volume-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/tiger19935~keyword-search-volume-api/runs": { "post": { "operationId": "runs-sync-tiger19935-keyword-search-volume-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/tiger19935~keyword-search-volume-api/run-sync": { "post": { "operationId": "run-sync-tiger19935-keyword-search-volume-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", "required": [ "keywords" ], "properties": { "mode": { "title": "Mode", "enum": [ "volume", "ideas" ], "type": "string", "description": "'Volume' returns metrics for exactly the keywords you list (up to 10,000). 'Ideas' takes up to 200 seed keywords and returns the best related keywords with their metrics, sorted by search volume.", "default": "volume" }, "keywords": { "title": "Keywords", "minItems": 1, "maxItems": 10000, "type": "array", "description": "One keyword or phrase per row. Volume mode: up to 10,000 keywords. Ideas mode: up to 200 seed keywords. Each keyword may have up to 80 characters and 10 words, and no emoji or symbols; invalid and duplicate entries are skipped and listed in the run summary (OUTPUT). Case does not matter.", "items": { "type": "string" } }, "location": { "title": "Country", "enum": [ "2840", "2826", "2124", "2036", "2276", "2250", "2724", "2380", "2528", "2616", "2804", "2076", "2484", "2356", "2392", "2410", "2752", "2578", "2208", "2246", "2372", "2620", "2756", "2040", "2056", "2203", "2642", "2348", "2300", "2100", "2792", "2376", "2784", "2682", "2818", "2710", "2566", "2702", "2360", "2608", "2764", "2704", "2458", "2554", "2032", "2170", "2152", "2586" ], "type": "string", "description": "Country whose Google searches are counted (Google geo-target country code).", "default": "2840" }, "language": { "title": "Language", "enum": [ "en", "de", "fr", "es", "it", "pt", "nl", "pl", "uk", "ru", "tr", "ja", "ko", "sv", "da", "fi", "no", "cs", "ro", "hu", "el", "ar", "he", "hi", "id", "vi", "th" ], "type": "string", "description": "Language of the searches (language code, e.g. en, de, fr, uk).", "default": "en" }, "maxIdeas": { "title": "Max ideas (Ideas mode)", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Ideas mode only: the maximum number of keyword ideas in the whole run (highest search volume first). You pay only for ideas you receive.", "default": 200 }, "minSearchVolume": { "title": "Minimum monthly search volume", "minimum": 0, "maximum": 1000000000, "type": "integer", "description": "Skip keywords with a lower average monthly search volume (they are not saved and not charged). 0 keeps everything.", "default": 0 }, "includeNoData": { "title": "Keep keywords without data", "type": "boolean", "description": "Volume mode only: also save a row (hasData = false) for keywords Google has no volume for. These rows are free. Turn off to save only keywords with data.", "default": true }, "cacheDays": { "title": "Reuse cached data for (days)", "minimum": 0, "maximum": 30, "type": "integer", "description": "Keywords you fetched earlier are served from your personal cache (a key-value store in your account) when the data is younger than this - no new batch fee. 0 = always fetch fresh data. Maximum 30.", "default": 30 }, "dfsLogin": { "title": "Your DataForSEO login", "type": "string", "description": "Your DataForSEO API login (usually your account e-mail). Needed for real data (together with the API password); leave both empty to get 3 sample demo rows. Stored encrypted." }, "dfsPassword": { "title": "Your DataForSEO API password", "type": "string", "description": "Your DataForSEO API password (from the DataForSEO dashboard, not your account password). Needed for real data. Stored encrypted." } } }, "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 } } } } } } } } } }