# Google SERP Scraper (`datascraperes/google-serp-scraper`) Actor

Scrape Google organic search results by query, country, language, and page range. Get clean SERP data including position, title, URL, and description, with pay-per-result pricing and no browser required.

- **URL**: https://apify.com/datascraperes/google-serp-scraper.md
- **Developed by:** [DataScraperES](https://apify.com/datascraperes) (community)
- **Categories:** SEO tools, Lead generation, AI
- **Stats:** 2 total users, 2 monthly users, 94.4% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$0.60 / 1,000 serp results

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 web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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

## Google SERP Scraper

Extract structured Google organic search results for one or more queries, countries, languages, and page ranges.

The Actor returns one dataset item per organic result with its query, page, position, title, URL, and description.

### Use cases

- SEO rank tracking by query and market.
- Competitor and search-result analysis.
- Content, topic, and lead research.
- Monitoring organic result changes.
- Building structured SERP datasets for downstream workflows.

### Pricing

This Actor uses pay-per-event pricing.

| Event | What is charged | Price |
|---|---|---:|
| `serp-result` | One organic Google result published to the dataset | `$0.60 / 1,000 results` |

Equivalent price: `$0.0006` per organic result. Failed pages are not charged as `serp-result` events.

### Input

| Field | Type | Required | Default | Description |
|---|---|---:|---|---|
| `queries` | `string[]` | Yes | none | Search queries, one per line. Maximum: 10,000. |
| `startPage` | `integer` | No | `1` | First Google results page. |
| `endPage` | `integer` | No | `1` | Last page, from 1 to 10 and not lower than `startPage`. |
| `language` | `string` | No | `es` | Preferred language for the search results. |
| `country` | `string` | No | `es` | Target country used to localize the search results. |

#### Example input

```json
{
  "queries": ["best web hosting 2026", "seo tools for beginners"],
  "startPage": 1,
  "endPage": 2,
  "language": "en",
  "country": "us"
}
```

### Output

Each organic result is stored as a separate dataset item:

```json
{
  "query": "best web hosting 2026",
  "page": 1,
  "position": 1,
  "title": "Best Web Hosting 2026 - Full Comparison",
  "url": "https://example.com/best-web-hosting/",
  "description": "Snippet text shown in Google results."
}
```

### Run summary

The default Key-Value Store contains a `SUMMARY` record with the final run status, requested, successful, failed, and remaining pages, total results, selected country and language, and whether the spending limit stopped the run. The Actor output object links directly to both the dataset and this summary.

### Capacity and run limits

- A run accepts up to **10,000 queries** and pages 1–10.
- The selected query/page combinations are capped at **10,000 Google result pages**. This supports, for example, 10,000 queries on page 1, 5,000 queries on pages 1–2, or 1,000 queries on pages 1–10.
- With up to 10 organic results per page, the maximum paid output is **100,000 organic results**.
- The Actor checks the Apify spending limit before each paid page and stops when no further paid result can be delivered.

### Reliability

- Retries rate limits, blocked responses, timeouts, malformed responses, and empty parses.
- Runs a slower recovery pass for pages that fail initially.
- Persists completed and partially published pages across migrations or restarts.
- Checks the run spending limit before starting paid SERP work.
- Stops cleanly when no more paid results can be published.

### Notes

- The selected `country` localizes the search market; it is not a strict filter, so some international results can still appear.
- Ads, shopping boxes, maps, local packs, and knowledge panels are not included in organic output.
- Google markup and results can change, so positions and snippets may differ between runs.
- Some results may not contain a description.
- Deep pages may contain fewer than 10 results when Google has exhausted the available result set.
- Use output responsibly and comply with applicable laws, regulations, and website terms.

# Actor input Schema

## `queries` (type: `array`):

One or more search queries to scrape from Google.

## `startPage` (type: `integer`):

First Google results page to scrape (1 = positions 1–10).

## `endPage` (type: `integer`):

Last Google results page to scrape. E.g. startPage=1, endPage=3 scrapes pages 1, 2 and 3 (positions 1–30).

## `language` (type: `string`):

Language code for the search (select a language from the list).

## `country` (type: `string`):

Target country used to localize the search results (select a country from the list).

## `debug` (type: `boolean`):

Adds detailed retry and response-classification messages to the run log.

## Actor input object example

```json
{
  "queries": [
    "apify web scraping"
  ],
  "startPage": 1,
  "endPage": 1,
  "language": "es",
  "country": "es",
  "debug": false
}
```

# Actor output Schema

## `results` (type: `string`):

Organic Google SERP results.

## `summary` (type: `string`):

Final status, requested, successful, failed, and remaining pages, result count, selected market, and spending-limit state.

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "queries": [
        "apify web scraping"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("datascraperes/google-serp-scraper").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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "queries": ["apify web scraping"] }

# Run the Actor and wait for it to finish
run = client.actor("datascraperes/google-serp-scraper").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 '{
  "queries": [
    "apify web scraping"
  ]
}' |
apify call datascraperes/google-serp-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=datascraperes/google-serp-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/hrhVFW4C2RI1ENViU/builds/J4A1b3mmxYTf2qKd3/openapi.json