# Google Search Scraper (`codingfrontend/google-search-scraper`) Actor

A robust, high-performance utility designed for developer automation, data integration, and AI training. Features built-in captcha bypass, headful/headless browser execution, and proxy support to scrape Google data seamlessly, reliably, and at scale.

- **URL**: https://apify.com/codingfrontend/google-search-scraper.md
- **Developed by:** [Coding Frontned](https://apify.com/codingfrontend) (community)
- **Categories:** Developer tools, Automation, AI
- **Features:** Limited permissions
- **Stats:** 28 total users, 4 monthly users, 93.3% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.99 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Google Search Scraper

Fetch bounded, localized Google web-search HTML and publish source-backed organic results only. People Also Ask questions, related searches, featured text, and estimated totals are retained as page evidence in the `OUTPUT` and `OUTPUT_SUMMARY` records rather than mixed into the result dataset.

### Behavior

- Returns at most 100 unique organic results across at most 10 result pages.
- Preserves the original `query`, `maxItems`, localization, time-filter, `nfpr`, `filter`, timeout, retry, and proxy inputs, including the legacy `time_period`, `time_period_min`, and `time_period_max` aliases.
- Uses Apify's `GOOGLE_SERP` proxy group by default. Direct mode is useful for local QA, while standard/custom proxy settings remain accepted.
- Resolves Google's protected result redirects with bounded, redirect-only probes; destination pages are never scraped.
- Publishes normal rows atomically only after all requested pages are source-backed and valid. A challenge, consent page, oversized response, malformed source, or failed page produces no normal rows.
- Treats Google's explicit no-results page as a successful valid-empty run.
- Normal rows include source type, host, HTTP status, content type, response size, retry/proxy metadata, SHA-256 source hash, extraction method, and stable IDs. Runtime/debug fields are removed before publication.
- Optional failure rows contain exactly `url`, `error`, `errorCode`, and `scrapedAt`.

You can download the dataset in various formats such as JSON, HTML, CSV, or Excel.

### Input

| Field | Type | Default | Notes |
| --- | --- | --- | --- |
| `query` | string | required | 1–300 characters |
| `maxItems` | integer | `10` | 1–100 |
| `gl` | string | `us` | Two-letter country code |
| `hl` | string | `en` | Language such as `en` or `en-us` |
| `lr` | string | omitted | Result-language filter such as `lang_en` |
| `timePeriod` | string | `none` | `last_hour`, `last_day`, `last_week`, `last_month`, `last_year`, or `custom` |
| `timePeriodMin` / `timePeriodMax` | string | omitted | `MM/DD/YYYY`, required together for `custom` |
| `time_period`, `time_period_min`, `time_period_max` | aliases | omitted | Backward-compatible snake-case aliases |
| `nfpr` / `filter` | integer | omitted | Google values `0` or `1` |
| `requestTimeoutSecs` | integer | `45` | 5–120 seconds per page |
| `maxRequestRetries` | integer | `1` | 0–2 retries after the first request |
| `requestDelayMs` | integer | `0` | 0–5000 ms between successful pages |
| `maxResponseBytes` | integer | `6000000` | 1024–12000000 byte response cap |
| `includeDiagnostics` | boolean | `true` | Emit minimal diagnostics on failure |
| `proxySessionId` | string | omitted | Optional stable proxy session |
| `proxyConfiguration` | object | Google SERP proxy | Apify, custom, or direct settings |
| `fixtureJson` / `fixtureFile` | string | omitted | Local QA only; fixture files must be under `test/fixtures` or `.actor/fixtures` |

Example:

```json
{
  "query": "OpenAI API documentation",
  "maxItems": 15,
  "gl": "us",
  "hl": "en",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["GOOGLE_SERP"]
  }
}
```

### Dataset and run metadata

Each normal row is an `organic-result` with `recordId`, `position`, `title`, `url`, `domain`, `searchQuery`, `searchPage`, localization fields, `searchUrl`, `scrapedAt`, `fieldCoverage`, and `dataQuality`. Optional source-backed fields such as `displayedUrl`, `snippet`, `date`, `siteLinks`, `rating`, and `reviewCount` are omitted when unavailable. Provenance fields identify the exact HTML source and request attempt.

`OUTPUT` and its identical `OUTPUT_SUMMARY` alias report status, counts, page-level SERP feature evidence, proxy mode, redirect-resolution count, request attempts, failures, and elapsed time. A failed run is fail-closed: diagnostics may be present, but guessed or partial normal rows are not.

### Local verification

```bash
npm ci
npm run check
npm exec --yes --package=apify-cli -- apify validate-schema
npm exec --yes --package=apify-cli -- apify run --input-file qa-inputs/local-fixture.json --purge
npm run validate
```

The local fixture covers pagination, canonical URL deduplication, and SERP feature capture. `qa-inputs/cloud-validation.json` exercises bounded direct live access; Google may return a challenge, which is recorded truthfully as a diagnostic rather than bypassed.

# Changelog

This Actor's version history is a separate document: https://apify.com/codingfrontend/google-search-scraper/changelog.md

# Actor input Schema

## `query` (type: `string`):

Google web-search query, 1-300 characters.

## `maxItems` (type: `integer`):

Maximum unique organic rows across bounded result pages.

## `gl` (type: `string`):

Two-letter Google country code.

## `hl` (type: `string`):

Language code such as en or en-us.

## `lr` (type: `string`):

Optional result-language filter such as lang_en.

## `timePeriod` (type: `string`):

Optional Google time filter; custom requires both date fields.

## `time_period` (type: `string`):

Backward-compatible alias for timePeriod.

## `timePeriodMin` (type: `string`):

Required for custom time period, in MM/DD/YYYY.

## `time_period_min` (type: `string`):

Backward-compatible alias for timePeriodMin.

## `timePeriodMax` (type: `string`):

Required for custom time period, in MM/DD/YYYY.

## `time_period_max` (type: `string`):

Backward-compatible alias for timePeriodMax.

## `nfpr` (type: `integer`):

Optional: set to 1 to request no query autocorrection.

## `filter` (type: `integer`):

Optional: set to 0 to disable Google's similar-result filter.

## `requestTimeoutSecs` (type: `integer`):

Hard timeout per page in seconds.

## `maxRequestRetries` (type: `integer`):

Bounded retries per page.

## `requestDelayMs` (type: `integer`):

Delay between successful page requests.

## `maxResponseBytes` (type: `integer`):

Hard cap for each HTML response and fixture.

## `includeDiagnostics` (type: `boolean`):

On failure, emit minimal URL/error/errorCode/scrapedAt rows.

## `proxySessionId` (type: `string`):

Optional stable proxy session identifier.

## `proxyConfiguration` (type: `object`):

Google SERP is the validated default; standard/custom proxy and direct mode are accepted overrides.

## `fixtureJson` (type: `string`):

Optional local-only JSON containing Google Search HTML pages.

## `fixtureFile` (type: `string`):

Optional relative fixture path inside test/fixtures or .actor/fixtures.

## Actor input object example

```json
{
  "query": "OpenAI API documentation",
  "maxItems": 10,
  "gl": "us",
  "hl": "en",
  "timePeriod": "none",
  "requestTimeoutSecs": 45,
  "maxRequestRetries": 1,
  "requestDelayMs": 0,
  "maxResponseBytes": 6000000,
  "includeDiagnostics": true,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "GOOGLE_SERP"
    ]
  }
}
```

# Actor output Schema

## `organicResults` (type: `string`):

No description

## `runSummary` (type: `string`):

No description

## `outputSummary` (type: `string`):

No description

# 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 = {
    "query": "OpenAI API documentation",
    "maxItems": 10,
    "gl": "us",
    "hl": "en",
    "requestTimeoutSecs": 45,
    "maxRequestRetries": 1,
    "includeDiagnostics": true,
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "GOOGLE_SERP"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("codingfrontend/google-search-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 = {
    "query": "OpenAI API documentation",
    "maxItems": 10,
    "gl": "us",
    "hl": "en",
    "requestTimeoutSecs": 45,
    "maxRequestRetries": 1,
    "includeDiagnostics": True,
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["GOOGLE_SERP"],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("codingfrontend/google-search-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "query": "OpenAI API documentation",
  "maxItems": 10,
  "gl": "us",
  "hl": "en",
  "requestTimeoutSecs": 45,
  "maxRequestRetries": 1,
  "includeDiagnostics": true,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "GOOGLE_SERP"
    ]
  }
}' |
apify call codingfrontend/google-search-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,codingfrontend/google-search-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/Y0wW7ftci1BT3jTed/builds/HbvGhiEWG3gRYVZgP/openapi.json