ayyouboss0011/sherlockmaps

SherlockMaps is an open-source Google Maps scraper that pulls business information off the public Google Maps website. You give it a search term like "restaurants berlin" and it drives a real Chromium browser through Google Maps using Playwright, an automation library that controls browsers programmatically. For each listing it finds, it extracts the company name, category, address, phone number, website, star rating, number of reviews, Plus Code, opening hours, and attributes such as wheelchair accessibility. Results are deduplicated by name plus website, and obviously invalid website URLs are filtered out. There are three ways to run it. The command-line mode takes a PROMPT environment variable and prints results to standard output, with optional output formats including JSON, CSV, a human-readable pretty print, or saving to a timestamped file. The REST API mode runs as a persistent server on port 8000, with a /crawl POST endpoint that queues jobs asynchronously, status and history endpoints, and an interactive docs page at /docs. The Python library mode lets you import GoogleMapsCrawler from core.crawler and use it as a context manager, calling crawl() multiple times with different search terms in one session. Docker is the recommended path: a docker compose up brings up the API server with Playwright and the Chromium browser already set up inside the container, so you do not have to install Python dependencies on your own machine. The README also documents a direct install path, where you create a Python 3.9 or newer environment, pip install requirements, and then run playwright install chromium to fetch the browser binaries. The API surface is broad: there are endpoints for health checks, job queue status, statistics, fetching results in bulk, exporting results, clearing results, and reading or updating configuration at runtime. Chrome profile data persists between runs, which helps with session state. The license is MIT. The README does not address legal or terms-of-service questions about scraping Google Maps, which a non-technical reader should consider before using the tool at scale, since Google's terms restrict automated access to Maps data.