# Keyword Research & SERP Data (`datascraperes/keyword-research-serp`) Actor Research keywords, search-result data, related terms, and keyword clusters from publicly accessible search intelligence pages. - **URL**: https://apify.com/datascraperes/keyword-research-serp.md - **Developed by:** [DataScraperES](https://apify.com/datascraperes) (community) - **Categories:** SEO tools, Automation, Developer tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing $1.00 / 1,000 keyword reports This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Keyword Research & SERP Data Turn a list of search terms into five export-ready tables: keyword summaries, organic SERP results, keyword ideas, topic clusters, and paid-SERP history. ### When to use this Actor Use it when you need to: - Validate a keyword before creating content or launching a campaign. - Find question, phrase-match, transactional, and competitor-related keyword ideas. - Review organic and paid search-result data for a market. - Build keyword clusters and content-topic plans. - Check the URL that ranks for a keyword on a particular domain. ### Quick start 1. Enter one or more terms in **Keywords**. 2. Select the **Market code** where you want to research them. 3. Pick the report sections you need, or keep the default complete report. 4. Click **Start**. 5. Open the **Output** tab and choose the table you need. Download it as CSV or Excel, or use its API URL. Start with a small run of one or two keywords to choose the sections that are useful for your workflow. ### Before you start You do not need an external account or to provide cookies or credentials. Choose the market first: keyword volume, ranking difficulty and results are market-specific. Use the same market code for all terms in one run so the exported tables are comparable. ### Input `keywords` is the only required field. Add up to 25 terms; duplicate and blank values are removed automatically. | Field | Default | What it does | |---|---:|---| | `keywords` | Required | Keywords to research, up to 25 unique terms. | | `countryCode` | `ES` | Two-letter market code, for example `ES`, `US`, or `UK`. Use `UK`, not `GB`. | | `sections` | Complete report | Data families to collect. See the section guide below. | | `relatedLimit` | `5` | Requested size of each related-keyword or cluster list. The upstream service can return fewer rows. | | `serpRows` | `30` | Requested number of organic SERP rows. | | `topDomain` | Empty | Domain for the optional `top_url` report, such as `example.com`. | | `delaySeconds` | `0` | Optional wait between upstream requests. The default is the fastest sequential mode. Increase only if a large run is rate-limited. | | `continueOnError` | `true` | Continue later keywords and write an error row if one term cannot be researched. | #### How to enter each field correctly - **Keywords:** write the actual seed query only. Do not use a URL, a whole sentence, or comma-separated values in one list item. Add separate items instead. - **Market code:** use `ES`, `US`, `UK`, or the two-letter code for the target market. `UK` is correct for the United Kingdom; `GB` is not. - **Domain to check its ranking page:** only needed with `top_url`. Enter `example.com`, not `https://example.com/blog/page`. - **Limits:** `relatedLimit` and `serpRows` are requested maximums. They do not guarantee that the market has that many available results. - **Delay:** keep `0` for the fastest mode. Retry only affected inputs with a delay of `1` to `3` if the upstream service limits a larger run. #### Report sections | Section | Includes | Choose it when you need | |---|---|---| | `serp` | Organic SERP and paid-SERP history | Ranking and advertising context. | | `stats` | Keyword metrics and available search features | Fast validation of a seed keyword. | | `suggestions` | General, keyword, and domain suggestions | More topic and query ideas. | | `related` | Phrase match, questions, transactional terms, also-ranks, and ad-overlap terms | Keyword expansion and intent research. | | `clusters` | Related keyword groups and cluster totals | Content hubs and topical planning. | | `top_url` | Top URL for the keyword on `topDomain` | Comparing a domain's ranking page. Requires `topDomain`. | For most SEO planning runs, select `stats`, `related`, and `serp`. Add `clusters` when planning topic hubs. Use `suggestions` for exploratory ideas that may not include metrics. Select `top_url` only for a domain-specific comparison. #### Ready-to-run examples **Fast keyword check** ```json { "keywords": ["seo", "abogados madrid"], "countryCode": "ES", "sections": ["stats", "suggestions"] } ```` **Complete keyword research** ```json { "keywords": ["email marketing software"], "countryCode": "US", "sections": ["serp", "stats", "suggestions", "related", "clusters"], "serpRows": 30, "relatedLimit": 5, "delaySeconds": 3 } ``` **Find a domain's ranking URL** ```json { "keywords": ["keyword research"], "countryCode": "UK", "sections": ["serp", "top_url"], "topDomain": "example.com" } ``` **Large-list retry after a rate limit** ```json { "keywords": ["seo auditoria", "seo local", "seo tecnico"], "countryCode": "ES", "sections": ["stats", "related"], "delaySeconds": 2, "continueOnError": true } ``` ### Results The Actor creates five dedicated datasets. Each is a clean table with one row per useful entity: | Dataset | One row means | Best for | |---|---|---| | Keyword summaries | A processed seed keyword | Prioritizing by volume, difficulty, competition, and result counts. | | Organic SERP results | One ranking URL | Competitor and ranking-page analysis. | | Keyword opportunities | One related keyword with metrics | Prioritized expansion and content planning. | | Keyword clusters | One topic-cluster node | Building topic hubs and content architecture. | | Paid SERP history | One historical ad observation | Reviewing advertisers and paid-search history. | #### How to use the tables 1. Open **Keyword opportunities** first. Filter `recommendation` to `High priority`, then sort `opportunityScore` from high to low. 2. Review `searchVolume`, `rankingDifficulty`, `totalMonthlyClicks`, `intent`, and `ideaType` before choosing a keyword. 3. Open **Organic SERP results** for the chosen seed to see the pages and domains currently competing. 4. Use **Keyword clusters** to group selected opportunities into topic hubs. These are top-level topics only, intentionally limited to avoid noisy internal tree data. 5. Use **Paid SERP history** only when paid-search context is relevant; historical ads do not represent current ads. #### Opportunity score and recommendation `opportunityScore` is a transparent prioritization aid, not a traffic forecast. It is calculated as: ```text search volume × (1 − ranking difficulty / 100) ``` `High priority` requires available search volume of at least 1,000 and ranking difficulty of 30 or lower. `Review` means the idea has some measurable demand but needs human judgment. `Low data` means the upstream response did not provide enough demand data for reliable automatic prioritization. The default **Keyword summaries** dataset contains one object per processed keyword: ```json { "keyword": "seo", "countryCode": "ES", "ok": true, "sectionsRequested": ["serp", "stats"], "liveSearchVolume": 39500, "rankingDifficulty": 17, "paidCompetitors": 82, "organicResultCount": 10, "keywordIdeaCount": 35, "clusterCount": 42, "paidHistoryCount": 12, "errorCode": null, "errorMessage": null } ``` `sectionsWithData` identifies which requested parts returned data. `ok: true` means at least one requested section returned usable data. A row with `ok: false` contains the reason in `errorCode` and `errorMessage`; it is not charged. `chargedEvents` in the `OUTPUT` record shows the actual number of confirmed paid events. The Output tab also provides an `OUTPUT` summary with input, processed, successful, failed, unprocessed, and charge-limit counts. ### Pay per event pricing and cost control This Actor uses Apify **Pay per event** pricing. The primary event is `keyword-analyzed` at **$0.001 per keyword report with usable data** — **$1 per 1,000 reports**. You only pay for a keyword when at least one requested section returns data. Fully failed keyword rows are free. Your maximum variable charge is simple to estimate: ```text unique keywords with usable data × $0.001 ``` There is no fixed start charge. Do not enable `apify-default-dataset-item`: the Actor writes free error rows. The Actor checks the spending limit before each keyword, confirms the charged event when the summary is stored, and stops safely if the remaining budget cannot cover another report. ### Runtime and limits - A lightweight `stats` run generally needs only a few requests per keyword. - The complete default report makes roughly 18 upstream requests per keyword. In local validation, the zero-delay mode completed a real full report in about 13 seconds; response time can vary by market and upstream load. - Requested SERP and list sizes are targets, not guarantees. The upstream service can return fewer rows or temporarily limit a request. - The 25-keyword limit protects against unexpectedly large runs. If a larger run encounters rate limiting, set `delaySeconds` to 1–3 and retry only the affected terms. ### FAQ **Why is a report partial?** Some data families can be temporarily unavailable while others succeed. Compare `sectionsRequested` with `sectionsWithData` in Keyword summaries to identify what was returned. **Why did the Actor stop before all keywords?** Check `stoppedByChargeLimit` in `OUTPUT`. Increase the run's spending limit or start a new run with the remaining keywords. **Why are there fewer rows than requested?** `relatedLimit` and `serpRows` request a maximum. Availability varies by keyword, market, and the upstream response. **What does an error row mean?** The keyword could not return usable data. Read `errorCode` and `errorMessage`, then retry only that keyword later. Error rows are not charged. **Which dataset should I export?** Export Keyword opportunities for content and keyword planning, Organic SERP results for competitor research, Keyword summaries for one-row-per-seed reporting, Keyword clusters for topical architecture, and Paid SERP history for advertising research. **Can I use the output in an automation?** Yes. Start with Keyword opportunities: filter `recommendation = High priority`, then sort by `opportunityScore`. Use Organic SERP for competitor workflows and Keyword summaries for seed-keyword prioritization. ### Important notes - This Actor uses publicly accessible search-intelligence pages. It does not request or store third-party accounts, cookies, or credentials. - The default mode is intentionally fast. For a larger workload, increase `delaySeconds` if the upstream service returns incomplete data or rate limits requests. - Review the current terms of the upstream service and ensure your intended use complies with them. # Actor input Schema ## `keywords` (type: `array`): Required. Add one seed keyword per item, exactly as people search for it. You may enter up to 25 unique terms; blanks and duplicates are removed. Example: seo, abogados madrid, email marketing software. ## `countryCode` (type: `string`): Required market for every keyword. Use a two-letter code: ES for Spain, US for United States, UK for United Kingdom (not GB). The same keyword can produce different volume, difficulty and SERP data in each market. ## `sections` (type: `array`): Choose one or more values: stats for volume/difficulty; related for scored keyword opportunities; serp for organic and paid results; suggestions for extra unscored query ideas; clusters for top topics; top\_url only when topDomain is filled. More sections return more datasets and can take longer. ## `relatedLimit` (type: `integer`): Maximum requested rows for each related-keyword and cluster source. Start with 5. Raise it only when you need a broader idea list; the upstream service may still return fewer items. ## `serpRows` (type: `integer`): Maximum organic ranking URLs to return per keyword when serp is selected. Use 10 for a quick competitor review or 30 for deeper analysis. The upstream service may return fewer rows. ## `topDomain` (type: `string`): Optional. Use only together with top\_url. Enter a bare domain without http://, https://, paths or spaces, for example example.com. The Actor returns the URL from that domain which ranks best for each seed keyword. Leave empty when you do not need this comparison. ## `delaySeconds` (type: `number`): Optional wait between upstream requests. Zero is the fastest tested sequential mode. If a large run returns rate-limit errors or incomplete data, retry affected keywords with 1–3 seconds. Higher values increase runtime. ## `continueOnError` (type: `boolean`): Recommended. When enabled, a failure for one keyword creates an uncharged error row and the Actor continues with the rest. Disable only when you need the run to stop at the first keyword failure. ## Actor input object example ```json { "keywords": [ "seo", "abogados madrid" ], "countryCode": "ES", "sections": [ "serp", "stats", "suggestions", "related", "clusters" ], "relatedLimit": 5, "serpRows": 30, "topDomain": "semrush.com", "delaySeconds": 0, "continueOnError": true } ``` # Actor output Schema ## `keywordIdeas` (type: `string`): Prioritized keyword opportunities with metrics, intent, score, and recommendation. ## `results` (type: `string`): One decision-ready summary per processed keyword. ## `organicSerp` (type: `string`): One row per organic result, ready to filter or export. ## `keywordClusters` (type: `string`): Flattened topic clusters with hierarchy, size, and score. ## `paidSerpHistory` (type: `string`): Historical paid results, one row per ad observation. ## `summary` (type: `string`): Summary of input, processed reports, failures, and charge-limit status. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "keywords": [ "seo" ] }; // Run the Actor and wait for it to finish const run = await client.actor("datascraperes/keyword-research-serp").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "keywords": ["seo"] } # Run the Actor and wait for it to finish run = client.actor("datascraperes/keyword-research-serp").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "keywords": [ "seo" ] }' | apify call datascraperes/keyword-research-serp --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=datascraperes/keyword-research-serp", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Keyword Research & SERP Data", "description": "Research keywords, search-result data, related terms, and keyword clusters from publicly accessible search intelligence pages.", "version": "0.1", "x-build-id": "WGkElwk9my0QsfFDz" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/datascraperes~keyword-research-serp/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-datascraperes-keyword-research-serp", "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/datascraperes~keyword-research-serp/runs": { "post": { "operationId": "runs-sync-datascraperes-keyword-research-serp", "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/datascraperes~keyword-research-serp/run-sync": { "post": { "operationId": "run-sync-datascraperes-keyword-research-serp", "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": { "keywords": { "title": "Keywords", "minItems": 1, "maxItems": 25, "type": "array", "description": "Required. Add one seed keyword per item, exactly as people search for it. You may enter up to 25 unique terms; blanks and duplicates are removed. Example: seo, abogados madrid, email marketing software.", "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "countryCode": { "title": "Market code", "pattern": "^[A-Za-z]{2}$", "type": "string", "description": "Required market for every keyword. Use a two-letter code: ES for Spain, US for United States, UK for United Kingdom (not GB). The same keyword can produce different volume, difficulty and SERP data in each market.", "default": "ES" }, "sections": { "title": "Report sections", "type": "array", "description": "Choose one or more values: stats for volume/difficulty; related for scored keyword opportunities; serp for organic and paid results; suggestions for extra unscored query ideas; clusters for top topics; top_url only when topDomain is filled. More sections return more datasets and can take longer.", "items": { "type": "string" }, "default": [ "serp", "stats", "suggestions", "related", "clusters" ] }, "relatedLimit": { "title": "Related-keyword limit", "minimum": 1, "maximum": 100, "type": "integer", "description": "Maximum requested rows for each related-keyword and cluster source. Start with 5. Raise it only when you need a broader idea list; the upstream service may still return fewer items.", "default": 5 }, "serpRows": { "title": "Organic SERP rows", "minimum": 1, "maximum": 100, "type": "integer", "description": "Maximum organic ranking URLs to return per keyword when serp is selected. Use 10 for a quick competitor review or 30 for deeper analysis. The upstream service may return fewer rows.", "default": 30 }, "topDomain": { "title": "Domain to check its ranking page", "type": "string", "description": "Optional. Use only together with top_url. Enter a bare domain without http://, https://, paths or spaces, for example example.com. The Actor returns the URL from that domain which ranks best for each seed keyword. Leave empty when you do not need this comparison." }, "delaySeconds": { "title": "Minimum delay between requests", "minimum": 0, "maximum": 30, "type": "number", "description": "Optional wait between upstream requests. Zero is the fastest tested sequential mode. If a large run returns rate-limit errors or incomplete data, retry affected keywords with 1–3 seconds. Higher values increase runtime.", "default": 0 }, "continueOnError": { "title": "Continue on keyword errors", "type": "boolean", "description": "Recommended. When enabled, a failure for one keyword creates an uncharged error row and the Actor continues with the rest. Disable only when you need the run to stop at the first keyword failure.", "default": 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 } } }, "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 } } } } } } } } } } ```