Google Maps Scraper: Extract Business Leads from Google Maps via CLI, Web UI, and REST API

What the Scraper Extracts and Who Uses It

The scraper retrieves business profile data as Google Maps presents it: name, address, phone number, website URL, rating, number of reviews, latitude and longitude coordinates, email address (when listed on the business page or website), and full review text. The README describes the target use cases as lead generation, local business research, sales prospecting, data enrichment, and developer automation. The project provides several interfaces for different workflows: a command-line tool for scripted or one-off runs, a browser-based Web UI for interactive operation, a REST API for integration with other services, and an AI Agent Skill for use with coding agents. A multi-user SaaS edition is documented separately in docs/saas.md for teams that need a shared platform with user management. The current release is v1.18.1, published on 2026-09-20.

How It Works: Playwright-Based Browser Scraping

The scraper loads Google Maps pages using Playwright, a browser automation library, running a headless Chromium instance. This approach makes the scraper behave like a real browser visit rather than a raw HTTP request, which allows it to process the JavaScript-rendered content that Google Maps produces. The Go module dependencies include github.com/mxschmitt/playwright-go for browser automation and github.com/gosom/scrapemate as the underlying scraping framework. Results can be stored in PostgreSQL (using pgx) or SQLite (using modernc.org/sqlite). The Dockerfile uses a three-stage build: a Playwright dependency stage that downloads and installs Chromium with its system dependencies, a Go build stage, and a final Debian slim runtime image. Running Chromium in Docker requires a set of system libraries that the Dockerfile installs explicitly, including libnss3, libatk1.0-0, and libgbm1. The go.mod specifies Go 1.27.1, and the Dockerfile uses that same version as the build base.

Installing and Running the Scraper

The project targets Docker on macOS, Linux, or Windows via WSL. Building the Docker image:

docker build -t google_maps_scraper .

For the AI Agent Skill workflow, install Node.js and then install the skill:

npx skills add gosom/google-maps-scraper

Once the skill is installed, describe the leads you want in plain language to an AI coding agent such as Claude Code. The agent plans the searches, runs a validation, starts the scrape, and monitors it. For larger crawls, proxy credentials are entered through a masked local terminal prompt rather than in the agent chat.

For a direct CLI run, the Makefile includes a build target:

make build

The binary is written to bin/google_maps_scraper. The README points to docs/recipes.md for common workflow examples and to docs/saas.md for multi-user platform setup. The example-queries.txt file in the repository root contains sample input queries.

Proxy Support and Rate Limiting

Google Maps detects and blocks automated traffic. Running the scraper at any significant volume requires a proxy. The README integrates proxy sponsor links and mentions that the AI Agent Skill workflow includes a proxy selection step that presents a curated list of sponsors. Proxy credentials entered during that flow are masked and are not stored in the agent chat history. The project's go.mod includes github.com/posthog/posthog-go, indicating that usage analytics are collected; the tlmt/ directory in the repository root is consistent with telemetry collection. For teams running in jurisdictions or organizational environments where external analytics are a concern, reviewing the tlmt/ code before deployment is prudent. Rate limiting is controlled by the underlying scrapemate framework.

The go.mod file also includes cloud infrastructure dependencies: AWS Lambda and S3 SDKs, a DigitalOcean client, and a Hetzner Cloud client. These reflect a deployment model where the scraper can run on cloud instances rather than only on a local machine. The PROVISION file in the repository root and the infra/ directory contain provisioning scripts for cloud-based deployments. The rqueue/ directory provides a job queue abstraction, and the River queue library (github.com/riverqueue/river) with its PostgreSQL driver (riverqueue/river/riverdriver/riverpgxv5) handles task scheduling for longer-running scrapes. This queue-backed design allows large scraping jobs to continue in the background and survive process restarts.

Limitations: Terms of Service and Scale

Google's Terms of Service prohibit automated scraping of their services without explicit permission. The project does not provide legal cover and the README does not address the legal question directly. In practice, running the scraper against Google Maps violates Google's ToS. Google actively detects and blocks scraping traffic; the proxy dependency is a direct consequence of this friction. The scraper is also not real-time: it loads pages sequentially through a browser, making it unsuitable for applications that need fresh data on sub-minute intervals. The SaaS edition extends the single-instance model to multi-user operation but does not change the fundamental architecture or the ToS situation. Teams needing production-grade Google Maps data should evaluate the official Google Places API and its pricing as the fully compliant alternative that avoids these constraints.

Google Maps Scraper vs. SerpApi

SerpApi is a commercial API that handles Google search and Maps scraping on behalf of clients, manages proxies and bot detection internally, and returns structured JSON. The key difference from gosom/google-maps-scraper is operational: SerpApi is a hosted service where Google scraping infrastructure is managed by a third party, while gosom/google-maps-scraper is self-hosted Go code you run yourself. Self-hosting gives full control over data handling, storage format, and integration, and costs nothing beyond infrastructure. SerpApi abstracts away proxy management and page-load complexity at the cost of a per-request fee and dependency on a third-party service. For small research projects or one-off data collection, the open-source tool is practical. For continuous production data pipelines with reliability requirements, a managed API removes operational burden.

The repository also documents third-party data providers in dedicated files: serpapi.md, scrap_io.md, talordata.md, and webshare.md. These are sponsor integration notes rather than core code, but they indicate that the project's community regularly uses external data services alongside self-hosted scraping. The skills/ directory at the root contains the AI agent skill files, including a proxy selection script (select-proxy-sponsors.mjs) and a status check script (status-local.mjs) that the Makefile's test-agent-skill target validates.

Editorial conclusion

Google Maps Scraper is the right choice for developers and data teams who need structured business data from Google Maps and want full control over where results go: a local CSV, a PostgreSQL database, or a downstream REST endpoint. The tool uses a real Chromium browser via Playwright to load pages, which means it requires Docker and a reasonably capable machine to run reliably. Legal review is always required before scraping, because Google's Terms of Service restrict automated access to their services. Teams with high-volume or production-grade data needs should review the SaaS edition documentation in docs/saas.md and the proxy guidance in the README before treating the free single-instance setup as their only option.

Frequently asked questions

Official sources

1. gosom/google-maps-scraper on GitHub
2. Issues
3. License: MIT
4. README
5. Releases