Skip to content
Back to search

google-maps-scraper

scrape data from Google Maps. Extracts data such as the name, address, phone number, website URL, rating, reviews number, latitude and longitude, reviews,email and more for each place

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/gosom/google-maps-scraper with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/gosom/google-maps-scraper'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gosom-google-maps-scraper/badge.svg)](/listings/gosom-google-maps-scraper)

HTML

<a href="/listings/gosom-google-maps-scraper"><img src="/api/listings/gosom-google-maps-scraper/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Command Line

mkdir -p gmaps-output

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

Useful options:

| Need | Flag | |---|---| | Extract emails from business websites | `-email` | | Write JSON instead of CSV | `-json -results /out/results.json` | | Collect extra reviews | `-extra-reviews -json -results /out/results.json` | | Resume an interrupted file scrape | `-resume -results /out/results.csv` | | Increase concurrency | `-c 4`, `-c 8`, or `-c 16` | | Run multiple pages per browser | `-pages-per-browser 4` | | Limit browser processes | `-browser-pool-size 2` | | Use proxies | `-proxies "http://user:pass@host:port,socks5://host:port"` | | Read proxies from a credentials file | `-proxies-file /path/to/proxies.txt` |

`-c` controls how many scrape jobs run in parallel. Higher concurrency can finish large input files faster, but it also uses more CPU/RAM and can increase blocking or failures, especially without proxies. Start with the default for a first run. For larger jobs on a capable machine, try `-c 4`, `-c 8`, or `-c 16` and measure the result.

