The open source Google Maps scraper from gosom is a Go program that drives a real browser, and it takes a proxy list in one flag. What surprises people is what happens to that list afterwards: the default mode does not rotate it per request, and it refuses any line without a login. Both behaviours come from the library it drives its fetchers with, and its own documentation says nothing about either. We read every setting on this page in v1.18.0, released on 13 September 2026, and in scrapemate v1.4.0, the version it pins.
If you came here for which kind of proxy suits Google Maps work in general, our Google Maps proxies page answers that. This one is about the tool.
Why would the scraper need a proxy?
Maps work means many similar requests to one company's service from one address. Sites answer a hosting address differently than a home connection. In our test of 19 September 2026, a residential address changed 4 of 13 answers. Google's own search page came back without results for both. That test used plain requests to other sites, so treat it as a sign, not a promise. The table per site is on our OpenClaw page.
The two ways in
# inline
./google-maps-scraper -input queries.txt -results out.csv \
-proxies "http://USERNAME:PASSWORD@GATEWAY_HOST:GATEWAY_PORT"
# from a file, one URL per line, # comments allowed
./google-maps-scraper -input queries.txt -results out.csv \
-proxies-file ~/.config/google-maps-scraper/proxies.txt
The two cannot be used together. Nothing else feeds proxies in: exporting http_proxy or https_proxy does not move this scraper, as one user found while debugging a run that produced no results.
Prefer the file. The project says so itself for agent use, because a file keeps credentials out of the command line and the process list, and its own helper writes that file with owner-only permissions. Two details differ between the forms. The file form trims each line, while the inline form keeps whatever sits around a comma. A space after a comma becomes part of the next address.
One more parsing rule matters. A line with no scheme is treated as SOCKS5, so 1.2.3.4:8080 becomes a SOCKS5 address rather than an HTTP one. Write the scheme yourself. Accepted: http, https, socks5, socks5h.
What each mode does with the list
| Default mode (browser) | -fast-mode (stealth fetcher) | |
|---|---|---|
| Address chosen | once per browser, in list order | on every request, in list order |
| Login on the line | required, the job fails without one | optional |
| How long an address is held | the life of a browser, up to 200 pages | one request |
| A line that cannot be parsed | stops the whole run | stops the whole run |
The default mode is the one you get unless you pass -fast-mode, and it is the mode that collects the richer data.
The login the default mode demands
For each entry in the list, the library starts a small proxy on your own machine and points the browser at that. The local one takes no login, and it adds yours on the way out. This is how an authenticated proxy works at all with a browser that cannot take a password on the command line.
The catch is that the local forwarder refuses to start when either field is empty: failed to start auth proxy for socks5://127.0.0.1:9050: username and password are required. A proxy that recognises you by your server address alone has no username, so the job fails before it begins. That report has been open since August 2025, and a second user hit the same with an HTTP proxy.
How many addresses does a run use?
In the default mode, one per browser. The scraper reuses a browser for up to 200 pages, and the number of browsers follows -c while -pages-per-browser stays at its default of one. So -c 4 puts four addresses in flight, whatever the list length, and entries beyond that wait until a browser is replaced. Raising -pages-per-browser lowers the number of browsers, and -browser-pool-size sets it outright.
Check your -c value before you blame the list. The flag's help text says the default is half your CPU cores, but the code takes the smaller of that and one, so an unset -c means a single browser and a single address.
That gives a simple rule: make the list at least as long as the concurrency. A longer list is not wasted, it just enters slowly. And no honest number exists for how many addresses a city needs before Google starts refusing, because that depends on the queries, the pace and the day.
Which proxy type fits this scraper?
Residential, for a service that judges the address. The shape the default mode wants is a handful of lines, each with its own identity, one per browser.
HProxy residential gateways fit that directly. On a Residential Premium plan, the plan API generates lines with a username and password included, up to 5,000 of them. Each line gets its own sticky session, so ten lines give ten stable identities. Put one line per list entry, and size the list against your -c setting. The username carries country targeting when you need a country. An allowed IP address needs no login at all, which suits -fast-mode but not the default mode, since the forwarder insists on both fields. A sticky address can still change early if its device leaves the network, so let the run retry. The residential proxies page lists the plans.
What breaks when the proxy is on
username and password are required. The line has no login and the default mode needs one.- The run stops on the first line it cannot read. A malformed entry ends the process rather than being skipped, so check the file before a long job.
- A line silently became SOCKS5. It had no scheme.
-proxies and -proxies-file cannot be used together. Pick one.- A space after a comma. The inline form keeps it, and the address no longer parses.
- 407 Proxy Authentication Required. The password is wrong, or the line belongs to another plan. Our 407 guide walks through it.
- The same address keeps coming up. In the default mode that is normal: a browser holds its address for up to 200 pages.
What this page does not cover
We read the scraper and its library as text and did not run them. We did not scrape Google Maps to find where it starts refusing, so this page gives no number of addresses per city. One thing to know while you read the project's own setup guide. Its proxy page is also its sponsor page, with paid listings, referral links and discount codes. The agent skill it ships presents three of those sellers at random when asked for a recommendation. The advice there is not wrong, but it is paid placement. The scraper moves quickly, so we will read these settings again by 19 October 2026.
Where to go from here
Google Maps proxies covers the choice of proxy for Maps work in general. Sticky vs rotating sessions explains the identity question behind the list length, and how websites detect proxies explains what a service looks at besides the address. HTTP vs SOCKS5 is worth a minute before you write a line without a scheme.
Sources
- The proxy inputs (internal/proxyconfig/proxyconfig.go), the flags (runner/runner.go), the fetcher choice per mode (runner/filerunner, runner/databaserunner, runner/webrunner), the proxy documentation page, the agent skill's proxy reference and the README. gosom/google-maps-scraper, release v1.18.0, 13 September 2026.
- The proxy parser (proxy.go), the round robin rotator (adapters/proxy/proxy.go), the local forwarder and the browser pool (adapters/fetchers/jshttp), and the stealth fetcher. gosom/scrapemate v1.4.0, the version the scraper pins.
- Issues 168, 101, 24, 93 and 305, and pull request 165. google-maps-scraper issue tracker, 2024 to 2026.
- Plans, IP whitelist and sticky sessions; errors; the proxy API. HProxy documentation, hproxy.com/docs, 19 September 2026.
- Our own test of 19 September 2026: plain GET requests to 13 sites and 3 controls, two runs from our server and two through a residential line of our own house plan. Raw output is kept in the research folder of our OpenClaw page.
