{ "openapi": "3.0.1", "info": { "title": "Keyword Suggestions API — Google, Bing & Amazon", "description": "Keyword research as data. Every autocomplete suggestion for your seed keywords from Google, YouTube, Bing, Amazon, eBay and DuckDuckGo, expanded alphabet-soup style with question, preposition and comparison modifiers. One row per keyword, with relevance and repeat counts. No API key, no login.", "version": "0.1", "x-build-id": "c0ShdSXPzNVFagRgw" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/insight.solutions~keyword-suggestions-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-insight.solutions-keyword-suggestions-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/insight.solutions~keyword-suggestions-api/runs": { "post": { "operationId": "runs-sync-insight.solutions-keyword-suggestions-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/insight.solutions~keyword-suggestions-api/run-sync": { "post": { "operationId": "run-sync-insight.solutions-keyword-suggestions-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": "Seed keywords", "type": "array", "description": "One seed per line. Every engine you pick is asked what it would autocomplete for each seed, and every suggestion comes back as a row. Seeds are compared case- and space-insensitively, so `Best CRM` and `best crm` are one seed; the `input` column still shows what you typed. Up to **200 seeds per run**, each under 200 characters — an autocomplete endpoint answers prefixes, not sentences.", "items": { "type": "string" } }, "sources": { "title": "Sources", "type": "array", "description": "Which autocomplete endpoints to ask — each one is a separate request per query, so three sources cost three times one. Google gives the most (15 per query, with a relevance score), Bing the longest lists (~25); YouTube is video-search intent, Amazon and eBay are buying intent, DuckDuckGo is a privacy-engine cross-check. The default three are a good start; add `amazon` or `ebay` for product research. DuckDuckGo needs residential proxy and Amazon is US-only.", "items": { "type": "string", "enum": [ "google", "youtube", "bing", "amazon", "ebay", "duckduckgo" ], "enumTitles": [ "Google — 15 per query, with relevance scores", "YouTube — video search intent", "Bing — the longest lists, up to ~25", "Amazon — buying intent, US marketplace only", "eBay — buying intent, with matching categories", "DuckDuckGo — needs residential proxy" ] }, "default": [ "google", "youtube", "bing" ] }, "language": { "title": "Language", "type": "string", "description": "Two-letter ISO 639-1 code. Sent to Google and YouTube as `hl`, and combined with the country into Bing's market (`en` + `us` → `en-US`). Amazon and eBay take their language from the marketplace, and DuckDuckGo's autocomplete takes no locale at all.", "default": "en" }, "country": { "title": "Country", "type": "string", "description": "Two-letter ISO 3166 code, lower case. Sent to Google and YouTube as `gl`, upper-cased into Bing's market, and mapped to eBay's numeric site ID — `us` 0, `ca` 2, `gb` 3, `au` 15, `fr` 71, `de` 77, `it` 101, `es` 186; any other country falls back to the US site. **Amazon ignores it**: only the US marketplace returns suggestions.", "default": "us" }, "maxSuggestionsPerQuery": { "title": "Suggestions per query", "minimum": 1, "maximum": 50, "type": "integer", "description": "How many suggestions to keep from each query, in the order the engine ranked them. The engines' own ceilings are lower than you might expect: Google's chrome client sends 15, Bing about 25, and YouTube, Amazon, eBay and DuckDuckGo about 10 each — so a number above 25 only changes what happens if one of them starts sending more.", "default": 20 }, "expansions": { "title": "Expansions", "type": "array", "description": "How far past the bare seed to go. An autocomplete endpoint only answers the prefix it is given, so the long tail is reached by asking many prefixes: `alphabet` adds 26 queries (`seed a` … `seed z`), `numbers` 10, `questions` 26 (appended and prepended), `prepositions` 12, `comparisons` 11 — each per seed, per source. Leave it empty for a quick look; switch on `alphabet` and `questions` when you want the tail. All five is 86 queries per seed per source.", "items": { "type": "string", "enum": [ "alphabet", "numbers", "questions", "prepositions", "comparisons" ], "enumTitles": [ "Alphabet — seed a … seed z (+26 queries)", "Numbers — seed 0 … seed 9 (+10 queries)", "Questions — how/what/why, appended and prepended (+26 queries)", "Prepositions — for/with/without/near… (+12 queries)", "Comparisons — vs/alternatives/review/best… (+11 queries)" ] }, "default": [] }, "dedupe": { "title": "One row per unique suggestion", "type": "boolean", "description": "On (the default): one row per unique suggestion per seed **and** source, with `alsoFrom` counting how many *other* queries returned the same suggestion — a useful strength signal, because a keyword that turns up under fifteen different prefixes is one the engine really wants to suggest. Off: every query keeps its own rows, duplicates and all, and `alsoFrom` is null. Comparison is case- and space-insensitive; the first query that produced a suggestion keeps the row.", "default": true }, "amazonDepartment": { "title": "Amazon department", "type": "string", "description": "Amazon's search alias — the department its search box would be scoped to. `aps`, the default, is all departments; `electronics`, `books`, `fashion`, `kitchen`, `sporting`, `toys-and-games`, `videogames`, `office-products`, `pets` and `lawngarden` are the common ones. Only matters when `amazon` is in `sources`. Amazon is US-only here — the other marketplaces return nothing — so rows are marked `marketplace: amazon.com`.", "default": "aps" }, "maxConcurrency": { "title": "Jobs in parallel", "minimum": 1, "maximum": 10, "type": "integer", "description": "How many (keyword, source) pairs are worked on at once. Each parallel worker keeps its own proxy session, so one engine refusing an exit IP does not burn the address the others are using. Requests to one engine from one worker are spaced 150–300 ms apart whatever this is set to.", "default": 4 }, "maxRunSecs": { "title": "Maximum run time (seconds)", "minimum": 30, "maximum": 3600, "type": "integer", "description": "Wall-clock budget for the whole run. When it is reached the Actor stops asking, keeps and bills for every suggestion it already wrote, and files a free diagnostic row for each keyword and source it never finished. Nothing is charged for work that did not happen. A full five-expansion run over many seeds needs a bigger number than the default: 86 queries per seed per source at roughly four a second is the arithmetic.", "default": 240 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Which proxy the requests go out through. Google, YouTube, Bing, Amazon and eBay all answer Apify datacenter addresses, so that is the default — cheaper than residential, and the proxy cost is already inside the per-keyword price. **DuckDuckGo only answers residential exits**: if `duckduckgo` is in your sources set the proxy groups to `RESIDENTIAL`, otherwise you get one free `blocked` row per keyword saying so. Sessions rotate when an exit IP is refused.", "default": { "useApifyProxy": true } } } }, "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 } } } } } } } } } }