**Want to skip CSV files?** Send leads directly to [LeadsDB](https://getleadsdb.com/):

docker run \
  -v gmaps-playwright-cache:/opt \
  -v "$PWD/example-queries.txt:/queries.txt:ro" \
  gosom/google-maps-scraper \
  -input /queries.txt \
  -depth 1 \
  -leadsdb-api-key "your-api-key" \
  -exit-on-inactivity 3m

Web UI

Start the web interface with a single command:

mkdir -p gmapsdata

docker run \
  -v "$PWD/gmapsdata:/gmapsdata" \
  -p 8080:8080 \
  gosom/google-maps-scraper \
  -data-folder /gmapsdata

Then open http://localhost:8080 in your browser.

Or download the [binary release](https://github.com/gosom/google-maps-scraper/releases) for your platform.

> **Note:** Results take at least 3 minutes to appear (minimum configured runtime). > > **macOS Users:** Docker command may not work. See [MacOS Instructions](MacOS%20instructions.md).

REST API

When running the web server, a full REST API is available:

| Endpoint | Method | Description | |----------|--------|-------------| | `/api/v1/jobs` | POST | Create a new scraping job | | `/api/v1/jobs` | GET | List all jobs | | `/api/v1/jobs/{id}` | GET | Get job details | | `/api/v1/jobs/{id}` | DELETE | Delete a job | | `/api/v1/jobs/{id}/download` | GET | Download results as CSV |

Full OpenAPI 3.0.3 documentation available at http://localhost:8080/api/docs

SaaS Edition

Need a multi-user platform with API keys, admin UI, job queue, workers, and cloud provisioning? Use the optional self-hosted SaaS edition:

curl -fsSL https://raw.githubusercontent.com/gosom/google-maps-scraper/main/PROVISION | sh

See [SaaS documentation](docs/saas.md) for deployment and operations details. There is also a [5-minute deployment walkthrough](https://gosom.dev/deploy-your-own-maps-scraping-api-in-5-minutes/) and a [YouTube video walkthrough](https://www.youtube.com/watch?v=STG9mZw_nac).

More examples are available in [Recipes](docs/recipes.md). If you need proxies for larger jobs, see [Proxy Sponsors](docs/proxies.md).

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 788 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Google Maps Scraper
  2. <p align="center">
  3. <a href="https://github.com/gosom/google-maps-scraper/stargazers"><img src="https://img.shields.io/github/stars/gosom/google-maps-scraper?style=social" alt="GitHub Stars"></a>
  4. <a href="https://github.com/gosom/google-maps-scraper/network/members"><img src="https://img.shields.io/github/forks/gosom/google-maps-scraper?style=social" alt="GitHub Forks"></a>
  5. <a href="https://twitter.com/intent/tweet?text=Powerful%20open-source%20Google%20Maps%20scraper%20-%20extract%20business%20data%20at%20scale%20with%20CLI%2C%20Web%20UI%2C%20or%20REST%20API&url=https%3A%2F%2Fgithub.com%2Fgosom%2Fgoogle-maps-scraper&hashtags=golang,webscraping,googlemaps,opensource"><img src="https://img.shields.io/twitter/url/http/shields.io.svg?style=social" alt="Tweet"></a>
  6. </p>
  7. [![Build Status](https://github.com/gosom/google-maps-scraper/actions/workflows/build.yml/badge.svg)](https://github.com/gosom/google-maps-scraper/actions/workflows/build.yml)
  8. [![Go Report Card](https://goreportcard.com/badge/github.com/gosom/google-maps-scraper)](https://goreportcard.com/report/github.com/gosom/google-maps-scraper)
  9. [![GoDoc](https://godoc.org/github.com/gosom/google-maps-scraper?status.svg)](https://godoc.org/github.com/gosom/google-maps-scraper)
  10. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  11. [![Discord](https://img.shields.io/badge/Discord-Join%20Chat-7289DA?logo=discord&logoColor=white)](https://discord.gg/fpaAVhNCCu)
  12. Extract Google Maps business leads, emails, reviews, phone numbers, websites, ratings, coordinates, and more with a free open-source CLI, Web UI, REST API, and optional self-hosted platform.
  13. Use it for lead generation, local business research, sales prospecting, data enrichment, or developer automation.
  14. ## Paid Setup and Integration
  15. Work directly with the maintainer to deploy the scraper on your infrastructure, configure scraping jobs, or integrate the API with your application.
  16. **[Book a call](https://www.cal.eu/g-k-lsoknt/gosom)** to discuss your project and scope a paid engagement.
  17. ## Ask an AI Agent to Get Leads
  18. The easiest way to use Google Maps Scraper is with an AI coding agent such as [Claude Code](https://claude.com/claude-code), Codex, Cursor, GitHub Copilot, or any [Agent Skills-compatible tool](https://agentskills.io). You describe the leads you want; the agent plans the searches, runs a small validation, starts the full local scrape, monitors it, and helps you work with the results.
  19. Install the skill:
  20. ```bash
  21. npx skills add gosom/google-maps-scraper
  22. ```
  23. Then ask your agent in plain language:
  24. > Find dentists in Berlin and include their websites and email addresses.
  25. The agent automatically checks for the latest skill and Docker image, then asks only for details it still needs. For larger crawls, you can provide your own proxy, continue without one, or review one randomly selected proxy sponsor. Proxy credentials are entered through a masked local terminal prompt and are never pasted into the agent chat.
  26. Requires Docker and Node.js on macOS, Linux, or Windows through WSL. See [how the agent workflow works](#ai-agent-skill).
  27. | Goal | Start here |
  28. |---|---|
  29. | Get leads into CSV/JSON | [Command Line](#command-line) |
  30. | Ask an AI coding agent to run a scrape | [AI Agent Skill](#ai-agent-skill) |
  31. | Run a browser UI locally | [Web UI](#web-ui) |
  32. | Automate scraping from your app | [REST API](#rest-api) |
  33. | Run a multi-user scraping platform | [SaaS Edition](docs/saas.md) |
  34. | Follow common workflows | [Recipes](docs/recipes.md) |
  35. ![Example GIF](img/example.gif)
  36. If this project is useful to you, a GitHub star helps others discover it. Sponsorships help fund maintenance and new work.
  37. ---
  38. ## Featured Sponsor
  39. <table width="100%">
  40. <tr>
  41. <td align="left" valign="middle" width="67%">
  42. <a href="https://www.webshare.io/?referral_code=0q3l81eet8mp">
  43. <img src="./img/webshare-featured-banner.png" alt="Webshare — Premium proxies for scraping" width="600">
  44. </a>
  45. </td>
  46. <td align="left" valign="middle" width="33%">
  47. <p>The most affordable premium proxies across 195 countries &amp; 80+ million IPs, plus a FREE plan for new users.</p>
  48. <a href="https://www.webshare.io/?referral_code=0q3l81eet8mp">Visit Webshare →</a>
  49. </td>
  50. </tr>
  51. </table>
  52. ## Sponsored By
  53. These sponsors help support development and maintenance of Google Maps Scraper.
  54. <table width="100%">
  55. <tr>
  56. <td align="center" valign="middle" width="33%">
  57. <a href="https://www.coreclaw.com/?utm_source=github&amp;utm_medium=referral&amp;utm_campaign=gosom&amp;utm_term=&amp;utm_id=gosom">
  58. <img src="./img/sponsors/coreclaw.svg" alt="Coreclaw" width="250" height="100"><br>
  59. <strong>Coreclaw</strong>
  60. </a>
  61. </td>
  62. <td align="center" valign="middle" width="33%">
  63. <a href="https://evomi.com?utm_source=github&amp;utm_medium=banner&amp;utm_campaign=gosom-maps">
  64. <img src="./img/sponsors/evomi.svg" alt="Evomi" width="250" height="100"><br>
  65. <strong>Evomi</strong>
  66. </a>
  67. </td>
  68. <td align="center" valign="middle" width="33%">
  69. <a href="https://gmapsextractor.com?utm_source=github&amp;utm_medium=banner&amp;utm_campaign=gosom">
  70. <img src="./img/sponsors/g-maps-extractor.svg" alt="G Maps Extractor" width="250" height="100"><br>
  71. <strong>G Maps Extractor</strong>
  72. </a>
  73. </td>
  74. </tr>
  75. <tr>
  76. <td align="center" valign="middle" width="33%">
  77. <a href="https://hasdata.com/scrapers/google-maps?utm_source=github&amp;utm_medium=sponsorship&amp;utm_campaign=gosom">
  78. <img src="./img/sponsors/hasdata.svg" alt="HasData" width="250" height="100"><br>
  79. <strong>HasData</strong>
  80. </a>
  81. </td>
  82. <td align="center" valign="middle" width="33%">
  83. <a href="https://go.nodemaven.com/GoogleMapsScrapperoctober">
  84. <img src="./img/sponsors/nodemaven.svg" alt="NodeMaven" width="250" height="100"><br>
  85. <strong>NodeMaven</strong>
  86. </a>
  87. </td>
  88. <td align="center" valign="middle" width="33%">
  89. <a href="https://www.rapidproxy.io/?ref=gosom">
  90. <img src="./img/sponsors/rapidproxy.svg" alt="RapidProxy" width="250" height="100"><br>
  91. <strong>RapidProxy</strong>
  92. </a>
  93. </td>
  94. </tr>
  95. <tr>
  96. <td align="center" valign="middle" width="33%">
  97. <a href="https://scrap.io?utm_medium=ads&amp;utm_source=github_gosom_gmap_scraper">
  98. <img src="./img/sponsors/scrap-io.svg" alt="Scrap.io" width="250" height="100"><br>
  99. <strong>Scrap.io</strong>
  100. </a>
  101. </td>
  102. <td align="center" valign="middle" width="33%">
  103. <a href="https://www.searchapi.io/google-maps?via=gosom&amp;utm_source=github&amp;utm_medium=sponsorship&amp;utm_campaign=gosom">
  104. <img src="./img/sponsors/searchapi.svg" alt="SearchApi" width="250" height="100"><br>
  105. <strong>SearchApi</strong>
  106. </a>
  107. </td>
  108. <td align="center" valign="middle" width="33%">
  109. <a href="https://serpapi.com/?utm_source=google-maps-scraper">
  110. <img src="./img/sponsors/serpapi.svg" alt="SerpApi" width="250" height="100"><br>
  111. <strong>SerpApi</strong>
  112. </a>
  113. </td>
  114. </tr>
  115. <tr>
  116. <td align="center" valign="middle" width="33%">
  117. <a href="https://talordata.com/?campaignid=f01u8cHondg2qA47&amp;utm_source=github&amp;utm_term=googlemaps">
  118. <img src="./img/sponsors/talordata.svg" alt="TalorData" width="250" height="100"><br>
  119. <strong>TalorData</strong>
  120. </a>
  121. </td>
  122. <td align="center" valign="middle" width="33%"><a href="https://github.com/sponsors/gosom">Become a sponsor</a></td>
  123. <td width="33%"></td>
  124. </tr>
  125. </table>
  126. [View all sponsors and offers](SPONSORS.md) · [Become a sponsor](https://github.com/sponsors/gosom)
  127. ---
  128. ## Why Use This Scraper?
  129. | | |
  130. |---|---|
  131. | **Completely Free & Open Source** | MIT licensed, no hidden costs or usage limits |
  132. | **Multiple Interfaces** | CLI, Web UI, REST API - use what fits your workflow |
  133. | **High Performance** | ~120 places/minute with optimized concurrency |
  134. | **33+ Data Points** | Business details, reviews, emails, coordinates, and more |
  135. | **Production Ready** | Scale from a single machine to Kubernetes clusters |
  136. | **Flexible Output** | CSV, JSON, PostgreSQL, S3, or custom plugins |
  137. | **Proxy Support** | Built-in SOCKS5/HTTP/HTTPS proxy rotation |
  138. ---
  139. ## Table of Contents
  140. - [Quick Start](#quick-start)
  141. - [Command Line](#command-line)
  142. - [Web UI](#web-ui)
  143. - [REST API](#rest-api)
  144. - [SaaS Edition](#saas-edition)
  145. - [AI Agent Skill](#ai-agent-skill)
  146. - [Recipes](docs/recipes.md)
  147. - [Proxy Sponsors](docs/proxies.md)
  148. - [Installation](#installation)
  149. - [Features](#features)
  150. - [Extracted Data Points](#extracted-data-points)
  151. - [Configuration](#configuration)
  152. - [Command Line Options](#command-line-options)
  153. - [Using Proxies](#using-proxies)
  154. - [Email Extraction](#email-extraction)
  155. - [Fast Mode](#fast-mode)
  156. - [Advanced Usage](#advanced-usage)
  157. - [PostgreSQL Database Provider](#postgresql-database-provider)
  158. - [Kubernetes Deployment](#kubernetes-deployment)
  159. - [Custom Writer Plugins](#custom-writer-plugins)
  160. - [Performance](#performance)
  161. - [Support the Project](#support-the-project)
  162. - [Community](#community)
  163. - [Contributing](#contributing)
  164. - [License](#license)
  165. ---
  166. ## Quick Start
  167. ### Command Line
  168. ```bash
  169. mkdir -p gmaps-output
  170. docker run \
  171. -v gmaps-playwright-cache:/opt \
  172. -v "$PWD/example-queries.txt:/queries.txt:ro" \
  173. -v "$PWD/gmaps-output:/out" \
  174. gosom/google-maps-scraper \
  175. -input /queries.txt \
  176. -results /out/results.csv \
  177. -depth 1 \
  178. -exit-on-inactivity 3m
  179. ```
  180. Useful options:
  181. | Need | Flag |
  182. |---|---|
  183. | Extract emails from business websites | `-email` |
  184. | Write JSON instead of CSV | `-json -results /out/results.json` |
  185. | Collect extra reviews | `-extra-reviews -json -results /out/results.json` |
  186. | Resume an interrupted file scrape | `-resume -results /out/results.csv` |
  187. | Increase concurrency | `-c 4`, `-c 8`, or `-c 16` |
  188. | Run multiple pages per browser | `-pages-per-browser 4` |
  189. | Limit browser processes | `-browser-pool-size 2` |
  190. | Use proxies | `-proxies "http://user:pass@host:port,socks5://host:port"` |
  191. | Read proxies from a credentials file | `-proxies-file /path/to/proxies.txt` |
  192. `-c` controls how many scrape jobs run in parallel. Higher concurrency can finish large input files faster, but it also uses more CPU/RAM and can increase blocking or failures, especially without proxies. Start with the default for a first run. For larger jobs on a capable machine, try `-c 4`, `-c 8`, or `-c 16` and measure the result.
  193. ### Web UI
  194. Start the web interface with a single command:
  195. ```bash
  196. mkdir -p gmapsdata
  197. docker run \
  198. -v "$PWD/gmapsdata:/gmapsdata" \
  199. -p 8080:8080 \
  200. gosom/google-maps-scraper \
  201. -data-folder /gmapsdata
  202. ```
  203. Then open http://localhost:8080 in your browser.
  204. Or download the [binary release](https://github.com/gosom/google-maps-scraper/releases) for your platform.
  205. > **Note:** Results take at least 3 minutes to appear (minimum configured runtime).
  206. >
  207. > **macOS Users:** Docker command may not work. See [MacOS Instructions](MacOS%20instructions.md).
  208. ### REST API
  209. When running the web server, a full REST API is available:
  210. | Endpoint | Method | Description |
  211. |----------|--------|-------------|
  212. | `/api/v1/jobs` | POST | Create a new scraping job |
  213. | `/api/v1/jobs` | GET | List all jobs |
  214. | `/api/v1/jobs/{id}` | GET | Get job details |
  215. | `/api/v1/jobs/{id}` | DELETE | Delete a job |
  216. | `/api/v1/jobs/{id}/download` | GET | Download results as CSV |
  217. Full OpenAPI 3.0.3 documentation available at http://localhost:8080/api/docs
  218. ### SaaS Edition
  219. Need a multi-user platform with API keys, admin UI, job queue, workers, and cloud provisioning? Use the optional self-hosted SaaS edition:
  220. ```bash
  221. curl -fsSL https://raw.githubusercontent.com/gosom/google-maps-scraper/main/PROVISION | sh
  222. ```
  223. See [SaaS documentation](docs/saas.md) for deployment and operations details.
  224. There is also a [5-minute deployment walkthrough](https://gosom.dev/deploy-your-own-maps-scraping-api-in-5-minutes/) and a [YouTube video walkthrough](https://www.youtube.com/watch?v=STG9mZw_nac).
  225. More examples are available in [Recipes](docs/recipes.md). If you need proxies for larger jobs, see [Proxy Sponsors](docs/proxies.md).
  226. ---
  227. ## AI Agent Skill
  228. The AI Agent Skill turns a natural-language lead request into a guided local scraping workflow. It is designed for nontechnical users as well as developers and keeps you in control of the search scope, proxy choice, and output.
  229. If you have not installed it yet:
  230. ```bash
  231. npx skills add gosom/google-maps-scraper
  232. ```
  233. Then just ask your agent:
  234. > Find me all dentists in Berlin with their emails
  235. The agent will:
  236. 1. Noninteractively check for the latest skill and Docker image.
  237. 2. Infer sensible search defaults and ask only for missing essentials.
  238. 3. Let you use your own proxy, continue without one, or review one randomly selected proxy sponsor.
  239. 4. Collect proxy credentials through a masked local terminal prompt instead of chat.
  240. 5. Run a small validation scrape before the full job.
  241. 6. Start and monitor the Docker crawl in the background.
  242. 7. Present the results with options to save, filter, analyze, or export.
  243. Proxy sponsor recommendations are clearly disclosed. One provider is selected per request: Webshare has a 50% chance, and the other active sponsors share the remaining 50% equally. If Webshare is inactive, active sponsors have equal chances; a sole active sponsor is always selected. Any discount or offer is displayed only when it is configured in the skill's [active sponsor registry](skills/google-maps-scraper/references/proxy-sponsors.json). You can always use another provider or no proxy.
  244. Requires Docker and Node.js on macOS, Linux, or Windows through WSL. See the [skill definition](skills/google-maps-scraper/SKILL.md) for details.
  245. ---
  246. ## Installation
  247. ### Using Docker (Recommended)
  248. The published Docker image uses Playwright:
  249. ```bash
  250. docker pull gosom/google-maps-scraper
  251. ```
  252. ### Build from Source
  253. Requirements: Go 1.27.4+
  254. ```bash
  255. git clone https://github.com/gosom/google-maps-scraper.git
  256. cd google-maps-scraper
  257. go mod download
  258. go build
  259. ./google-maps-scraper -input example-queries.txt -results results.csv -exit-on-inactivity 3m
  260. ```
  261. > First run downloads required browser libraries for Playwright.
  262. ---
  263. ## Features
  264. | Feature | Description |
  265. |---------|-------------|
  266. | **33+ Data Points** | Business name, address, phone, website, reviews, coordinates, and more |
  267. | **Email Extraction** | Optional crawling of business websites for email addresses |
  268. | **Multiple Output Formats** | CSV, JSON, PostgreSQL, S3, or custom plugins |
  269. | **Proxy Support** | SOCKS5, HTTP, HTTPS with authentication |
  270. | **Scalable Architecture** | Single machine to Kubernetes cluster |
  271. | **REST API** | Programmatic control for automation |
  272. | **Web UI** | User-friendly browser interface |
  273. | **Fast Mode (Beta)** | Quick extraction of up to 21 results per query |
  274. | **AWS Lambda** | Serverless execution support (experimental) |
  275. ---
  276. ## Extracted Data Points
  277. <details>
  278. <summary><strong>Click to expand all 36 data points</strong></summary>
  279. | # | Field | Description |
  280. |---|-------|-------------|
  281. | 1 | `input_id` | Internal identifier for the input query |
  282. | 2 | `link` | Direct URL to the Google Maps listing |
  283. | 3 | `title` | Business name |
  284. | 4 | `category` | Business type (e.g., Restaurant, Hotel) |
  285. | 5 | `address` | Street address |
  286. | 6 | `open_hours` | Operating hours |
  287. | 7 | `popular_times` | Visitor traffic patterns |
  288. | 8 | `website` | Official business website |
  289. | 9 | `phone` | Contact phone number |
  290. | 10 | `plus_code` | Location shortcode |
  291. | 11 | `review_count` | Total number of reviews |
  292. | 12 | `review_rating` | Average star rating |
  293. | 13 | `reviews_per_rating` | Breakdown by star rating |
  294. | 14 | `latitude` | GPS latitude |
  295. | 15 | `longitude` | GPS longitude |
  296. | 16 | `cid` | Google's unique Customer ID |
  297. | 17 | `status` | Business status (open/closed/temporary) |
  298. | 18 | `descriptions` | Business description |
  299. | 19 | `reviews_link` | Direct link to reviews |
  300. | 20 | `thumbnail` | Thumbnail image URL |
  301. | 21 | `timezone` | Business timezone |
  302. | 22 | `price_range` | Price level ($, $$, $$$) |
  303. | 23 | `data_id` | Internal Google Maps identifier |
  304. | 24 | `street_view_url` | Street View URL |
  305. | 25 | `place_id` | Google's unique place id |
  306. | 26 | `images` | Associated image URLs |
  307. | 27 | `reservations` | Reservation booking link |
  308. | 28 | `order_online` | Online ordering link |
  309. | 29 | `menu` | Menu link |
  310. | 30 | `owner` | Owner-claimed status |
  311. | 31 | `complete_address` | Full formatted address |
  312. | 32 | `credit_cards_accepted` | Accepted credit card networks |
  313. | 33 | `about` | Additional business info |
  314. | 34 | `user_reviews` | Customer reviews (text, rating, timestamp) |
  315. | 35 | `user_reviews_extended` | Additional anonymously available reviews (requires `-extra-reviews`) |
  316. | 36 | `emails` | Extracted email addresses (requires `-email` flag) |
  317. | 37 | `review_collection` | Collection status, method, collected/expected counts, and stopping reason (with `-extra-reviews`) |
  318. With `-extra-reviews`, the scraper observes the anonymous browser's own review responses and uses visible review cards as a fallback. It does not sign in. Google may expose only a small sample; increasing scroll depth or retrying cannot guarantee the full reported review count.
  319. `review_collection.status` is `complete` when the collected count reaches the reported total, `limited` when Google explicitly serves a limited view, and `partial` for other stopping conditions. The object includes `method` (`browser`, `dom`, or `none`), `collected`, `expected`, and a `reason` when incomplete. The JSON field is omitted unless extra reviews were requested; the CSV column is appended after `emails`.
  320. Resuming an older CSV preserves its existing columns. Start a new output file to include `review_collection` if the older file does not have that column.
  321. </details>
  322. **Custom Input IDs:** Define your own IDs in the input file:
  323. ```
  324. Matsuhisa Athens #!#MyCustomID
  325. ```
  326. **Direct Google Maps URLs:** Input lines can be regular search queries or direct Google Maps URLs. Supported URL formats include:
  327. ```text
  328. https://www.google.com/maps/search/pizza
  329. https://www.google.com/maps/place/Empire+State+Building/@40.7484405,-73.9856632
  330. https://maps.google.com/maps?z=16&q=Empire+State+Building
  331. maps.app.goo.gl/abc123
  332. ```
  333. URLs on `google.com` subdomains must include a scheme (`http://` or `https://`) and a `/maps` path. Short `maps.app.goo.gl` links are also supported without a scheme.
  334. ---
  335. ## Configuration
  336. ### Command Line Options
  337. ```
  338. Usage: google-maps-scraper [options]
  339. Core Options:
  340. -input string Path to input file with queries (one per line)
  341. -results string Output file path (default: stdout)
  342. -json Output JSON instead of CSV
  343. -resume Resume a CLI file scrape by appending missing places
  344. -depth int Max scroll depth in results (default: 10)
  345. -c int Concurrency level (default: half of CPU cores)
  346. Email & Reviews:
  347. -email Extract emails from business websites
  348. -extra-reviews Collect anonymously available extra reviews and report status
  349. Location Settings:
  350. -lang string Language code, e.g., 'de' for German (default: "en")
  351. -geo string Coordinates for search, e.g., '37.7749,-122.4194'
  352. -zoom int Zoom level 0-21 (default: 15)
  353. -radius float Search radius in meters (default: 10000)
  354. -grid-bbox string Bounding box for grid scraping, format: "minLat,minLon,maxLat,maxLon"
  355. -grid-cell float Grid cell size in km (default: 1.0, used with -grid-bbox)
  356. -grid-strict Keep only places whose coordinates are inside -grid-bbox
  357. Web Server:
  358. -web Run web server mode
  359. -addr string Server address (default: ":8080")
  360. -data-folder Data folder for web runner (default: "webdata")
  361. Database:
  362. -dsn string PostgreSQL connection string
  363. -produce Produce seed jobs only (requires -dsn)
  364. Proxy:
  365. -proxies string Comma-separated proxy list
  366. Format: protocol://user:pass@host:port
  367. -proxies-file Path to a file containing one proxy URL per line
  368. Export:
  369. Advanced:
  370. -exit-on-inactivity duration Exit after inactivity (e.g., '5m')
  371. -fast-mode Quick mode with reduced data
  372. -debug Show browser window
  373. -writer string Custom writer plugin (format: 'dir:pluginName')
  374. -browser-pool-size int Number of browser processes to launch (default: 0, derived from -c and -pages-per-browser)
  375. -pages-per-browser int Max concurrent pages per browser process (default: 1)
  376. Notes:
  377. -grid-bbox requires a valid zoom level (1-21)
  378. -fast-mode cannot be used together with -grid-bbox
  379. ```
  380. Run `./google-maps-scraper -h` for the complete list.
  381. ### Resuming Interrupted CLI Runs
  382. Use `-resume` to continue a CLI file scrape after a crash or manual stop:
  383. ```bash
  384. ./google-maps-scraper \
  385. -resume \
  386. -input queries.txt \
  387. -results results.csv \
  388. -depth 10
  389. ```
  390. Resume mode reads the existing CSV or JSONL results file, appends new results, and skips places that were already written. It also writes completed input queries to `<results>.resume.json`; future resume runs use that sidecar file to skip fully completed queries.
  391. `-resume` is only supported with regular file output. It requires `-results` to be a file path and does not support `stdout`, `-writer`, or `-fast-mode`. Resume runs should use the same input and scrape options as the original run.
  392. ### Using Proxies
  393. For larger scraping jobs, proxies help avoid rate limiting. Here's how to configure them:
  394. ```bash
  395. ./google-maps-scraper \
  396. -input queries.txt \
  397. -results results.csv \
  398. -proxies 'socks5://user:pass@host:port,http://host2:port2' \
  399. -depth 1 -c 2
  400. ```
  401. **Supported protocols:** `socks5`, `socks5h`, `http`, `https`
  402. Current proxy sponsors are listed in [Proxy Sponsors](docs/proxies.md). Using those links helps fund project maintenance.
  403. ### Email Extraction
  404. Email extraction is **disabled by default**. When enabled, the scraper visits each business website to find email addresses.
  405. ```bash
  406. ./google-maps-scraper -input queries.txt -results results.csv -email
  407. ```
  408. > **Note:** Email extraction increases processing time significantly.
  409. ### Fast Mode
  410. Fast mode returns up to 21 results per query, ordered by distance. Useful for quick data collection with basic fields.
  411. ```bash
  412. ./google-maps-scraper \
  413. -input queries.txt \
  414. -results results.csv \
  415. -fast-mode \
  416. -zoom 15 \
  417. -radius 5000 \
  418. -geo '37.7749,-122.4194'
  419. ```
  420. > **Warning:** Fast mode is in Beta. You may experience blocking.
  421. ### Grid Scraping (BBox)
  422. Grid mode splits a bounding box into cells and runs one search per cell. This is useful when a single search does not return enough places.
  423. `queries.txt` example:
  424. ```text
  425. cafes in Peristeri, Greece
  426. ```
  427. Command example:
  428. ```bash
  429. ./google-maps-scraper \
  430. -input queries.txt \
  431. -results peristeri-cafes.csv \
  432. -grid-bbox "38.0077,23.6719,38.0257,23.6947" \
  433. -grid-cell 0.5 \
  434. -zoom 16 \
  435. -depth 1 \
  436. -c 4
  437. ```
  438. Notes:
  439. - `-grid-bbox` guides where searches are launched from, but results are not strictly clipped to the box.
  440. - Add `-grid-strict` to keep only places whose coordinates fall inside the box, including its edges. This applies to all output formats. Places outside the box are still fetched before filtering.
  441. - When resuming, keep the same bounding box and strict-mode setting; use a fresh results file if you change either.
  442. - For strict distance filtering, use `-fast-mode` with `-geo` + `-radius` (or post-filter by latitude/longitude).
  443. ---
  444. ### Browser Page Concurrency
  445. With the default `-pages-per-browser 1`, each concurrent job (`-c`) effectively uses its own browser process with a single page tab. This can be inefficient because browser pages can be CPU- and memory-heavy, and each browser process adds overhead.
  446. The `-pages-per-browser` flag lets you run multiple page tabs inside the same browser process, reducing overhead. Leave `-browser-pool-size` at `0` to derive the browser count from concurrency and pages per browser, or set it explicitly to cap the number of browser processes independently of concurrency.
  447. **How the flags interact:**
  448. | Flag | What it controls |
  449. |------|------------------|
  450. | `-c` | Total number of concurrent scrape jobs |
  451. | `-browser-pool-size` | Number of browser processes to launch (default: `0`, derived from `-c` and `-pages-per-browser`) |
  452. | `-pages-per-browser` | Number of page tabs per browser process (default: 1) |
  453. When `-pages-per-browser` is greater than 1, the scraper opens multiple tabs within each browser process and routes jobs through a shared page pool. This can significantly increase job throughput on the same hardware.
  454. **Example — 8 concurrent jobs across 2 browsers with 4 tabs each:**
  455. ```bash
  456. ./google-maps-scraper \
  457. -c 8 \
  458. -browser-pool-size 2 \
  459. -pages-per-browser 4 \
  460. -input queries.txt \
  461. -results results.csv \
  462. -depth 1
  463. ```
  464. **Tuning guidance:**
  465. - Start with `-c 4 -browser-pool-size 1 -pages-per-browser 4` for a 4:1 page-to-browser ratio.
  466. - Monitor CPU and RAM usage with `htop` or `docker stats`; browser resource use varies significantly by workload, Chromium version, and page count.
  467. - If memory is the bottleneck, keep `-browser-pool-size` low and reduce `-c` or `-pages-per-browser`.
  468. - If CPU is the bottleneck, reduce the total number of active pages by lowering `-c` or `-pages-per-browser`.
  469. - The product `-browser-pool-size × -pages-per-browser` should roughly equal or exceed `-c` to keep all jobs busy.
  470. - Setting an explicit `-browser-pool-size` is most useful in containerized environments (Docker, Kubernetes) where you want predictable resource usage.
  471. ---
  472. ## Advanced Usage
  473. ### PostgreSQL Database Provider
  474. For distributed scraping across multiple machines:
  475. **1. Start PostgreSQL:**
  476. ```bash
  477. docker-compose -f docker-compose.dev.yaml up -d
  478. ```
  479. **2. Seed the jobs:**
  480. ```bash
  481. ./google-maps-scraper \
  482. -dsn "postgres://postgres:postgres@localhost:5432/postgres" \
  483. -produce \
  484. -input example-queries.txt \
  485. -lang en
  486. ```
  487. **3. Run scrapers (on multiple machines):**
  488. ```bash
  489. ./google-maps-scraper \
  490. -c 2 \
  491. -depth 1 \
  492. -dsn "postgres://postgres:postgres@localhost:5432/postgres"
  493. ```
  494. ### Kubernetes Deployment
  495. ```yaml
  496. apiVersion: apps/v1
  497. kind: Deployment
  498. metadata:
  499. name: google-maps-scraper
  500. spec:
  501. replicas: 3 # Adjust based on needs
  502. selector:
  503. matchLabels:
  504. app: google-maps-scraper
  505. template:
  506. metadata:
  507. labels:
  508. app: google-maps-scraper
  509. spec:
  510. containers:
  511. - name: google-maps-scraper
  512. image: gosom/google-maps-scraper:latest
  513. args: ["-c", "1", "-depth", "10", "-dsn", "postgres://user:pass@host:5432/db"]
  514. resources:
  515. requests:
  516. memory: "512Mi"
  517. cpu: "500m"
  518. ```
  519. > **Note:** The headless browser requires significant CPU/memory resources.
  520. ### Custom Writer Plugins
  521. Create custom output handlers using Go plugins:
  522. **1. Write the plugin** (see `examples/plugins/example_writer.go`)
  523. **2. Build:**
  524. ```bash
  525. go build -buildmode=plugin -tags=plugin -o myplugin.so myplugin.go
  526. ```
  527. **3. Run:**
  528. ```bash
  529. ./google-maps-scraper -writer ~/plugins:MyWriter -input queries.txt
  530. ```
  531. ---
  532. ## Performance
  533. **Expected throughput:** ~120 places/minute (with `-c 8 -depth 1`)
  534. | Keywords | Results/Keyword | Total Jobs | Estimated Time |
  535. |----------|-----------------|------------|----------------|
  536. | 100 | 16 | 1,600 | ~13 minutes |
  537. | 1,000 | 16 | 16,000 | ~2.5 hours |
  538. | 10,000 | 16 | 160,000 | ~22 hours |
  539. For large-scale scraping, use the PostgreSQL provider with Kubernetes.
  540. ### Telemetry
  541. Anonymous usage statistics are collected for improvement purposes. Opt out:
  542. ```bash
  543. export DISABLE_TELEMETRY=1
  544. ```
  545. ---
  546. ## Support the Project
  547. This project is free and open source. Stars, sponsorships, and sponsor referrals help fund maintenance.
  548. - Star the repository: [github.com/gosom/google-maps-scraper](https://github.com/gosom/google-maps-scraper)
  549. - Sponsor development: [GitHub Sponsors](https://github.com/sponsors/gosom)
  550. - Paid setup and API integration: [Book a call with the maintainer](https://www.cal.eu/g-k-lsoknt/gosom)
  551. - Need proxies? See [Proxy Sponsors](docs/proxies.md)
  552. - Deploying the self-hosted platform? See [SaaS deployment options](docs/saas.md)
  553. ---
  554. ## Community
  555. [![Discord](https://img.shields.io/badge/Discord-Join%20Our%20Server-7289DA?logo=discord&logoColor=white&style=for-the-badge)](https://discord.gg/fpaAVhNCCu)
  556. Join our Discord to:
  557. - Get help with setup and configuration
  558. - Share your use cases and success stories
  559. - Request features and report bugs
  560. - Connect with other users
  561. ---
  562. ## Contributing
  563. Contributions are welcome! Please:
  564. 1. Open an issue to discuss your idea
  565. 2. Fork the repository
  566. 3. Create a pull request
  567. See [AGENTS.md](AGENTS.md) for development guidelines.
  568. ---
  569. ## References
  570. - [How to Extract Data from Google Maps Using Golang](https://blog.gkomninos.com/how-to-extract-data-from-google-maps-using-golang)
  571. - [Distributed Google Maps Scraping](https://blog.gkomninos.com/distributed-google-maps-scraping)
  572. - [Deploy your own Maps scraping API in 5 minutes (includes video walkthrough)](https://gosom.dev/deploy-your-own-maps-scraping-api-in-5-minutes/)
  573. - [Video walkthrough (YouTube)](https://www.youtube.com/watch?v=STG9mZw_nac)
  574. - [scrapemate](https://github.com/gosom/scrapemate) - The underlying web crawling framework
  575. - [omkarcloud/google-maps-scraper](https://github.com/omkarcloud/google-maps-scraper) - Inspiration for JS data extraction
  576. ---
  577. ## License
  578. This project is licensed under the [MIT License](LICENSE).
  579. ---
  580. ## Star History
  581. <a href="https://www.star-history.com/?repos=gosom%2Fgoogle-maps-scraper&type=date&legend=top-left">
  582. <picture>
  583. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=gosom/google-maps-scraper&type=date&theme=dark&legend=top-left&sealed_token=Yr-6oa5yTlmDhKxqKB2hmq1BmacSXwVftAnHxVCYmn7c4GiYaBtbLGZIZufr71ZfE4jkDpnt75NiAK4fBXP9FPuusVh3L0ofCigowkfI_OxlShvmkys9esorL4X5DRFPCCEVfdt0P0PV-52Qq61fiZSVkUKRjWYT8lhKUkwcXeCH8H8aIbc9NiLItTXz" />
  584. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=gosom/google-maps-scraper&type=date&legend=top-left&sealed_token=Yr-6oa5yTlmDhKxqKB2hmq1BmacSXwVftAnHxVCYmn7c4GiYaBtbLGZIZufr71ZfE4jkDpnt75NiAK4fBXP9FPuusVh3L0ofCigowkfI_OxlShvmkys9esorL4X5DRFPCCEVfdt0P0PV-52Qq61fiZSVkUKRjWYT8lhKUkwcXeCH8H8aIbc9NiLItTXz" />
  585. <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=gosom/google-maps-scraper&type=date&legend=top-left&sealed_token=Yr-6oa5yTlmDhKxqKB2hmq1BmacSXwVftAnHxVCYmn7c4GiYaBtbLGZIZufr71ZfE4jkDpnt75NiAK4fBXP9FPuusVh3L0ofCigowkfI_OxlShvmkys9esorL4X5DRFPCCEVfdt0P0PV-52Qq61fiZSVkUKRjWYT8lhKUkwcXeCH8H8aIbc9NiLItTXz" />
  586. </picture>
  587. </a>
  588. ---
  589. ## Legal Notice
  590. Please use this scraper responsibly and in accordance with applicable laws and regulations. Unauthorized scraping may violate terms of service.
  591. ---
  592. <p align="center">
  593. <sub>Banner generated using OpenAI's DALL-E</sub>
  594. </p>
  595. <p align="center">
  596. <sub><strong>SPONSOR DISCLAIMER:</strong> Sponsor listings and referral links do not constitute an endorsement. This project and its maintainers are not responsible for sponsors' products, services, representations, conduct, or any resulting loss or damage. Users engage with sponsors at their own risk.</sub>
  597. </p>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.