Skip to content
DariusDev16Public

About

Interactive Google Maps lead extractor. Desktop app for Linux (single-file AppImage, Qt6) + a zero-dependency terminal wizard, both on the same engine: 4 lead APIs, 65 countries, 68 business verticals, 35 fields, 6 export formats.

Topics

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

MAPLEAD

Google Maps lead extractor — desktop apps for Linux and Windows plus a terminal wizard, one engine.

Nine questions, one spreadsheet. Pick a provider, a city, a business type and how many leads you want; MAPLEAD pulls local businesses out of Google Maps through a lead-scraper API and writes them to CSV / Excel / JSON / TXT / TSV / HTML.

MAPLEAD desktop app

🖥️ Desktop app Qt6 window, one file, nothing to install — MAPLEAD-x86_64.AppImage
🪟 Windows one portable MAPLEAD.exe, no admin, no install — MAPLEAD-windows-x64.exe
⌨️ Terminal wizard pure standard-library Python, no dependencies at all
🔌 4 providers Outscraper · Google Places · SerpApi · DataForSEO (+ an offline demo)
🧭 65 countries / 1044 cities typed, filtered, auto-completed — no spelling games
🏷️ 68 business types · 35 fields you choose exactly which columns come out
💬 Leads panel + WhatsApp cards with one-click links and a first message built from the lead
📨 Bulk WhatsApp sends the message to a whole filter through WhatsApp Web, with safety pauses and a contact history
⚡ Turbo mode searches city by city and business by business, and messages every lead that passes your filter
📄 6 export formats csv · xlsx · json · txt · tsv · html

light theme field picker


1 · Get the app

Linux x86_64, AppImage — one file, no packages, no root:

chmod +x MAPLEAD-1.4.2-x86_64.AppImage
./MAPLEAD-1.4.2-x86_64.AppImage

Building it yourself (also fine for arm64/other distros with a rebuild):

git clone https://github.com/DariusDev16/maplead.git
cd maplead
./build-appimage.sh --install     # writes ~/Apps/, adds it to your PATH and menu

No FUSE on your system? The launcher handles it: it unpacks the image once into ~/.maplead-runtime/ and runs from there. No root, no loop device.

Windows 10/11 x64, one .exe — download it and double-click:

.\MAPLEAD-1.2.0-windows-x64.exe

Nothing to unpack and nothing to install: the file is the whole app. It is also the terminal wizard, with exactly the same flags as maplead.py:

.\MAPLEAD-1.2.0-windows-x64.exe --cli            # guided wizard
.\MAPLEAD-1.2.0-windows-x64.exe --cli --demo     # no key, no network
.\MAPLEAD-1.2.0-windows-x64.exe --doctor         # host diagnostics

SmartScreen may warn on first launch because the build is unsigned: More info → Run anyway.

Building it yourself:

git clone https://github.com/DariusDev16/maplead.git
cd maplead
.\build-windows.ps1               # writes %USERPROFILE%\Apps\MAPLEAD-<version>-windows-x64.exe

2 · Add an API key

MAPLEAD never scrapes Google directly — it talks to a lead-scraper API you pay for (or a free trial of). In the app: API keys… (top right) → paste → Save & verify (it makes a real request before saving). Keys live in the per-user config folder: ~/.config/maplead/.env on Linux, %APPDATA%\maplead\.env on Windows (mode 600 / an ACL-protected profile folder).

id service env var per query e-mail / socials
outscraper Outscraper OUTSCRAPER_API_KEY ~200 ✅ (paid enrichment)
google Google Places API (New) GOOGLE_MAPS_API_KEY 60 ❌
serpapi SerpApi SERPAPI_API_KEY ~140 ❌
dataforseo DataForSEO DATAFORSEO_LOGIN + …_PASSWORD ~300 ❌
demo built in – 120 ✅ (synthetic)

No key yet? Run it in Demo mode: synthetic leads, no network, nothing to pay — perfect to try the whole thing first.

3 · Run a search

Fill the form on the left, press Run search (or Ctrl+R), watch the activity log. Results land in a sortable grid; double-click a row to open it in Google Maps, right-click to copy it straight into Sheets.

the nine answers

Everything is filtered after every batch, so a strict --min-rating still fills your quota, and duplicates are removed on place_id (falling back to name + address).

4 · Get the file

A search does not write anything on its own. When the results look right, press Export at the top of the grid (or Ctrl+S). Files land in your Documents folder — ~/Documents/maplead/ on Linux, %USERPROFILE%\Documents\maplead\ on Windows — with a timestamped name. xlsx has a frozen header, auto-filter and a Meta sheet with the search parameters; csv/tsv are UTF-8 (BOM, so Excel keeps the accents); json keeps types and arrays.

