Google Maps Scraper

A Tkinter desktop UI on top of a Playwright-driven Google Maps scraper. Designed for long, resumable scraping sessions across many keyword × area combinations.

Run

python run_app.py

(Or double-click start.bat on Windows.)

On first launch the app installs Playwright and Chromium itself — you only need a Python 3.10+ install on PATH.

Features

• Runs — every scraping session is a named "run" with its config saved in SQLite. History persists across launches.
• Pause / Resume / Stop — progress is checkpointed between queries. Closing the app mid-run is safe; pick up later with one click.
• Continue last — jumps straight to the most recent run with pending queries.
• Crash recovery — queries marked in_progress get re-queued on resume.
• Deduplication
  • global scope — skip records already present in any previous run.
  • run scope — dedup only within the current run.
  • Seed from CSV — point at any prior CSV (this app's, the original script's, or an export) and its name|address keys are added to the skip set on top of the chosen scope.
• Editable keyword / area lists — add, remove (Delete key works), reset to defaults. Edits persist to gmaps_prefs.json.
• Live tab — progress bar, counters, scrolling log.
• Results tab — filterable by selected run or all runs.
• CSV export — per-run or combined. Optional auto-export on run completion.
• Anti-detection — randomised user-agent / viewport, consent and CAPTCHA handling, browser recycling every 30 queries (carried over from the upstream script).

Project layout

run_app.py            Entry point (bootstrap then UI)
start.bat             Windows double-click launcher
gmaps_app/
  __init__.py
  bootstrap.py        First-launch installer with progress window
  models.py           Business, Run, QueryRow dataclasses
  db.py               SQLite repo with migrations
  scraper.py          Playwright primitives (navigate, scroll, extract)
  runner.py           Thread + asyncio orchestrator (pause/resume/stop)
  csv_import.py       Read dedup keys from arbitrary CSVs
  prefs.py            Tiny JSON prefs store
  ui.py               Tkinter UI

Storage

Created next to run_app.py:

• gmaps_data.db — SQLite database (runs, queries, businesses)
• gmaps_prefs.json — your edited keyword / area lists
• .gmaps_bootstrap_complete — marker so setup only runs once
• scraper.log — log file (if logging to disk is enabled)

All of these are git-ignored.

Use responsibly

Scraping Google Maps may breach their terms of service. Use this for research, recovery of your own data, or in jurisdictions / contexts where it is permitted. You are responsible for how you use it.