The hardest part of trying to scrape Google Maps is not parsing. It is that the same search returns different businesses in a different order depending on where the request appears to come from. A list of “coffee shops” collected from a server in Virginia is not what a user in Austin or Munich sees. This guide shows how to build a small, well-behaved Google Maps scraper in Python with Playwright and city-level proxies, how to extract names, ratings, review counts, categories and addresses without relying on brittle class names, and when the official Places API (New) is the better tool.
The short version
Check the official Places API (New) first; for many business uses it is the right tool. If you still need to see Google Maps the way a local user does, for example for local-rank research on public listings, run Playwright through a city-targeted, sticky residential proxy and match the browser’s locale, timezone and geolocation to that city. Open a documented Maps search URL, scroll the results feed, read cards through role and aria-label locators, dedupe by place ID or a normalized URL, and keep concurrency and request rates low.
Read this before you write any code. Google’s terms restrict automated access to Google Maps, and the Google Maps additional terms prohibit mass downloading content or using it to build a substitute business-listings database. For most business uses, the official Places API (New) Text Search is the correct tool. The browser techniques here are for public listing data at small scale, such as checking local visibility in a few cities. Respect Google’s terms and local law, do not collect personal data about reviewers or anyone else, and get legal advice for your case. This is not legal advice.
Key takeaways
- Maps results depend on the searcher’s apparent location, so the exit IP must be in the city you study.
- Proxy city, timezone, locale and geolocation should all describe the same place.
- Use one sticky session per city so a scroll session never changes IP midway.
- Locate elements by role, aria-label and URL pattern, store raw card text, and expect the layout to change.
- One search returns a limited list; split areas, then dedupe by place ID.
- For structured business data at volume, use the Places API (New) and its storage rules.
Terms, the API and What to Collect
Decide the access method before the codeThree documents matter. Google’s general Terms of Service forbid automated access that violates machine-readable instructions such as robots.txt. The Google Maps additional terms go further: no mass downloading, no bulk feeds and no using Maps content to create a business-listings database, mailing list or telemarketing list for a substitute service. And if you use the API, the Google Maps Platform terms and Places API policies restrict caching and storing content. The one exception is the place ID, which may be stored indefinitely.
At the time of writing, Google’s robots.txt allows generic crawlers to fetch /maps/search/ and /maps/place/ paths. That is not a license. It only means robots.txt is not the rule that blocks you; the Maps terms still apply.
So scope the job first:
- Purpose. Checking how a client ranks for “plumber” in five cities is research. Copying every listing in a country into a lead database is what the terms prohibit.
- Fields. Name, category, address, rating and review count are public listing attributes. Reviewer names, profiles and photos of people are personal data. Leave them out.
- Volume. Scale alone does not grant permission under Google Maps terms.
- Alternatives. If the Places API covers the need, use it (example below).
Why Google Maps Results Change with Location
Local ranking is personal by designGoogle’s Business Profile help page on local ranking says local results are based mainly on relevance, distance and prominence. Distance is how far a business is from the searcher, and Google notes that when a user does not share their location, it uses what it knows about it. For a scraper, “what it knows” usually starts with the IP address.
Several inputs therefore shape the list you get back:
| Signal | What it changes | How to control it |
|---|---|---|
| Query text | Relevance and the search area | Name the city or neighborhood in the query |
| Map viewport | Which area is searched and listed | Use one consistent window size and URL format |
| IP location | Distance for “near me” style intent | City-targeted proxy exit |
| Browser geolocation | Location when the page asks for it | Context geolocation set to the same city |
| Language and region | UI language, labels, formats | Context locale and timezone_id |
Even the API is affected: the Text Search (New) docs state that without locationBias or locationRestriction, results are biased by the caller’s IP address.
This is why city-level targeting matters. A country-level proxy can exit in any city, so two runs of one job can describe two different markets. Pin the exit to the city you measure, keep it for the whole session, and make the browser agree. A Munich IP with an America/New_York timezone and an en-US locale is a contradiction that adds noise and looks automated.
For local data, the proxy is not just a way to spread requests. It defines whose view of the map you are recording.
Architecture of a Google Maps Scraper
A grid of jobs, one browser context eachThe unit of work is one query in one city. Each job gets its own browser context configured for that city and produces a ranked list of listings, stored with the city and query it came from.
queries x cities ("coffee shops", Austin), ...
|
v
job queue --(concurrency = 1-2)--> worker
|
new browser context per job:
proxy (city, sticky) + locale + timezone + geolocation
|
v
Maps search URL -> consent check
|
v
scroll results feed -> extract raw cards
|
v
parse -> dedupe by place key -> SQLite
(places table + sightings with city, query, position)
Keep two kinds of record. A place is the business, stored once. A sighting says a place appeared at position N for a query in a city at a given time. Rank tracking and city comparison come from sightings; a deduplicated list of places alone loses the location-specific view.
If you are new to driving a real browser, our introduction to headless browsers and how to use them with a proxy covers the basics. For the wider Python tooling picture, see Python web scraping with residential proxies.
Setup: Playwright and City-Targeted Proxies
One sticky username per cityInstall Playwright and a Chromium build:
pip install playwright
playwright install chromium
# One sticky, city-targeted username per city, copied from Connection Builder
export PE_PASSWORD='your-proxy-password'
export PE_USER_AUSTIN='username-copied-from-connection-builder'
# Confirm the exit IP before involving a browser
curl -x "http://${PE_USER_AUSTIN}:${PE_PASSWORD}@v2.proxyempire.io:5000" \
https://api.ipify.org
In the ProxyEmpire dashboard, open Proxy Manager → Connection Builder, pick residential proxies, set the country and city, and choose a sticky session (Same IP). Targeting and session settings are encoded in the proxy username, so copy it exactly as the Connection Builder shows it rather than assembling it by hand. Repeat per city and keep the usernames in environment variables. For several sessions per city, export a proxy list in host:port:user:pass format.
Run the curl test for each city before starting a browser (more flags in our guide to curl with a proxy).
Two settings matter for Playwright. Use the http:// gateway URL: Chromium does not support username and password authentication for SOCKS5 proxies, and Playwright rejects it (see SOCKS vs HTTP proxies). And use sticky sessions: the results list loads more data as you scroll, and an IP change midway turns one session into two unrelated visitors. Sticky vs rotating proxies explains when each mode fits.
Describe each city once, with everything the browser needs to match it:
# cities.py: one entry per target city. The proxy username for each city
# is copied from ProxyEmpire Proxy Manager -> Connection Builder with city
# targeting and a sticky session selected. Never hard-code the password.
import itertools
import os
from dataclasses import dataclass
@dataclass(frozen=True)
class City:
key: str
label: str # what goes into the query text
lat: float
lng: float
timezone_id: str # IANA zone, must match the proxy city
locale: str # BCP 47 tag, drives Accept-Language and UI language
proxy_user_env: str # env var holding the Connection Builder username
CITIES = [
City("austin", "Austin, TX", 30.2672, -97.7431,
"America/Chicago", "en-US", "PE_USER_AUSTIN"),
City("manchester", "Manchester, UK", 53.4808, -2.2426,
"Europe/London", "en-GB", "PE_USER_MANCHESTER"),
City("munich", "Munich, Germany", 48.1351, 11.5820,
"Europe/Berlin", "de-DE", "PE_USER_MUNICH"),
]
QUERIES = ["coffee shops", "bike repair", "coworking space"]
def proxy_for(city: City) -> dict:
return {
"server": "http://v2.proxyempire.io:5000", # http://, not socks5://
"username": os.environ[city.proxy_user_env],
"password": os.environ["PE_PASSWORD"],
}
def jobs():
"""The query x city grid: every (query, city) pair is one job."""
for query, city in itertools.product(QUERIES, CITIES):
yield query, city
Opening a Search That Matches the Proxy City
Proxy, locale, timezone and geolocation agreeGoogle documents a Maps URLs format for opening a search: https://www.google.com/maps/search/?api=1&query=.... Prefer it over URLs copied from the address bar, and put the city in the query text so the intent does not rest on IP inference alone.
In Playwright, a context is a cheap, isolated browser profile with its own cookies and, optionally, its own proxy. It is also where you set the locale (which drives navigator.language and the Accept-Language header), timezone and geolocation.
import asyncio
from urllib.parse import quote_plus
from playwright.async_api import async_playwright
from cities import CITIES, proxy_for
def search_url(query: str, city_label: str) -> str:
# Documented Maps URLs format (api=1). Putting the city in the query
# text makes the intent explicit instead of relying on IP location alone.
q = quote_plus(f"{query} in {city_label}")
return f"https://www.google.com/maps/search/?api=1&query={q}"
async def open_search(browser, query, city):
context = await browser.new_context(
proxy=proxy_for(city),
locale=city.locale,
timezone_id=city.timezone_id,
geolocation={"latitude": city.lat, "longitude": city.lng,
"accuracy": 100},
permissions=["geolocation"],
viewport={"width": 1366, "height": 900},
)
page = await context.new_page()
await page.goto(search_url(query, city.label),
wait_until="domcontentloaded", timeout=60_000)
return context, page
async def main():
async with async_playwright() as p:
browser = await p.chromium.launch(headless=True)
context, page = await open_search(browser, "coffee shops", CITIES[0])
print(page.url)
await page.screenshot(path="austin.png")
await context.close()
await browser.close()
if __name__ == "__main__":
asyncio.run(main())
The geolocation permission only matters if the page asks for the device location; when it does, the answer matches the IP. A fixed viewport keeps the results panel, and so scrolling, predictable.
Run it once and check the screenshot: a results list for the right city, in the expected language. Fix error pages, consent screens or wrong-city results before going further.
Consent Pages in EU Locales
Detect it, reject non-essential, fail loudlyVisitors who appear to be in the EEA, the UK and some other regions may first get a cookie-consent page, often on a consent. subdomain, or a consent dialog. A fresh context has no consent cookie, so expect it on every job there.
Handle it generically: detect the consent step, find a reject-style button by role and accessible name, click it, continue. Decline non-essential cookies. On an unexpected layout, take a screenshot and stop.
import re
# Reject-style button labels for the locales you run. These are examples:
# open the consent page once per locale and copy the exact wording you see.
REJECT_LABELS = re.compile(
r"^(reject all|alle ablehnen|tout refuser|rechazar todo|rifiuta tutto)$",
re.IGNORECASE,
)
async def handle_consent(page) -> bool:
"""If Google shows a consent interstitial, choose the reject option."""
if "consent." not in page.url:
# Some locales show an in-page dialog instead of a redirect.
dialog = page.get_by_role("dialog")
if not await dialog.count():
return False
button = page.get_by_role("button", name=REJECT_LABELS).first
try:
await button.click(timeout=5_000)
except Exception:
# Unknown layout: save evidence and fail loudly, do not guess.
await page.screenshot(path="consent-unknown.png", full_page=True)
raise RuntimeError(f"Unhandled consent page at {page.url}")
await page.wait_for_load_state("domcontentloaded")
return True
The label list is deliberately explicit. Open the consent page once per locale through the matching proxy and copy the exact button text; a broad regex can click the wrong control.
Scrolling and Extracting Listings
Roles, aria-labels and URL patterns, not class namesMaps has no page numbers: the results panel loads more entries as you scroll. Its CSS class names are generated and change often, while accessibility attributes tend to last longer because screen readers depend on them. At the time of writing, the results list is exposed with the feed role, and each listing contains a link whose URL contains /maps/place/.
Treat every locator here as a starting point. Google’s DOM changes without notice. Check each locator against the live page (see inspecting the page) before you depend on it.
Scroll the feed until it stops growing
Scroll the feed element, not the window, count place links after each step, and stop at your cap or when the count stops growing for a few rounds. A fixed number of scrolls would cut the list short whenever responses are slow.
import asyncio
import random
# Links whose href points at a place page. This keys on Google's URL
# pattern (/maps/place/), not on generated class names, so it survives
# most layout changes. Verify it against the live page before a run.
PLACE_LINKS = 'a[href*="/maps/place/"]'
async def scroll_results(page, max_results=120, max_idle_rounds=4):
# The results list is exposed to assistive tech as a feed. If the
# query matched a single place, Maps can open that place directly
# and there is no feed at all; the caller handles that case.
feed = page.get_by_role("feed").first
try:
await feed.wait_for(timeout=15_000)
except Exception:
return None
idle, last = 0, 0
while idle < max_idle_rounds:
count = await feed.locator(PLACE_LINKS).count()
if count >= max_results:
break
idle = idle + 1 if count == last else 0
last = count
# Scroll the feed element itself, not the window.
await feed.evaluate("el => el.scrollBy(0, el.clientHeight)")
await asyncio.sleep(random.uniform(1.5, 3.5))
return feed
If a query matches one place exactly, Maps may open that place’s panel and not show a list. The function returns None in that case and the caller logs it. Do not treat it as zero results.
Extract raw card data, then parse in Python
Pull the data in one evaluate_all call rather than hundreds of locator calls. The in-page JavaScript only returns raw strings: the link URL, the link’s aria-label (usually the business name), the card’s visible text, and aria-labels on img-role elements, where star ratings are commonly exposed. Parsing happens in Python, and the raw text is stored, so a layout change means re-parsing, not re-scraping.
import re
from scroll import PLACE_LINKS
# Runs in the page. For each place link, climb to the nearest container
# that holds the whole card and return raw strings only. Parsing happens
# in Python so you can re-parse stored raw text when the layout changes.
CARD_JS = """
links => links.map(a => {
const card = a.closest('[role="article"]') || a.parentElement;
return {
url: a.href,
name: a.getAttribute('aria-label') || '',
text: card ? card.innerText : '',
img_labels: card
? [...card.querySelectorAll('[role="img"][aria-label]')]
.map(e => e.getAttribute('aria-label'))
: [],
};
})
"""
RATING_RE = re.compile(r"(\d(?:[.,]\d)?)\s*(?:von 5\s*)?(?:star|Stern)", re.I)
COUNT_RE = re.compile(r"([\d.,\s]+)\s*(?:review|Rezension|Bewertung)", re.I)
PAREN_COUNT_RE = re.compile(r"\(([\d.,\s]+)\)")
def _to_int(raw: str):
digits = re.sub(r"[^\d]", "", raw)
return int(digits) if digits else None
def parse_card(raw: dict) -> dict:
labels = " | ".join(raw["img_labels"])
rating = RATING_RE.search(labels)
count = COUNT_RE.search(labels) or PAREN_COUNT_RE.search(raw["text"])
# Heuristic for an English UI: one card line usually reads
# "Category · Address". Treat both fields as best-effort.
category = address = None
for line in raw["text"].splitlines():
parts = [p.strip() for p in line.split("·") if p.strip()]
if len(parts) >= 2 and not RATING_RE.search(line):
category, address = parts[0], parts[-1]
break
return {
"url": raw["url"],
"name": raw["name"].strip() or None,
"rating": float(rating.group(1).replace(",", ".")) if rating else None,
"review_count": _to_int(count.group(1)) if count else None,
"category": category,
"address": address,
"raw_text": raw["text"],
}
async def extract_cards(feed) -> list:
raw_cards = await feed.locator(PLACE_LINKS).evaluate_all(CARD_JS)
return [parse_card(r) for r in raw_cards]
Rating and review count usually come from an aria-label and are the most reliable fields. Category and address come from visible text, a layout detail, so they are best-effort. The regexes handle common English and German rating/review labels, including decimal commas. Other locales may need their own tested patterns. Record the selected locale for every run because language changes can affect comparisons.
Fields that only appear on the place panel, such as opening hours, mean clicking each card, which multiplies requests per job. Check whether the Places API covers them first.
Inspecting the Page When Locators Break
Read the accessibility tree, not the CSSWhen extraction returns nothing or nonsense, the page has usually changed. Investigate in this order:
- Screenshot first. Many “broken locator” failures are really a consent page, an error page or a single-place panel.
- Accessibility snapshot.
await page.get_by_role("feed").first.aria_snapshot()prints the roles and names Playwright sees in the results list, the quickest way to find new anchors (aria snapshots docs). - Codegen.
playwright codegen --lang de-DE --timezone Europe/Berlin --geolocation "48.1351,11.5820" "https://www.google.com/maps/search/?api=1&query=cafe+in+Munich"opens a browser and suggests role-based locators as you hover over elements (codegen docs). - DevTools Accessibility pane. The Accessibility tab in Chrome’s Elements panel shows each element’s computed role and name.
- Compare with a local view. Browse through the same city proxy in normal Chrome. ProxyEmpire’s free Proxy Manager extension matches timezone and language to the proxy location and blocks WebRTC leaks.
Prefer role plus accessible name, then aria-label or href patterns, and visible text last. Avoid generated class names and positional paths.
Result Limits and Splitting Searches
One search is a sample, not a censusOne Google Maps search does not list every matching business in a city. The feed stops after a limited number of results, and the cutoff varies, so do not hard-code one. The API is explicit: Text Search (New) returns at most 20 results per page and 60 across all pages, a limit Google says may change.
- For rank research, the limit rarely matters. Local-visibility questions are about the top of the list, so capping each job at the first 20 to 60 results answers them and keeps requests low.
- For coverage of an area, use smaller areas (neighborhoods in the query, or smaller API rectangles) and narrower queries (“espresso bar” rather than “cafe”), then merge with deduplication.
Systematic coverage of every business in an area is exactly where the Places API, under its own terms, is the appropriate tool.
Deduplication and Storage
Stable keys, raw text, sightingsThe same business appears across queries, neighboring cells and repeat runs. Deduplicate on a stable key, never the name: chains have many branches with the same name.
The best key is Google’s place ID, which the Places policies let you store indefinitely and the API returns as id. Scraped place URLs often contain identifiers in an undocumented format; the code uses them when present and otherwise falls back to a normalized URL path plus address. To get canonical IDs for scraped rows, run a Text Search with a field mask of only places.id, which falls under the Essentials ID Only SKU.
import re
import sqlite3
from datetime import datetime, timezone
from urllib.parse import urlsplit
# Observed, undocumented fragments in Maps place URLs. Prefer them as
# keys when present; otherwise fall back to a normalized URL path.
FEATURE_ID_RE = re.compile(r"!1s(0x[0-9a-f]+:0x[0-9a-f]+)")
PLACE_ID_RE = re.compile(r"!19s(ChIJ[\w-]+)")
def place_key(url: str, address: str = None) -> str:
for rx in (PLACE_ID_RE, FEATURE_ID_RE):
m = rx.search(url)
if m:
return m.group(1)
# Drop the query string, the "@lat,lng,zoom" viewport and "data=" blob,
# which vary between visits. The name alone is not unique (chains), so
# add the address to the fallback key.
path = urlsplit(url).path
segments = [s for s in path.split("/")
if s and not s.startswith(("@", "data="))]
return "/".join(segments) + "|" + (address or "")
SCHEMA = """
CREATE TABLE IF NOT EXISTS places (
place_key TEXT PRIMARY KEY,
name TEXT,
category TEXT,
address TEXT,
url TEXT,
first_seen TEXT
);
CREATE TABLE IF NOT EXISTS sightings (
place_key TEXT,
city TEXT,
query TEXT,
position INTEGER,
rating REAL,
review_count INTEGER,
raw_text TEXT,
seen_at TEXT
);
"""
def open_db(path="maps.sqlite"):
db = sqlite3.connect(path)
db.executescript(SCHEMA)
return db
def save(db, city_key, query, cards):
now = datetime.now(timezone.utc).isoformat()
seen = set()
for card in cards:
key = place_key(card["url"], card["address"])
if key in seen: # duplicate inside one result list
continue
seen.add(key)
position = len(seen) # rank after in-list dedupe
db.execute(
"INSERT OR IGNORE INTO places VALUES (?, ?, ?, ?, ?, ?)",
(key, card["name"], card["category"], card["address"],
card["url"], now),
)
db.execute(
"INSERT INTO sightings VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
(key, city_key, query, position, card["rating"],
card["review_count"], card["raw_text"], now),
)
db.commit()
return len(seen)
SQLite is enough here. Positions are counted after in-list deduplication, so comparing ranks across cities or over time is a plain SQL query on sightings.
Running Politely
Low concurrency, long pauses, clean failuresA polite run is slow on purpose. It stays within the small-scale use you scoped, and it yields cleaner data with fewer interstitials and partial lists. The runner allows two concurrent jobs and pauses 20 to 45 seconds after each. These are conservative starting points, not measured thresholds.
import asyncio
import random
from playwright.async_api import async_playwright
from cities import CITIES, jobs
from consent import handle_consent
from extract import extract_cards
from navigate import open_search
from scroll import scroll_results
from store import open_db, save
CONCURRENCY = 2 # keep this low; Maps is not a bulk endpoint
async def run_job(browser, sem, city_locks, db, query, city):
# One job per city at a time (one sticky IP), and at most
# CONCURRENCY jobs overall.
async with city_locks[city.key], sem:
context, page = await open_search(browser, query, city)
try:
await handle_consent(page)
feed = await scroll_results(page, max_results=120)
if feed is None:
print(f"[{city.key}] {query!r}: no list (single place or block)")
await page.screenshot(path=f"debug-{city.key}.png")
return
cards = await extract_cards(feed)
n = save(db, city.key, query, cards)
print(f"[{city.key}] {query!r}: {n} places")
finally:
await context.close()
# Pause after every job, with jitter, before freeing the slot.
await asyncio.sleep(random.uniform(20, 45))
async def main():
db = open_db()
sem = asyncio.Semaphore(CONCURRENCY)
city_locks = {c.key: asyncio.Lock() for c in CITIES}
async with async_playwright() as p:
browser = await p.chromium.launch(headless=True)
await asyncio.gather(*(run_job(browser, sem, city_locks, db, q, c)
for q, c in jobs()))
await browser.close()
db.close()
if __name__ == "__main__":
asyncio.run(main())
Do not try to defeat CAPTCHAs or other bot checks. If a city keeps returning interstitials at this pace, the workload does not fit the browser approach; move it to the API. Our Playwright browser cluster design is worth reading for its session and failure-handling patterns, even though a Maps research project should never need that scale.
What About Google Maps Reviews?
Aggregates yes, reviewer identities no“Scrape Google Maps reviews” is a common request and the riskiest one. Review text comes attached to a reviewer name, profile and sometimes photos, all personal data. The Google Maps Platform terms explicitly forbid API customers from copying and saving user reviews, and data-protection law in many places applies to reviewer data however you obtain it.
Most analysis does not need individual reviews. Rating and review count per place, tracked over time in sightings, show reputation trends without personal data. For review text about your own business, use the Google Business Profile tools available to owners. The Places API’s reviews field returns at most five reviews per place, under the same display and storage rules. For text work such as sentiment analysis, keep the minimum and never store reviewer identities.
The Compliant Alternative: Places API (New)
Location as a parameter, not a proxyGoogle’s current product is Places API (New), and its Text Search endpoint is a POST to https://places.googleapis.com/v1/places:searchText. You send an API key in X-Goog-Api-Key and a field mask in X-Goog-FieldMask; there is no default field list, and omitting the mask is an error. Location is a request parameter, so no proxy is needed for city-specific results.
import os
import requests
URL = "https://places.googleapis.com/v1/places:searchText"
# Ask only for what you need. Field choice decides the billing SKU:
# rating and userRatingCount move the request to a higher tier.
FIELD_MASK = ",".join([
"places.id",
"places.displayName",
"places.formattedAddress",
"places.primaryType",
"places.rating",
"places.userRatingCount",
"places.googleMapsUri",
"nextPageToken",
])
def text_search(query, low, high, language="en", region="us"):
headers = {
"Content-Type": "application/json",
"X-Goog-Api-Key": os.environ["GOOGLE_MAPS_API_KEY"],
"X-Goog-FieldMask": FIELD_MASK,
}
body = {
"textQuery": query,
"languageCode": language,
"regionCode": region,
"pageSize": 20,
# Without a bias or restriction the API biases by the caller's IP.
"locationRestriction": {
"rectangle": {
"low": {"latitude": low[0], "longitude": low[1]},
"high": {"latitude": high[0], "longitude": high[1]},
}
},
}
while True:
resp = requests.post(URL, json=body, headers=headers, timeout=30)
resp.raise_for_status()
data = resp.json()
for place in data.get("places", []):
yield {
"place_id": place["id"],
"name": place.get("displayName", {}).get("text"),
"address": place.get("formattedAddress"),
"category": place.get("primaryType"),
"rating": place.get("rating"),
"review_count": place.get("userRatingCount"),
"maps_url": place.get("googleMapsUri"),
}
token = data.get("nextPageToken")
if not token:
break
# Every other parameter must stay identical between pages.
body["pageToken"] = token
if __name__ == "__main__":
# A rough box around central Austin, TX.
for row in text_search("coffee shops", (30.20, -97.82), (30.33, -97.68)):
print(row)
Some details from the Text Search (New) documentation that are easy to miss:
- The field mask sets the price.
places.idalone falls under an ID-only SKU. Display name, address, type andgoogleMapsUrifall under Pro.ratinganduserRatingCountmove the request to Enterprise. Check usage and billing before you run at volume. displayNameis an object withtextandlanguageCode, not a plain string.- Pagination uses
pageSize(1 to 20) andpageToken. Every other parameter must match the previous request, or the API returnsINVALID_ARGUMENT.maxResultCountis deprecated in favor ofpageSize. locationRestrictiontakes a rectangle and only applies to categorical queries such as “coffee shops”.locationBiasaccepts a circle or rectangle and may return results outside it.- Storage is restricted. You may store place IDs indefinitely (Google recommends refreshing IDs older than 12 months), but other Places content is subject to caching restrictions, and displayed data needs Google attribution.
The API gives Google’s structured view of each place, not the ranked list a user in a specific city sees in the consumer app. That narrow gap is where the browser approach adds something.
Places API vs Browser Scraping vs Third-Party Tools
Pick the tool for the question| Factor | Places API (New) | Browser scraping | Third-party tools |
|---|---|---|---|
| Terms | Supported, with storage rules | Restricted by Google’s terms | Same issue, outsourced |
| Location | Bias or restriction parameter | Proxy city + browser settings | Depends on the vendor |
| Data shape | Structured JSON, place IDs | Parsed UI text | Vendor schema |
| Stability | Versioned API | Breaks on UI changes | Vendor maintains it |
| Local rank as users see it | No | Yes | Sometimes |
| Cost model | Per request, by field SKU | Proxy traffic + compute | Per result or subscription |
| Best for | Apps, enrichment, volume | Small local-visibility research | One-off pulls without code |
Third-party scrapers are convenient, but they do not change the underlying terms, and you inherit their data-handling choices. Ask where their exit IPs are, and whether they collect reviewer data you do not want.
Troubleshooting
Symptom, likely cause, fix| Symptom | Likely cause | Fix |
|---|---|---|
| 407 from the proxy | Wrong username or password | Re-copy from Connection Builder; test with curl |
| “socks5 proxy authentication” error | SOCKS5 URL with credentials in Chromium | Use http://v2.proxyempire.io:5000 |
| Results for the wrong city | Country-level or rotating exit | City-targeted sticky username; city in query |
| Feed never appears | Consent page, single place, or error page | Check the screenshot; handle each case |
| List stops early | Slow loads, idle rounds too low | Raise max_idle_rounds; keep the session sticky |
| Empty rating fields | Locale changed the labels | Locale-specific regex, or re-parse raw_text |
| Repeated interstitials | Volume too high for this method | Slow down a lot, or move to the Places API |
For proxy-side status codes beyond 407, see our reference on proxy error codes.
Frequently Asked Questions
Google Maps scraping, in shortIs it legal to scrape Google Maps?
It depends on your jurisdiction, what you collect and how you use it, so get legal advice. Google’s terms restrict automated access, mass downloading and building substitute listings databases. For most business uses the Places API (New) is the right tool; keep browser scraping to small-scale research on public listing data, without personal data.
Why do I need city-level proxies to scrape Google Maps?
Local ranking weighs distance, and when a user shares no location Google infers it, starting with the IP. A country-level exit can land in any city. A city-targeted sticky session with matching locale, timezone and geolocation gives a consistent local view.
How many results can one Google Maps search return?
A limited number that varies in the web app. Text Search (New) documents up to 20 per page and 60 in total, subject to change. To cover an area, split it into smaller areas and narrower queries, then deduplicate.
What locators should a Google Maps scraper in Python use?
Role, aria-label and URL-pattern locators, such as the feed role and links containing /maps/place/, not generated class names. Verify them with aria snapshots, codegen or the DevTools Accessibility pane, and store raw card text for re-parsing.
Can I use SOCKS5 proxies with Playwright?
Not with username and password authentication in Chromium; Playwright rejects it. Use http://v2.proxyempire.io:5000 with the username from the Connection Builder.
Should I scrape Google Maps reviews?
Avoid collecting review text and reviewer identities: they are personal data, and the Maps Platform terms restrict saving reviews. Track aggregate rating and review count instead, and use Business Profile tools for reviews of your own business.
Get a consistent local view of every city you study
City-targeted residential proxies with sticky sessions, through one HTTP, HTTPS or SOCKS5 gateway. Build the username in the Connection Builder and test it in seconds.