harvest report

5 · Message leads in bulk (Linux)

Open the Leads panel, pick a filter (e.g. No website) and press Bulk send:

  1. untick the leads you want to skip — the message preview shows exactly what each one gets;
  2. Start sending opens WhatsApp Web inside MAPLEAD (scan the QR code once);
  3. it sends one message at a time, with random pauses, rests and a "may get blocked — continue?" question every 25 messages.

Everyone you message is remembered, so the next search skips them. Details and the safety settings: docs/GUIDE.md › Bulk WhatsApp.

bulk send: pick the leads, preview, safety settings bulk send: progress and activity log

6 · Turbo mode (Linux)

Turbo mode (under Run search, or Ctrl+T) does the search and the bulk send by itself, for a whole list of cities and business types:

  1. tick the cities and the business types, pick the filter (No website by default) and the safety pauses;
  2. it searches the first business type in the first city, sends your saved message to every lead that passes the filter, then moves to the next business type — and, after the last one, to the next city;
  3. it ends when the lists do, or when you press Stop. Starting it again continues where it stopped, and nobody is messaged twice.

Every search uses provider credits. Details: docs/GUIDE.md › Turbo mode.


Terminal wizard

Same engine, zero dependencies, Python 3.9+:

./maplead.py              # guided: 9 questions
./maplead.py --api        # set + verify an API key
./maplead.py --demo       # try it with no key at all
./maplead.py --gui        # …or open the desktop app

# scriptable
./maplead.py --demo \
  --country "United States" --region "Texas" --city "Austin" \
  --business "plumber" --fields sales --limit 150 --format xlsx \
  --min-rating 4.2 --require-phone --skip-closed --out leads/austin.xlsx
flag meaning
-k, --api key setup: paste, verify live, save
--check-keys / --remove-keys test / wipe stored keys
--provider force a provider instead of auto-detecting
--country --region --city location (DE, Germany, deutschland…)
--business vertical or free text ("solar installer")
--fields name,phone,rating · rec · basic · sales · all
--limit --format --out --outdir volume and destination
--min-rating --min-reviews quality filters
--require-phone --skip-landlines --require-website --skip-closed hard filters (--skip-landlines keeps mobiles only)
--enrich Outscraper contact enrichment (costs credits)
--gui launch the desktop app
--cli run the wizard from the desktop binary (both platforms — no Python needed)
--doctor print environment diagnostics (for bug reports)

The Windows .exe carries the same wizard, so nothing has to be installed first — and on Linux the AppImage does the same through --cli:

.\MAPLEAD-*-windows-x64.exe --cli --demo      # no key, no network
.\MAPLEAD-*-windows-x64.exe --cli --doctor    # what this build thinks your Windows looks like
./MAPLEAD-*-x86_64.AppImage --cli --demo

On Linux the wizard is inside the AppImage — the same file as the desktop app, so nothing has to be installed first either:

./MAPLEAD-1.4.2-x86_64.AppImage --cli --demo
./MAPLEAD-1.4.2-x86_64.AppImage --cli --country DE --city Berlin --business dentist
./MAPLEAD-1.4.2-x86_64.AppImage --cli --doctor

You can add ~/.local/bin/maplead-cli yourself (#!/bin/sh + exec "$HOME/Apps"/MAPLEAD-*-x86_64.AppImage --cli "$@") if you want the wizard on the PATH.


Screenshots

first run api keys
Empty first run — Demo mode is ready before you add a key Keys window: paste, verify, save

More detail in docs/GUIDE.md (user guide) and docs/DEVELOPMENT.md (architecture, build, release).

Status

Linux (AppImage) and Windows 10/11 x64 (portable ZIP) are packaged and tested in CI. The terminal wizard runs anywhere Python 3.9+ does. macOS packaging is on the roadmap.

Legal

Lead data returned by these APIs is public business information. Respect each provider's terms and rate limits, and your GDPR/LGPD/PCCB obligations before cold-contacting anyone. Automated WhatsApp messages go against WhatsApp's terms of service: the bulk sender's pauses lower the risk of a ban, they do not remove it. MAPLEAD never edits Google Maps — it only reads what the provider APIs already expose.

License

MIT © 2026 MAPLEAD contributors.

About

Interactive Google Maps lead extractor. Desktop app for Linux (single-file AppImage, Qt6) + a zero-dependency terminal wizard, both on the same engine: 4 lead APIs, 65 countries, 68 business verticals, 35 fields, 6 export formats.

Topics

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages