{ "openapi": "3.0.1", "info": { "title": "Keyword Search Volume & CPC Checker: Google Keyword Planner", "description": "Keyword search volume checker for a keyword list: Google search volume, CPC, competition, bids, keyword difficulty, search intent and up to 104 months of history per keyword, any country or worldwide. Keyword Planner view, keyword ideas, ranked keywords, AI and Bing search volume. Pay per keyword.", "version": "0.1", "x-build-id": "ikCoFruOLgxPXNll5" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/hyperbach~keyword-search-volume/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-hyperbach-keyword-search-volume", "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/hyperbach~keyword-search-volume/runs": { "post": { "operationId": "runs-sync-hyperbach-keyword-search-volume", "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/hyperbach~keyword-search-volume/run-sync": { "post": { "operationId": "run-sync-hyperbach-keyword-search-volume", "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", "type": "array", "description": "The keyword list, one keyword per entry (`event ticketing`). Up to 10,000 a run; the run reads them in batches of 700 (Labs view) or 1,000 (Google Ads view). Also accepted: `keywordsText` below, merged with this list.", "items": { "type": "string", "maxLength": 200 }, "default": [] }, "keywordsText": { "title": "Keywords as text (paste a list)", "maxLength": 1000000, "type": "string", "description": "Paste a whole list instead: one keyword per line, or comma-separated. Merged with `keywords`; duplicates are folded and charged once.", "default": "" }, "locations": { "title": "Locations (countries, worldwide, or Google Ads location codes)", "type": "array", "description": "One row per keyword per location. A country as its ISO code (`US`, `DE`, `GB`) or name (`Germany`), `worldwide` (Google's figure for all countries), or a numeric Google Ads location code for a city, region or postal code (`1023191` = New York, `1006886` = London). Empty = United States. Up to 50 locations a run; a location the Actor does not know is a free `unsupported_location` row, never a silent fallback.", "items": { "type": "string", "maxLength": 80 }, "default": [] }, "language": { "title": "Language", "pattern": "^[A-Za-z][A-Za-z _()-]{0,30}$", "type": "string", "description": "A Google Ads language as its code (`en`, `de`, `es`, `pt`, `ja`, `zh_TW` or `zh-TW`) or name (`German`, `Chinese (Traditional)`). One language a run; the 46 Google Ads languages are accepted. The Labs view serves each country in its own languages (the United States in `en` and `es`, Germany in `de`): a pair the Labs view lacks is read on the Google Ads view, and the row's `source_view` says so.", "default": "en" }, "view": { "title": "Which figure", "enum": [ "labs", "google_ads", "both" ], "type": "string", "description": "`labs` (the default): a keyword database built on Google Ads data, where every keyword is read on its own (its figure does not depend on the rest of the list): volume, CPC, competition, bids, up to 104 months of history, keyword difficulty, intent, SERP features and backlink averages; 92 countries. `google_ads`: the Google Ads Keyword Planner view as Google serves it, where close variants in one batch take one group figure (`ads_variants_merged` says so), 12 months (47 with a date window), search partners, worldwide, cities and postal codes. `both`: the Labs row with the Google Ads figures in the `ads_*` columns; the `ads_view` add-on is charged on each row that carries them. Each live Labs task (up to 700 keywords) carries one `labs_task` fee and each Google Ads task (up to 1,000) one `ads_task` fee, on its first charged row. Close variants Google counts as one search (plurals, word order, misspellings) share one figure on both views.", "default": "labs" }, "searchPartners": { "title": "Google Search + search partners", "type": "boolean", "description": "Google Search and its search partners together (the Keyword Planner's network setting) instead of Google Search alone. A Google Ads setting: with it the keyword rows are read on the `google_ads` view (`event ticketing`: 880 with partners, 720 without, in our test).", "default": false }, "dateFrom": { "title": "History from (YYYY-MM)", "pattern": "^(\\d{4}-\\d{2}(-\\d{2})?)?$", "type": "string", "description": "The first month of the monthly series, `YYYY-MM` (or a date). On the Google Ads view the source serves up to 4 years back (47 months); on the Labs view the series (up to 104 months) is trimmed to the window. Empty = everything the view holds.", "default": "" }, "dateTo": { "title": "History to (YYYY-MM)", "pattern": "^(\\d{4}-\\d{2}(-\\d{2})?)?$", "type": "string", "description": "The last month of the monthly series, `YYYY-MM` (or a date). Empty = the source's latest month (`data_month` on every row).", "default": "" }, "includeSerpInfo": { "title": "SERP features and result count (free)", "type": "boolean", "description": "On the Labs view: the SERP features Google shows for the keyword (`serp_item_types`, `has_ai_overview`), the result count and a check URL. Free. Off = the columns stay null.", "default": true }, "includeClickstream": { "title": "Add clickstream volume (Labs; doubles the source task)", "type": "boolean", "description": "Clickstream-based search volume and the clickstream-normalized volume next to Google's, from the `labs` keyword database (`clickstream_search_volume`, `clickstream_normalized_volume`, `clickstream_monthly_searches`). The `clickstream` add-on is charged on each keyword row that carries a figure.", "default": false }, "includeAiVolume": { "title": "Add AI-assistant search volume", "type": "boolean", "description": "How often the keyword is asked of AI assistants (ChatGPT and the like), with 12 months of history (`ai_search_volume`, `ai_monthly_searches`; 92 countries). The `ai_volume` add-on is charged on each keyword row that carries a figure, and each AI task (up to 700 keywords) one `labs_task` fee.", "default": false }, "includeBingVolume": { "title": "Add Bing search volume", "type": "boolean", "description": "Bing's search volume, CPC, competition and 13 months next to Google's (`bing_*` columns); served for US, GB, CA, AU, DE and FR in English, French and German. The `bing_volume` add-on is charged on each keyword row that carries a figure, and each Bing task (up to 1,000 keywords) one `ads_task` fee.", "default": false }, "includeAdultKeywords": { "title": "Include adult keywords (Google Ads view)", "type": "boolean", "description": "Ask Google Ads to return figures for adult keywords too (its default hides them). Google may still return no data for some.", "default": false }, "minSearchVolume": { "title": "Minimum monthly searches", "minimum": 0, "maximum": 100000000, "type": "integer", "description": "Keep only keywords with at least this many monthly searches. Ideas and ranked keywords are filtered at the source before anything is charged; one of your own keywords under the floor is a free `below_min_volume` row without figures. 0 = no floor.", "default": 0 }, "seeds": { "title": "Seed keywords for keyword ideas", "type": "array", "description": "Seeds for keyword ideas (`event ticketing`): up to `ideasPerSeed` ideas per seed and location, each a `keyword_idea` row with volume, CPC, competition, difficulty, intent and the seed. Up to 100 seeds a run.", "items": { "type": "string", "maxLength": 200 }, "default": [] }, "ideasPerSeed": { "title": "Ideas per seed", "minimum": 1, "maximum": 1000, "type": "integer", "description": "How many ideas to read per seed and location (1 to 1,000; the source holds up to a million for a broad seed). Applies when `seeds` is given.", "default": 100 }, "ideasSource": { "title": "Kind of ideas", "enum": [ "ideas", "suggestions", "related" ], "type": "string", "description": "Which Labs list the ideas come from: `ideas` (the seed's topic, ordered by relevance), `suggestions` (long-tail phrases containing the seed, by volume) or `related` (Google's related searches, two levels deep).", "default": "ideas" }, "domains": { "title": "Domains for ranked keywords", "type": "array", "description": "Domains whose organic ranking keywords you want (`eventbrite.com`, a URL is read as its domain): up to `keywordsPerDomain` keywords per domain and location, the highest estimated traffic first, each a `ranked_keyword` row with the position, the ranking URL and title, the estimated traffic and the keyword's figures. Up to 100 domains a run.", "items": { "type": "string", "maxLength": 253 }, "default": [] }, "keywordsPerDomain": { "title": "Ranked keywords per domain", "minimum": 1, "maximum": 1000, "type": "integer", "description": "How many ranked keywords to read per domain and location (1 to 1,000; eventbrite.com ranks for 1.4 million). Applies when `domains` is given.", "default": 100 }, "onlyChanges": { "title": "Only keywords whose figures moved (for a schedule)", "type": "boolean", "description": "For a saved task on a schedule: deliver a keyword row only when it is new to this memory or its data month or volume moved since it was last delivered to you; the unchanged ones are counted in the status message and not delivered. The memory lives with the Actor per Apify account and `stateStoreName`. The source updates once a month, so a monthly schedule is the natural one.", "default": false }, "stateStoreName": { "title": "Memory name", "pattern": "^[a-zA-Z0-9_-]{0,60}$", "type": "string", "description": "The name of the memory this run reads and writes (letters, digits, `-`, `_`). The same name across runs tracks the same keyword set; different tasks can keep different names. Empty = one default memory per account. The memory also makes sure a keyword you were already delivered in the same data month is not charged again (`billing_note` says when).", "default": "" }, "maxItems": { "title": "Max rows", "minimum": 0, "maximum": 1000000, "type": "integer", "description": "Stop after this many charged rows (keyword rows with figures, idea rows, ranked keyword rows; the free status rows do not count). 0 = no cap.", "default": 0 } } }, "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 } } } } } } } } } }