{ "openapi": "3.0.1", "info": { "title": "Keyword Search Volume, CPC & Difficulty — Google + Bing Bulk", "description": "Keyword search volume, CPC, competition, difficulty and search intent from Google Ads and Bing, with up to ~7 years of monthly history and a trend flag. One flat fee covers up to 1000 keywords per run. Expand seeds into keyword ideas or pull a competitor's ranked keywords. 111 countries.", "version": "0.0", "x-build-id": "xejvaOym3hiIKX44j" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/memo23~keyword-metrics/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-memo23-keyword-metrics", "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/memo23~keyword-metrics/runs": { "post": { "operationId": "runs-sync-memo23-keyword-metrics", "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/memo23~keyword-metrics/run-sync": { "post": { "operationId": "run-sync-memo23-keyword-metrics", "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 to do", "enum": [ "metrics", "ideas", "competitors" ], "type": "string", "description": "**Metrics** measures the keywords you supply — up to 1000 in one batch. **Ideas** takes up to 20 seeds and returns the related keywords Google associates with them. **Competitors** takes a domain instead of keywords and returns every keyword it ranks for in Google organic, with position, estimated traffic and what that traffic would cost to buy.", "default": "metrics" }, "domain": { "title": "Domain to analyse", "type": "string", "description": "The site whose Google organic rankings you want, as a bare host — `ahrefs.com`, not `https://ahrefs.com/blog`. A scheme, path or leading `www.` is stripped automatically. Required in Competitors mode and ignored in the others." }, "maxDomainKeywords": { "title": "Maximum ranked keywords", "minimum": 1, "maximum": 3000, "type": "integer", "description": "How many of the domain's ranked keywords to return, highest estimated traffic first. **Unlike every other limit in this actor, this one changes what you pay** — ranked keywords are billed per row, not per batch. Big sites rank for tens of thousands of terms; the top few hundred by traffic value are usually the interesting ones. Hard ceiling 3000 — beyond that a flat fee stops covering the per-row cost.", "default": 1000 }, "keywords": { "title": "Keywords", "type": "array", "description": "**Required in Metrics and Ideas modes** (Competitors mode uses `domain` instead and ignores this). In Metrics: up to 1000 keywords per run. In Ideas: up to 20 seeds. Billing is per batch, not per keyword — a run of 1000 keywords costs exactly the same as a run of 1. Anything past the limit is trimmed with a note in the log.", "items": { "type": "string" } }, "country": { "title": "Country", "enum": [ "us", "gb", "ca", "au", "ie", "nz", "za", "de", "fr", "es", "it", "nl", "be", "at", "ch", "pt", "se", "no", "dk", "fi", "is", "lu", "mt", "cy", "pl", "cz", "sk", "hu", "ro", "bg", "gr", "hr", "si", "rs", "ba", "mk", "al", "me", "lt", "lv", "ee", "ua", "md", "tr", "br", "mx", "ar", "cl", "co", "pe", "ec", "uy", "py", "bo", "cr", "pa", "gt", "do", "hn", "sv", "jm", "tt", "pr", "jp", "kr", "in", "sg", "hk", "tw", "id", "my", "ph", "th", "vn", "pk", "bd", "lk", "np", "kh", "la", "bn", "mn", "kz", "uz", "az", "ge", "am", "ae", "sa", "il", "qa", "kw", "bh", "om", "jo", "lb", "eg", "ma", "dz", "tn", "ng", "ke", "gh", "tz", "ug", "zm", "zw", "sn", "ci", "cm", "et" ], "type": "string", "description": "Country to measure search demand in. Unrecognised codes fall back to United States with a note in the log.", "default": "us" }, "location": { "title": "City or region", "type": "string", "description": "Optional. A city, state or region inside the country above, written the way Google Ads names it: \"Austin, Texas\" or \"Austin,Texas,United States\". A numeric Google Ads location code also works. Leave empty to measure the whole country. A city run uses Google Ads volume for that place. Bing, keyword difficulty, search intent and the long history series stay country-level and are not charged for a city." }, "language": { "title": "Language", "enum": [ "", "ar", "bg", "bn", "ca", "cs", "da", "de", "el", "en", "es", "et", "fa", "fi", "fr", "hi", "hr", "hu", "id", "is", "it", "iw", "ja", "ko", "lt", "lv", "ms", "nl", "no", "pl", "pt", "ro", "ru", "sk", "sl", "sr", "sv", "ta", "te", "th", "tl", "tr", "uk", "ur", "vi", "zh_CN", "zh_TW" ], "type": "string", "description": "Language of the searchers. Left on Auto, it follows the country — Germany queries German, Japan queries Japanese — which is almost always what you want. These are exactly the 46 languages Google Ads accepts; note its quirks: Hebrew is `iw`, Norwegian is `no`, and Chinese is regional (`zh_CN` / `zh_TW`). Microsoft/Bing supports English, French and German only — any other language skips the Bing half without charging.", "default": "" }, "includeGoogle": { "title": "Google Ads metrics", "type": "boolean", "description": "Search volume, CPC, competition level and index, top-of-page bid range, keyword difficulty, search intent, and up to ~93 months of monthly history from Google.", "default": true }, "includeBing": { "title": "Microsoft / Bing Ads metrics", "type": "boolean", "description": "The same metrics from Microsoft Ads, on the same rows, so you can compare the two networks directly. **Microsoft sells keyword data in six countries only — US, UK, Canada, Australia, Germany and France — and in English, French and German.** Anywhere else the row still arrives, with a `bing_status` of `unsupported_location` or `unsupported_language`, and the Bing batch is not charged. Ignored in ideas mode.", "default": true }, "includeAiVolume": { "title": "AI search volume", "type": "boolean", "description": "Also return how often each keyword is asked in AI assistants, with 12 months of that history. One flat fee for the whole list. Metrics mode only, charged after the data comes back. Ideas and competitors runs ignore this and are not charged for it.", "default": false }, "maxIdeas": { "title": "Maximum keyword ideas", "minimum": 1, "maximum": 20000, "type": "integer", "description": "Stop after this many discovered keywords. One expansion can return up to 20,000; the fee is identical either way, so raise this freely if you want the full set.", "default": 1000 }, "minVolume": { "title": "Minimum search volume", "minimum": 0, "type": "integer", "description": "Drop rows whose monthly search volume is below this on both engines. Applied after the lookup — useful for cutting the long tail out of an Ideas run.", "default": 0 }, "sortBy": { "title": "Sort results by", "enum": [ "relevance", "search_volume", "competition_index", "cpc", "low_top_of_page_bid", "high_top_of_page_bid" ], "type": "string", "description": "How the upstream ranks results before any trim. Matters most in Ideas mode, where the result set is far bigger than your maximum and this decides which keywords survive.", "default": "relevance" }, "searchPartners": { "title": "Include search-partner networks", "type": "boolean", "description": "Count each engine's partner network in the volumes, not just the engine's own results. Raises volumes; off by default, matching both Keyword Planners.", "default": false }, "includeAdultKeywords": { "title": "Include adult keywords", "type": "boolean", "description": "Let adult-content keywords through. Google filters them out by default. Google-side only.", "default": false }, "dateFrom": { "title": "History from", "type": "string", "description": "Start of the history window as `yyyy-mm-dd`. Setting either date switches the run to the Ads endpoint, which caps history at 12 months and reaches back four years. Leave both empty for the default ~93-month series." }, "dateTo": { "title": "History to", "type": "string", "description": "End of the history window as `yyyy-mm-dd`. Leave empty to run to the latest available month. Setting either date caps history at 12 months — see 'History from'." }, "bypassRunCache": { "title": "Bypass the cache", "type": "boolean", "description": "Force a live upstream lookup instead of reusing a cached result. Charges the full batch fees. Leave off unless you are deliberately re-testing.", "default": false } } }, "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 } } } } } } } } } }