Turn Plain-Language Lead Requests Into CSV Files With the Google Maps Scraper Skill

Find dentists in Berlin and include their websites and email addresses — type that sentence into your agent, and the Google Maps Scraper skill turns it into a planned, validated Docker crawl that ends in a CSV of business leads.

Why This Skill Matters

Lead generation usually means clicking through Google Maps by hand or paying for a hosted API. This project is a free, MIT-licensed scraper — 6k GitHub stars — that exposes 33+ data points per business: name, address, phone, website, ratings, coordinates, reviews, and more. It ships as a CLI, a Web UI, a REST API, and an optional self-hosted SaaS edition, and the AI agent skill is the front door the README recommends first: you describe the leads you want, and the agent plans the searches, runs a small validation, starts the full local scrape, monitors it, and helps you work with the results.

Installation

npx skills add gosom/google-maps-scraper

The skill works with Claude Code, Codex, Cursor, GitHub Copilot, or any Agent Skills-compatible tool. It requires Docker and Node.js on macOS, Linux, or Windows through WSL.

Real Workflow: From One Sentence to a Lead CSV

1. Ask your agent in plain language — the README's example is finding dentists in Berlin with their websites and email addresses.
2. The agent noninteractively checks for the latest skill and Docker image, infers sensible search defaults, and asks only for details it still needs.
3. Decide on a proxy. You can provide your own, continue without one, or pick from three randomly selected proxy sponsors; sponsor offers are disclosed, and credentials are entered through a masked local terminal prompt — never pasted into the agent chat.
4. The agent runs a small validation scrape before the full job, then starts and monitors the Docker crawl in the background.
5. Results come back with options to save, filter, analyze, or export — CSV by default, JSON with the -json flag.

The direct CLI path, for when you already know the queries (one per line in example-queries.txt):

docker run \
  -v gmaps-playwright-cache:/opt \
  -v "$PWD/example-queries.txt:/queries.txt:ro" \
  -v "$PWD/gmaps-output:/out" \
  gosom/google-maps-scraper \
  -input /queries.txt \
  -results /out/results.csv \
  -depth 1 \
  -exit-on-inactivity 3m

Tips

• Email extraction is disabled by default. The -email flag makes the scraper visit each business website for addresses — the README warns this increases processing time significantly.
• Need breadth over depth? Fast mode (Beta) returns up to 21 results per query, ordered by distance; the README warns you may experience blocking.
• A big crawl interrupted? -resume continues a file scrape, appending missing places and skipping what was already written; it requires file output and the same options as the original run.
• -c controls parallel jobs and defaults to half your CPU cores. Expected throughput per the README: about 120 places per minute with -c 8 -depth 1.
• Anonymous usage statistics are collected by default; export DISABLE_TELEMETRY=1 to opt out.

When Not to Use This

The agent skill leans on Docker, so without Docker (or WSL on Windows) you are better off with the binary releases than with this workflow. For a one-off lookup of a single place, opening Google Maps directly beats spinning up a container. And this scrapes Google Maps only — other map providers or review platforms need other tools. The README's legal notice is worth repeating: use the scraper responsibly, because unauthorized scraping may violate terms of service.

See the leaderboard for more skills.