How to Scrape Google Maps with Python and City-Level Proxies (2026)

Developer guide · Last reviewed 20 October 2026 · 16 min read

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 code

Three 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 design

Google’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:

SignalWhat it changesHow to control it
Query textRelevance and the search areaName the city or neighborhood in the query
Map viewportWhich area is searched and listedUse one consistent window size and URL format
IP locationDistance for “near me” style intentCity-targeted proxy exit
Browser geolocationLocation when the page asks for itContext geolocation set to the same city
Language and regionUI language, labels, formatsContext 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 each

The 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.

Figure 1 — query × city grid feeding isolated browser contexts
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 city

Install Playwright and a Chromium build:

Example 1 — install and test the proxy (shell)
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:

Example 2 — cities.py: city profiles and the job grid (Python)
# 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 agree

Google 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.

Example 3 — navigate.py: a city-matched context opening a Maps search (Python)
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.

Detect it, reject non-essential, fail loudly

Visitors 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.

Example 4 — consent.py: generic consent handling (Python)
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 names

Maps 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.

Example 5 — scroll.py: scrolling the results feed (Python)
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.

Example 6 — extract.py: card extraction and best-effort parsing (Python)
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 CSS

When extraction returns nothing or nonsense, the page has usually changed. Investigate in this order:

  1. Screenshot first. Many “broken locator” failures are really a consent page, an error page or a single-place panel.
  2. 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).
  3. 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).
  4. DevTools Accessibility pane. The Accessibility tab in Chrome’s Elements panel shows each element’s computed role and name.
  5. 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 census

One 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, sightings

The 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.

Example 7 — store.py: place keys and a SQLite schema with sightings (Python)
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 failures

A 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.

Example 8 — run.py: a low-concurrency runner (Python)
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())
One city, one sessionEach context uses that city’s sticky username. A per-city lock keeps jobs for one city sequential, so two jobs never share an IP at once.
Pauses with jitterRandomized delays between scrolls and between jobs. Do not tighten them just because things are working.
Stop on anomaliesConsent loops, error pages or CAPTCHAs mean stop and investigate. Do not retry in a tight loop, and do not try to bypass them.
Cache your own resultsDo not re-run a job you completed today unless you need a fresh observation.

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 proxy

Google’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.

Example 9 — Places API (New) Text Search with pagination (Python, requests)
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.id alone falls under an ID-only SKU. Display name, address, type and googleMapsUri fall under Pro. rating and userRatingCount move the request to Enterprise. Check usage and billing before you run at volume.
  • displayName is an object with text and languageCode, not a plain string.
  • Pagination uses pageSize (1 to 20) and pageToken. Every other parameter must match the previous request, or the API returns INVALID_ARGUMENT. maxResultCount is deprecated in favor of pageSize.
  • locationRestriction takes a rectangle and only applies to categorical queries such as “coffee shops”. locationBias accepts 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
FactorPlaces API (New)Browser scrapingThird-party tools
TermsSupported, with storage rulesRestricted by Google’s termsSame issue, outsourced
LocationBias or restriction parameterProxy city + browser settingsDepends on the vendor
Data shapeStructured JSON, place IDsParsed UI textVendor schema
StabilityVersioned APIBreaks on UI changesVendor maintains it
Local rank as users see itNoYesSometimes
Cost modelPer request, by field SKUProxy traffic + computePer result or subscription
Best forApps, enrichment, volumeSmall local-visibility researchOne-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
SymptomLikely causeFix
407 from the proxyWrong username or passwordRe-copy from Connection Builder; test with curl
“socks5 proxy authentication” errorSOCKS5 URL with credentials in ChromiumUse http://v2.proxyempire.io:5000
Results for the wrong cityCountry-level or rotating exitCity-targeted sticky username; city in query
Feed never appearsConsent page, single place, or error pageCheck the screenshot; handle each case
List stops earlySlow loads, idle rounds too lowRaise max_idle_rounds; keep the session sticky
Empty rating fieldsLocale changed the labelsLocale-specific regex, or re-parse raw_text
Repeated interstitialsVolume too high for this methodSlow 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 short
Is 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.

ProxyEmpire proxy types and prices

ProxyEmpire

Proxies for data collection at scale.

Residential, mobile, ISP and datacenter proxies for scraping, ad verification, SEO monitoring and multi-account work. Choose from 30M+ ethically sourced residential IPs and 4M+ 4G/5G mobile IPs in 170+ countries, target by country, city, ZIP, ISP or carrier, and connect over HTTP(S) or SOCKS5 with 99.9% uptime. Try residential and mobile proxies for $1.97.

🏘️ Rotating Residential Proxies
  • 30M+ Premium Residential IPs
  •  170+ Countries
    Every residential IP in our network corresponds to an actual desktop device with a precise geographical location. Our residential proxies are fast and reliable, with 99.9% uptime, and work for a wide range of use cases. You can use country, region, city, ZIP, ISP, ASN and OS fingerprint targeting for our rotating residential proxies, at no extra charge.

See our Rotating Residential Proxies

📍 Static Residential Proxies
  • 24 Countries
    Buy a dedicated static residential IP from one of the 24 countries that we offer proxies in. Keep the same IP for a month or longer, while benefiting from their fast speed and stability.

See our Static Residential Proxies

📳 Rotating Mobile Proxies
  • 4M+ Premium Mobile IPs
  •  170+ Countries
    Access millions of clean mobile IPs with precise targeting by country, region, city, ZIP, mobile carrier, ASN and OS fingerprint, at no extra charge. Get far fewer IP blocks and CAPTCHAs with our 4G and 5G proxies.

See our Mobile Proxies

📱 Dedicated Mobile Proxies
  • 4 Countries
  • 50+ Locations
    Get your own dedicated mobile proxy in one of our supported locations, with unlimited bandwidth and unlimited IP changes on demand. A great choice when you need a small number of mobile IPs and a lot of proxy bandwidth.

See our 4G & 5G Proxies

🌐 Rotating Datacenter Proxies
  • 197,000+ IPs Premium IPs
  •  62 Countries
    On a budget and need to do some simple scraping tasks? Our datacenter proxies are the perfect fit! Get started with as little as $2

See our Datacenter Proxies

♾️ Unlimited Residential Proxies
  • 1M+ Daily Residential IPs
  • 85+ Countries
    Our unlimited residential proxies bill by connection speed, not gigabytes: 100 to 1000 Mbit with unlimited bandwidth, on daily, weekly or monthly plans. Ask us for a 1-hour trial at 50 Mbit before you pick a plan.

See our Unlimited Residential Proxies

proxy locations

30M+ rotating IPs

99.9% uptime - high speed

99.9% uptime.

dedicated support team

24/7 Dedicated Support.

fair price

Fair Pricing.

🏠 Residential Proxies Rotating / Static / Unlimited
📱 Mobile Proxies Rotating and Dedicated
🖥️ Datacenter Proxies Rotating
🌍 IP Pool 30M+ residential + 4M+ mobile IPs
📶 Uptime 99.9% · Live status
💳 Payment Card · PayPal · Crypto · Bank transfer
💬 Support 24/7 live chat · [email protected]