# Google Maps Scraper $3/1k 🚀 (`autoharvestor/google-maps-scraper`) Actor

Automate Google Maps data extraction with this Apify Actor. Collect structured business listings 🚀 $3/1k —names, contacts, ratings, reviews, opening hours, and GPS coordinates—perfect for lead generation, local SEO audits, and competitor analysis.

- **URL**: https://apify.com/autoharvestor/google-maps-scraper.md
- **Developed by:** [Dipendra KC](https://apify.com/autoharvestor) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 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

## Production-Ready Google Maps Scraper (Apify Actor Parity)

A high-throughput, production-ready Google Maps business data scraper built in TypeScript with [Crawlee](https://crawlee.dev/) and [Playwright](https://playwright.dev/).

Replicates and enhances the core functionality of Apify's `compass/crawler-google-places` actor:

- **Bypasses the ~120-result cap** using automated geospatial grid tiling and adaptive 4-way recursive subdivision.
- **Extracts rich structured place data directly from Google Maps** (IDs, categories, opening hours, review distribution, amenities, images, reviews, phone number, and official website URL as listed on Maps).
- **Pure Google Maps Extraction (No External Crawling)**: This version extracts data exclusively from Google Maps. It does **not** visit external business websites to extract email addresses or social media profiles. The `website` field is included only when provided directly on the Google Maps listing.
- **Multiple deployment modes**: CLI tool, scheduled cron daemon, containerized worker, or headless Fastify REST API.
- **Anti-blocking & resilience**: Proxy rotation, consent interstitial bypass, captcha detection (`sorry.google.com`), and defensive DOM selectors.
- **Pluggable storage**: Streamed JSON, flattened CSV, NDJSON, and SQLite.

***

### Table of Contents

- [Core Crawl Strategy](#core-crawl-strategy)
- [System Architecture](#system-architecture)
- [Input Configuration Reference](#input-configuration-reference)
- [Output Schema](#output-schema)
- [Installation & Quick Start](#installation--quick-start)
- [CLI Commands](#cli-commands)
- [HTTP API Reference](#http-api-reference)
- [Storage Adapters](#storage-adapters)
- [Anti-Blocking & Proxy Management](#anti-blocking--proxy-management)
- [Docker Deployment](#docker-deployment)
- [Testing](#testing)
- [Legal & Compliance Notice](#legal--compliance-notice)

***

### Core Crawl Strategy

Google Maps caps any single search view at approximately 120 results. To achieve exhaustive regional coverage:

```
[Location String] ──▶ [OSM Nominatim] ──▶ [Bounding Box]
                                                │
                                                ▼
                                    [Geospatial Grid Tiler]
                                                │
                       ┌────────────────────────┴────────────────────────┐
                       ▼                                                 ▼
               [Tile 1: Zoom 14]                                 [Tile 2: Zoom 14]
                       │                                                 │
                       ▼                                                 ▼
             [Scroll Results Feed]                             [Scroll Results Feed]
                       │                                                 │
          ┌────────────┴────────────┐                                    │
    Hit ~120 Cap?             Under Cap?                                 │
          │                         │                                    │
          ▼                         ▼                                    ▼
 [Subdivide into 4x]        [Enqueue Places]                   [Enqueue Places]
  (Zoom 15 Quadrants)       (Global Dedup ID)                 (Global Dedup ID)
```

1. **Geocoding:** Resolves place names (e.g. `"Austin, TX"`) to geographical bounding boxes via OpenStreetMap's Nominatim API.
2. **Spatial Tiling:** Subdivides the bounding box into a grid of overlapping coordinate tiles based on the target zoom level.
3. **Scroll-to-load:** Programmatically scrolls each search feed (`div[role="feed"]`) until reaching the "You've reached the end of the list" marker or hitting `maxCrawledPlacesPerSearch`.
4. **Global ID Deduplication:** Extracts place stubs and enqueues detail targets into Crawlee's `RequestQueue` with unique keys based on Google internal IDs (`!1s0x...`, CID, or Place ID).
5. **Adaptive Recursive Subdivision:** When a tile yields >= 115 results, it automatically branches into 4 smaller sub-quadrants with increased zoom level (up to `maxTileDepth`), ensuring high-density areas are fully extracted.

***

### Input Configuration Reference

Configurable via a JSON file, environment variables, or CLI arguments:

| Field | Type | Default | Description |
|---|---|---|---|
| `category` | `string` | `undefined` | Primary business category or keyword (e.g. `"Roofing contractor"`, `"Dentist"`) |
| `location` | `string` | `undefined` | City, metro, or address (e.g. `"Austin, TX"`, `"London, UK"`) |
| `searchTerms` | `string[]` | `[]` | Search queries or multiple keywords (e.g. `["roofing contractors in Austin"]`) |
| `locationQuery` | `string` | `undefined` | Free-text location alias |
| `startUrls` | `string[]` | `[]` | Direct search or place detail public Google Maps URLs |
| `placeIds` | `string[]` | `[]` | Direct Google Place IDs to scrape directly |
| `categories` | `string[]` | `[]` | Filter places post-scrape to keep only matching categories |
| `maxCrawledPlacesPerSearch` | `number` | `100` | Place limit per search tile |
| `maxTotalPlaces` | `number` | `undefined` | Global cap across the entire crawl run |
| `maxReviews` | `number` | `5` | Number of recent reviews to scrape per place (`0` = skip) |
| `reviewsSort` | `string` | `"mostRelevant"` | Sort order: `newest`, `mostRelevant`, `highestRating`, `lowestRating` |
| `zoom` | `number` | `14` | Map zoom level for grid generation (1-21) |
| `language` | `string` | `"en"` | Language code for Google Maps (`hl` param) |
| `scrapePlaceDetailPage` | `boolean` | `true` | When false, exports stubs from feed without visiting detail page |
| `maxImages` | `number` | `10` | Max high-resolution photo URLs to extract |
| `includeReviewerInfo` | `boolean` | `false` | Opt-in for reviewer names/profiles (Privacy compliance) |
| `proxyConfig` | `object` | `{ urls: [] }` | List of proxy URLs (`http://user:pass@host:port`) |
| `concurrency` | `number` | `3` | Parallel Playwright browser workers |
| `outputFormat` | `string` | `"json"` | Export format: `json`, `csv`, `ndjson`, `sqlite` |
| `exportDir` | `string` | `"./results"` | Target directory for generated output files |
| `maxTileDepth` | `number` | `2` | Max recursion depth for adaptive tile subdivision |

> \[!IMPORTANT]
> **Apify Platform Run Options (Timeout: 0s, Memory: 8192 MB, Max Cost: Unlimited)**:
>
> - **Default Run Options**: The Actor specification (`.actor/actor.json`) is configured with `timeoutSecs: 0` (unlimited), `memoryMbytes: 8192` (8 GB RAM), and memory limits up to 16384 MB.
> - **Platform Timeout in Apify Console**: When running or saving tasks in the Apify Web Console, make sure the **Run options** match:
>   - **Timeout**: Set to `0` (unlimited execution time).
>   - **Memory**: Set to `8192 MB` (unlocks full multi-core CPU allocation and high-throughput browser concurrency).
>   - **Maximum cost per run**: Leave blank / empty for **unlimited**.
> - **Blazing-Fast Extraction**: Detail pages extract in 2-3 seconds with instant opening hours detection and optimized review collection. Setting `maxReviews: 0` or `scrapePlaceDetailPage: false` can further accelerate discovery when only business cards/leads are needed.

***

### Output Schema (CRM-Ready Business Lead)

Every scraped business is returned as a structured, CRM-ready lead record directly from Google Maps:

```json
{
  "business_name": "Example Roofing Co.",
  "category": "Roofing contractor",
  "categories": [
    "Roofing contractor",
    "General contractor",
    "Siding contractor"
  ],
  "full_address": "123 Main Street, Austin, TX 78701, USA",
  "city": "Austin",
  "state": "TX",
  "postal_code": "78701",
  "phone": "+1 512 555 0100",
  "website": "https://example-roofing.com",
  "rating": 4.6,
  "review_count": 84,
  "reviews": [
    {
      "author": "A. Smith",
      "rating": 5,
      "text": "Quick estimate and clear communication.",
      "date": "2 weeks ago",
      "response_from_owner": null
    }
  ],
  "price": "$$",
  "description": "Family-owned roofing and exterior restoration contractor serving the Austin metro area.",
  "images": [
    "https://lh5.googleusercontent.com/p/AF1Qip...=s1600"
  ],
  "images_count": 1,
  "opening_hours": {
    "Monday": "9:00 AM - 5:00 PM",
    "Tuesday": "9:00 AM - 5:00 PM",
    "Saturday": "Closed"
  },
  "additional_info": {
    "Service options": [{ "On-site services": true }]
  },
  "lead_score": 100,
  "lead_priority": "high",
  "contactability": "phone",
  "opportunity_signals": [],
  "data_source": "google_maps",
  "latitude": 30.2672,
  "longitude": -97.7431,
  "google_maps_url": "https://www.google.com/maps/place/?q=place_id:ChIJ...",
  "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
  "cid": "15074921902713971043",
  "scraped_at": "2026-03-31T10:00:00.000Z",
  "source_url": "https://www.google.com/maps/search/roofing+contractors+in+Austin"
}
```

#### Lead Scoring & Prioritization

- **`lead_score` (0-100)**: Quantifies lead quality and completeness based strictly on Google Maps listing data: direct phone (+30), official website listed on Maps (+25), rating >= 4.0 (+15), reviews count >= 10 (+15), and operating hours (+15).
- **`lead_priority`**: `"high"` (score >= 70), `"medium"` (40-69), or `"low"` (< 40).
- **`contactability`**: Primary communication channel available directly on Maps: `"phone"`, `"website"`, or `"none"`.
- **`opportunity_signals`**: Detects growth and outreach signals for agencies and sales teams (`"no_website"`, `"missing_phone"`, `"low_rating"`, `"low_review_count"`, `"missing_hours"`, `"unclaimed_listing"`).

***

### Installation & Quick Start

#### Prerequisites

- Node.js 20+ (Node 22 or 24 recommended)
- npm or pnpm

#### 1. Clone & Install

```bash
git clone <repo-url>
cd "1 Google Maps Scraper"
npm install
npx playwright install chromium
npm run build
```

#### 2. Configure Environment

Copy `.env.example` to `.env`:

```bash
cp .env.example .env
```

Add residential or datacenter proxy endpoints if crawling at scale:

```env
PROXIES=http://user:pass@pr.oxylabs.io:7777,http://user:pass@zproxy.lum-superproxy.io:22225
LOG_LEVEL=info
```

#### 3. Run Your First Crawl

```bash
## Using CLI options directly
node dist/index.js run --term "artisan bakery" --location "Austin, TX" --max 10 --out ./results

## Or using a configuration file
node dist/index.js run --config ./examples/search-location.json
```

***

### CLI Commands

#### 1. `scraper run`

Executes a scraping run.

```bash
node dist/index.js run [options]

Options:
  -c, --config <path>      Path to JSON configuration file
  -o, --out <dir>          Output directory for exported files
  -f, --format <format>    Export format: json, csv, ndjson, sqlite (default: json)
  -t, --term <term>        Search term (e.g. "coffee")
  -l, --location <loc>     Location string (e.g. "Brooklyn, NY")
  -m, --max <number>       Max places per search
  --concurrency <number>   Crawler worker concurrency (default: 3)
  --headless <boolean>     Run headless browser (default: true)
  --dry-run                Validate extractors against local HTML fixtures without network
  --fixtures <dir>         Path to fixture folder (default: ./tests/fixtures)
```

#### 2. `scraper geocode`

Inspects coordinates, bounding box, and grid tile count for any location.

```bash
node dist/index.js geocode "Miami Beach, FL" --zoom 14
```

#### 3. `scraper serve`

Launches the Fastify HTTP REST API.

```bash
node dist/index.js serve --port 3000
```

#### 4. `scraper schedule`

Runs recurring scheduled jobs via cron.

```bash
node dist/index.js schedule --cron "0 0 * * *" --config ./examples/search-location.json
```

***

### HTTP API Reference

When started with `node dist/index.js serve`, the scraper exposes full run lifecycle management:

#### `POST /runs`

Start a crawl run.

```json
POST /runs
Content-Type: application/json

{
  "searchTerms": ["italian restaurant"],
  "locationQuery": "Chicago, IL",
  "maxCrawledPlacesPerSearch": 20,
  "outputFormat": "json"
}
```

**Response (202 Accepted):**

```json
{
  "runId": "run_1726508900",
  "status": "RUNNING",
  "exportDir": "d:/.../results/run_1726508900",
  "message": "Crawl run started successfully"
}
```

#### `GET /runs/:id`

Check real-time progress and telemetry.

```json
{
  "runId": "run_1726508900",
  "status": "RUNNING",
  "metrics": {
    "durationSeconds": 42,
    "tilesProcessed": 3,
    "tilesTotal": 12,
    "placesFound": 36,
    "placesScraped": 34,
    "placesFailed": 0,
    "reviewsScraped": 0,
    "blockedRequests": 0,
    "estimatedProxyCostUsd": 0.051
  }
}
```

#### `GET /runs/:id/results`

Download all scraped place results in JSON or streaming NDJSON.

#### `DELETE /runs/:id`

Abort a currently running crawl immediately.

***

### Storage Adapters

The scraper writes incrementally ("write-as-you-go") so progress is never lost on crash or manual abort:

- **JSON (`json`):** Streams newline-delimited records to `places.ndjson` during the crawl, and flushes formatted `places.json` array on completion.
- **CSV (`csv`):** Generates flattened tabular records in `places.csv`. If `maxReviews > 0`, it additionally writes `reviews.csv` linked by foreign key `placeId`.
- **NDJSON (`ndjson`):** High-throughput streaming format for ingestion into ELT/data pipelines (Snowflake, BigQuery, ClickHouse).
- **SQLite (`sqlite`):** Stores normalized records into SQLite database `places.db` with relational `places` and `reviews` tables and indexed `place_id`/`cid`.

***

### Anti-Blocking & Proxy Management

- **Proxy Rotation:** Distributes requests evenly across configured proxy pools. Apify Datacenter proxies are configured by default for maximum speed and cost efficiency, with optional Apify Residential Proxy support for aggressive anti-blocking.
- **Proxy Cost Minimization (85–90% Bandwidth Savings):** Automatically aborts binary image downloads, map vector tiles, video, fonts, and telemetry beacons across all search and detail pages. Image URLs and place metadata are extracted directly from DOM attributes without downloading binary image data over paid proxy bandwidth.
- **Cross-Tile Deduplication:** Automatically tracks place IDs across overlapping geographical tiles to prevent redundant place detail page loads.
- **Stealth Evasions:** Automatically strips `navigator.webdriver`, overrides plugin and language signatures, mocks the Chrome runtime and permissions API, and randomizes desktop viewports.
- **Cookie Consent Bypass:** Automatically pre-seeds Google consent cookies (`SOCS` and `CONSENT`) and intercepts EU cookie consent redirects (`consent.google.com`) in multiple languages.
- **Captcha / Block Detection & Session Retirement:** Monitors for `sorry.google.com` redirects or "unusual traffic" block banners. On trigger, it records telemetry, permanently retires the proxy session, and immediately retries with a fresh proxy IP.
- **CI Dry-Run Mode:** Run `node dist/index.js run --dry-run` to validate DOM selectors against offline HTML fixtures in CI without triggering Google bot detection.

***

### Docker Deployment

Build and run in a containerized environment with all Playwright Chromium dependencies pre-installed:

```bash
## 1. Build image
docker build -t google-maps-scraper:latest .

## 2. Run CLI scraper
docker run --rm -v $(pwd)/results:/app/results google-maps-scraper:latest \
  run --term "orthodontist" --location "Denver, CO" --max 20

## 3. Or run as HTTP API Server
docker run -d -p 3000:3000 -v $(pwd)/results:/app/results google-maps-scraper:latest \
  serve --port 3000
```

***

### Testing

```bash
## Run Vitest test suite (extractors, geo tiling, schema validation)
npm test

## Run TypeScript typecheck
npm run typecheck

## Run offline extractor validation
npm run start -- run --dry-run
```

***

### Legal & Compliance Notice

This software is designed to extract publicly accessible information from Google Maps.

- **Terms of Service:** Users are solely responsible for ensuring compliance with Google's Terms of Service and applicable web scraping regulations in their jurisdiction.
- **Personal Data Protection (GDPR / CCPA):** Reviewer personal identifiers (names, profile links) are classified as personal data. Under default settings, this scraper anonymizes reviewer information (`includeReviewerInfo: false`). Reviewer names should only be scraped after explicit opt-in and in compliance with relevant data privacy laws.

# Actor input Schema

## `category` (type: `string`):

Primary business category or niche (e.g. 'Roofing contractor', 'Dentist', 'Coffee shop', 'Chartered accountant').

## `keyword` (type: `string`):

Specific search keyword or trade query (e.g. 'chartered accountant', 'commercial roofing', 'emergency plumber').

## `location` (type: `string`):

City, state, metro area, or address to automatically tile and search (e.g. 'Austin, TX', 'California', 'London, UK').

## `searchTerms` (type: `array`):

Additional search phrases to run in parallel (e.g. \['roof repair', 'commercial roofing']).

## `startUrls` (type: `array`):

Public Google Maps search or place URLs to scrape directly.

## `maxCrawledPlacesPerSearch` (type: `integer`):

Maximum places to extract per search area / tile.

## `maxTotalPlaces` (type: `integer`):

Hard stop cap across all searches and tiles (default 100).

## `maxReviews` (type: `integer`):

Number of recent customer reviews to extract (author, rating, text, date, owner response).

## `reviewsSort` (type: `string`):

Sort order for extracted reviews.

## `zoom` (type: `integer`):

Zoom level for geospatial tiling (14 recommended for metropolitan business density).

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

Language code for Google Maps results (e.g. 'en', 'es', 'de').

## `scrapePlaceDetailPage` (type: `boolean`):

Scrape complete details including hours, amenities, and photos.

## `includeReviewerInfo` (type: `boolean`):

Include reviewer full names. When disabled, outputs 'Anonymous User' for GDPR/CCPA privacy compliance.

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

Select proxies to be used for Google Maps requests. Apify Datacenter proxies are configured by default for maximum speed and cost efficiency.

## `proxyCostOptimization` (type: `boolean`):

Automatically minimizes proxy data transfer and bandwidth billing by aborting binary image downloads, map vector tiles, video, fonts, and telemetry beacons (saving 85-90% bandwidth).

## `concurrency` (type: `integer`):

Number of parallel browser workers.

## `outputFormat` (type: `string`):

Format for local file export (json, csv, ndjson, sqlite).

## `exportDir` (type: `string`):

Local directory path where scraped results are saved.

## `headless` (type: `boolean`):

Run browser in headless mode (recommended for cloud runs).

## Actor input object example

```json
{
  "category": "Roofing contractor",
  "location": "Austin, TX",
  "maxCrawledPlacesPerSearch": 100,
  "maxTotalPlaces": 100,
  "maxReviews": 5,
  "reviewsSort": "mostRelevant",
  "zoom": 14,
  "language": "en",
  "scrapePlaceDetailPage": true,
  "includeReviewerInfo": false,
  "proxyConfiguration": {
    "useApifyProxy": true
  },
  "proxyCostOptimization": true,
  "concurrency": 3,
  "outputFormat": "json",
  "exportDir": "./results",
  "headless": true
}
```

# Actor output Schema

## `leads` (type: `string`):

One structured record per local business with name, category, address, phone, website, rating, review count, lead score, contactability, and opportunity signals.

## `places` (type: `string`):

Google Maps places dataset records.

## `metrics` (type: `string`):

Execution statistics, runtime durations, tile counts, and estimated proxy costs.

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

Overall scraper run output snapshot in JSON.

## `webServer` (type: `string`):

Interactive live-view server and REST API for real-time monitoring.

# 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 = {
    "category": "Roofing contractor",
    "location": "Austin, TX",
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("autoharvestor/google-maps-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 = {
    "category": "Roofing contractor",
    "location": "Austin, TX",
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("autoharvestor/google-maps-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 '{
  "category": "Roofing contractor",
  "location": "Austin, TX",
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call autoharvestor/google-maps-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,autoharvestor/google-maps-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/0TFwFdKxauTtWLaqN/builds/ixFL4Sfy7ssdowCIN/openapi.json