Skip to content
Projects

Ayyouboss0011/SherlockMaps has 96 GitHub stars and 12 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-16 20:08 UTC. Last push 2026-11-14.

How these counts are measured

What you can do

  • Search Google Maps with any query
  • Company name, category, address, phone, website, rating, review count, Plus Code, opening hours and attributes
  • Optional review extraction
  • Deduplication and website URL validation

Measured star growth

in 24h
0
in 7 days
Update delayed
in 15 days
Update delayed
in 1 month
Update delayed

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

Powerful Google Maps Crawler / Scraper tool with REST API, Docker support & multi-format export

Developer Tools

README.md

Original
Sherlock Maps — Google Maps scraper and lead generation suite

Sherlock Maps

Turn Google Maps searches into clean, enriched lead lists — self-hosted and open source.

GitHub stars Latest release Python 3.9+ MIT license Docker Compose

Sherlock Maps dashboard

Sherlock Maps is a self-hosted Google Maps crawler and lead-generation suite. It extracts business names, categories, addresses, phone numbers, websites, ratings, reviews, opening hours and attributes — then enriches companies with email addresses from their websites.

Use the Next.js dashboard to start crawls, inspect results, export CSV/JSON and run email campaigns. Use the REST API or Python library when you want to build your own workflow.

Why Sherlock Maps?

  • Self-hosted and open source — your data stays on your infrastructure.
  • No per-result fees — no paid scraper API and no credit-based pricing.
  • Full lead pipeline — Google Maps → company data → email enrichment → export or outreach.
  • Developer-friendly — REST API, Python library, Docker Compose and a typed Next.js UI.
  • Reproducible browser setup — bundled cookie-consent extension plus optional local Chrome profile.

Features

Crawling

  • Search Google Maps with any query
  • Company name, category, address, phone, website, rating, review count, Plus Code, opening hours and attributes
  • Optional review extraction
  • Deduplication and website URL validation
  • Configurable result limits and scroll behavior

Lead enrichment

  • Crawl company websites for email addresses
  • Follow contact, imprint and about pages
  • Deduplicate emails and keep source metadata
  • Auto-trigger email enrichment after a map crawl

Dashboard

  • Live crawler status and KPIs
  • Job history with expandable company results
  • Search, inspect and export leads
  • SMTP settings, email templates and campaign history
  • Do-not-contact blacklist with CSV/XLSX import

Deployment

  • One-command Docker Compose stack
  • Persistent jobs, results, SMTP data and Chrome profile
  • REST API with Swagger UI
  • JSON, CSV, pretty-printed and file output
  • Local Python + Next.js development workflow

Quick start

Docker Compose (recommended)

git clone https://github.com/Ayyouboss0011/SherlockMaps.git
cd SherlockMaps
cp .env.example .env
docker compose up -d --build

Open:

Start a crawl from the dashboard or with the API:

curl -X POST http://localhost:6970/crawl \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "restaurants berlin",
    "auto_email_crawl": true,
    "max_results": 50
  }'

Check progress and export results:

curl http://localhost:6970/status
curl "http://localhost:6970/results?format=csv" -o leads.csv

The first build downloads Playwright and Chromium, so it can take a few minutes. The default ports can be changed in .env. See the quick start guide for local development and more commands.

Screenshots

Sherlock Maps dashboard with live crawler KPIs Company results with emails and ratings

Dashboard and enriched company results.

Email campaign composer with recipients SMTP settings and email templates

Campaign composer and SMTP/template settings.

Screenshots use fictional demo data. No real leads, email addresses or SMTP credentials are shown.

How it works

flowchart LR
    A[Google Maps] --> B[Playwright crawler]
    B --> C[Company extractor]
    C --> D[Deduplication + URL validation]
    D --> E[Company results]
    E --> F[Email enrichment]
    E --> G[CSV / JSON export]
    F --> H[REST API + job store]
    H --> I[Next.js dashboard]
    F --> J[Email campaigns]
  1. Search — navigate to Google Maps with your search term.
  2. Scroll and extract — load result cards and open each detail page.
  3. Clean — deduplicate companies and validate websites.
  4. Enrich — optionally crawl company websites for email addresses.
  5. Deliver — inspect in the dashboard, use the API or export CSV/JSON.

More detail: Architecture.

Use cases

  • Lead generation — build targeted local-business lists for agencies and sales teams.
  • Local SEO — audit categories, ratings, reviews and websites across a market.
  • Market research — compare competitors, categories and opening hours by city.
  • CRM enrichment — add websites and contact emails to an existing lead database.

REST API & Python

The API is documented interactively at /docs. A typical flow:

API=http://localhost:6970

# Start a crawl
curl -X POST "$API/crawl" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "cafes berlin", "auto_email_crawl": true}'

# Poll the job
curl "$API/crawl/JOB_ID"

# Get results
curl "$API/crawl/JOB_ID/results"

Use the crawler as a Python library:

from core.crawler import run_crawler

results = run_crawler(
    prompt="restaurants berlin",
    headless=False,
    output_format="json",
)

for company in results:
    print(company.name, company.website)

Full endpoint reference: REST API.

Configuration

Variable Default Description
API_PORT 6970 Docker host port for the API
UI_PORT 3008 Docker host port for the dashboard
OUTPUT_FORMAT json json, csv, pretty, file, print
HEADLESS false Run Chromium without a window
TRACK_REVIEWS true Extract review data
CHROME_PROFILE_PATH core/Chrome_Profile Optional local Chrome profile

See Configuration for the complete list.

Chrome profile & extensions

Your personal Chrome profile — cookies, logins and extensions — stays local and is never committed. The crawler uses core/Chrome_Profile by default and also supports CHROME_PROFILE_PATH and use_persistent_profile for API crawls.

The repository bundles I still don't care about cookies in core/extensions/, so every user gets the same cookie-banner handling without sharing a profile. Add your own unpacked extensions to core/extensions/.

Deployment

The API has no authentication by default. Keep it on localhost or a trusted network, or put it behind an authenticated reverse proxy.

Roadmap

  • Google Maps company extraction
  • Email enrichment
  • REST API + Next.js dashboard
  • Docker Compose deployment
  • Static demo with sample data
  • n8n / Google Sheets / CRM integrations
  • Additional locales
  • PyPI package

Have an idea or found a bug? Open an issue.

Contributing

Contributions are welcome. Read CONTRIBUTING.md for setup, branch naming, screenshot updates and the PR checklist.

Good first issues are labeled good first issue.

License

Sherlock Maps is released under the MIT License.

The bundled cookie-consent extension is GPL-3.0. See THIRD_PARTY_NOTICES.md.

Responsible use

Sherlock Maps is intended for research and internal business use. Scraping Google Maps may be subject to Google's Terms of Service and local law. Respect rate limits, privacy rights and anti-spam rules. The email blacklist exists to help you honor opt-outs.


If Sherlock Maps saves you time, a ⭐ helps other developers find it.