gmbscraper 0.1.0__tar.gz

gmbscraper-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.ty_cache/
+.python-version
+.DS_Store
+
+.coverage
+coverage.xml

gmbscraper-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Exprtec
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gmbscraper-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.5
+Name: gmbscraper
+Version: 0.1.0
+Summary: Playwright-based scraper for Google Maps / Google Business Profile listings and reviews
+Project-URL: Homepage, https://github.com/exprtec/gmbscraper-python
+Project-URL: Repository, https://github.com/exprtec/gmbscraper-python
+Project-URL: Issues, https://github.com/exprtec/gmbscraper-python/issues
+Author-email: Abdul Hadi Bharara <hadi@exprtec.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: gmb,google-maps,lead-generation,playwright,scraper
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: playwright>=1.49.0
+Description-Content-Type: text/markdown
+
+# gmbscraper
+
+A typed, importable Playwright scraper for Google Maps / Google Business Profile data:
+place search, place details, identity-based matching, review scraping, and
+parallel fan-out helpers.
+
+- Search Google Maps and scrape place details (name, category, address, phone,
+  website, rating, review count) without the official (paid, rate-limited)
+  Places API.
+- Adaptive quadrant search that recursively splits the map viewport to pull
+  results beyond Google's ~120-per-query cap.
+- Confidence-tiered identity matching (`phone_and_domain_match` >
+  `phone_match` > `domain_match` > `exact_name_match`) for matching a known
+  business/outlet against scraped candidates.
+- Review scraping with owner-response filtering, "see more" text expansion,
+  and multilingual review-tab detection.
+- Thread-based fan-out helpers (`chunk_items`, `run_chunked`) for running
+  multiple browser workers over a batch of items.
+
+> **Status:** pre-1.0 (`0.x`). Extracted from duplicated scraping code across
+> several internal projects; the API may still move before `1.0.0`.
+
+Using this from another project (agent or human)? Read [`skills/SKILL.md`](skills/SKILL.md) first — it covers the API surface, matching semantics, parallel fan-out, and how to add this as a dependency before PyPI publication.
+
+## Install
+
+Not yet published to PyPI. Add it as a `uv` path dependency — see [`skills/SKILL.md`](skills/SKILL.md#installing-in-a-consuming-project) for the exact `pyproject.toml` snippet — then:
+
+```bash
+uv run playwright install --with-deps chromium
+```
+
+## Quickstart
+
+```python
+from gmbscraper import BusinessIdentity, OutletIdentity, google_maps_browser
+
+with google_maps_browser() as maps:
+    # Search + adaptive pagination
+    links = maps.search_places_adaptive("plumbers", latitude=-33.87, longitude=151.21)
+
+    # Scrape a single place page
+    place = maps.scrape_place(links[0].maps_url, fallback_name=links[0].fallback_name)
+    print(place.name, place.rating, place.review_count)
+
+    # Find the Google Business Profile for a known business
+    match = maps.search_and_match(
+        OutletIdentity(name="Acme Plumbing", phone="0400 000 000", address="1 Main St, Sydney"),
+        BusinessIdentity(name="Acme Plumbing Pty Ltd", website="acmeplumbing.com.au"),
+    )
+    if match:
+        print(match.match_reason, match.place_id)
+
+    # Scrape reviews
+    reviews = maps.scrape_reviews(place.maps_url, max_reviews=50)
+```
+
+## Design notes
+
+- Every network-facing function swallows and skips broken selectors rather
+  than raising — a `PlaceProfile` is returned with whatever fields could be
+  read, since Google's DOM/markup changes without notice and partial data is
+  usually more useful than a hard failure. `scrape_reviews` is the exception:
+  it raises `GoogleReviewsUnavailableError` when Google serves a page with no
+  reviews UI at all (throttled/limited view, or the reviews tab never opens),
+  since a caller needs to distinguish "zero reviews" from "couldn't scrape."
+- There's no retry/backoff or proxy rotation built in. This is a DOM scraper,
+  not a hosted anti-block service — for scraping at a scale where blocking is
+  routine, a paid API (Outscraper, SerpApi, etc.) will be cheaper than
+  building that infrastructure yourself.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+```
+
+See [`skills/references/development.md`](skills/references/development.md) for what is and isn't covered by the test suite.
+
+## License
+
+MIT

gmbscraper-0.1.0/README.md

@@ -0,0 +1,85 @@
+# gmbscraper
+
+A typed, importable Playwright scraper for Google Maps / Google Business Profile data:
+place search, place details, identity-based matching, review scraping, and
+parallel fan-out helpers.
+
+- Search Google Maps and scrape place details (name, category, address, phone,
+  website, rating, review count) without the official (paid, rate-limited)
+  Places API.
+- Adaptive quadrant search that recursively splits the map viewport to pull
+  results beyond Google's ~120-per-query cap.
+- Confidence-tiered identity matching (`phone_and_domain_match` >
+  `phone_match` > `domain_match` > `exact_name_match`) for matching a known
+  business/outlet against scraped candidates.
+- Review scraping with owner-response filtering, "see more" text expansion,
+  and multilingual review-tab detection.
+- Thread-based fan-out helpers (`chunk_items`, `run_chunked`) for running
+  multiple browser workers over a batch of items.
+
+> **Status:** pre-1.0 (`0.x`). Extracted from duplicated scraping code across
+> several internal projects; the API may still move before `1.0.0`.
+
+Using this from another project (agent or human)? Read [`skills/SKILL.md`](skills/SKILL.md) first — it covers the API surface, matching semantics, parallel fan-out, and how to add this as a dependency before PyPI publication.
+
+## Install
+
+Not yet published to PyPI. Add it as a `uv` path dependency — see [`skills/SKILL.md`](skills/SKILL.md#installing-in-a-consuming-project) for the exact `pyproject.toml` snippet — then:
+
+```bash
+uv run playwright install --with-deps chromium
+```
+
+## Quickstart
+
+```python
+from gmbscraper import BusinessIdentity, OutletIdentity, google_maps_browser
+
+with google_maps_browser() as maps:
+    # Search + adaptive pagination
+    links = maps.search_places_adaptive("plumbers", latitude=-33.87, longitude=151.21)
+
+    # Scrape a single place page
+    place = maps.scrape_place(links[0].maps_url, fallback_name=links[0].fallback_name)
+    print(place.name, place.rating, place.review_count)
+
+    # Find the Google Business Profile for a known business
+    match = maps.search_and_match(
+        OutletIdentity(name="Acme Plumbing", phone="0400 000 000", address="1 Main St, Sydney"),
+        BusinessIdentity(name="Acme Plumbing Pty Ltd", website="acmeplumbing.com.au"),
+    )
+    if match:
+        print(match.match_reason, match.place_id)
+
+    # Scrape reviews
+    reviews = maps.scrape_reviews(place.maps_url, max_reviews=50)
+```
+
+## Design notes
+
+- Every network-facing function swallows and skips broken selectors rather
+  than raising — a `PlaceProfile` is returned with whatever fields could be
+  read, since Google's DOM/markup changes without notice and partial data is
+  usually more useful than a hard failure. `scrape_reviews` is the exception:
+  it raises `GoogleReviewsUnavailableError` when Google serves a page with no
+  reviews UI at all (throttled/limited view, or the reviews tab never opens),
+  since a caller needs to distinguish "zero reviews" from "couldn't scrape."
+- There's no retry/backoff or proxy rotation built in. This is a DOM scraper,
+  not a hosted anti-block service — for scraping at a scale where blocking is
+  routine, a paid API (Outscraper, SerpApi, etc.) will be cheaper than
+  building that infrastructure yourself.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+```
+
+See [`skills/references/development.md`](skills/references/development.md) for what is and isn't covered by the test suite.
+
+## License
+
+MIT

gmbscraper-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "gmbscraper"
+dynamic = ["version"]
+description = "Playwright-based scraper for Google Maps / Google Business Profile listings and reviews"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [
+    { name = "Abdul Hadi Bharara", email = "hadi@exprtec.com" },
+]
+keywords = ["google-maps", "gmb", "scraper", "playwright", "lead-generation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "playwright>=1.49.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/exprtec/gmbscraper-python"
+Repository = "https://github.com/exprtec/gmbscraper-python"
+Issues = "https://github.com/exprtec/gmbscraper-python/issues"
+
+[dependency-groups]
+dev = [
+    "ruff>=0.8",
+    "pytest>=8.0",
+]
+
+[tool.hatch.version]
+path = "src/gmbscraper/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/gmbscraper"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+ignore = ["E501"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["gmbscraper"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

gmbscraper-0.1.0/skills/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: gmbscraper
+description: Google Maps / Google Business Profile scraping via the `gmbscraper` package. Use when writing or reviewing code that searches Google Maps for places, scrapes a place's details, matches a known business/outlet against scraped candidates, or scrapes Google Maps reviews — in this repo or any project that depends on `gmbscraper` (e.g. reviewMonster, automation) — and when modifying gmbscraper's own scraper, matching, parsing, or review internals.
+---
+
+# gmbscraper
+
+Playwright-based scraper for Google Maps / Google Business Profile data. No official API key, no Places API quota — it drives a real (stealth-configured) Chromium browser against maps.google.com.
+
+## Quick Reference
+
+* Not on PyPI yet. Add it as a path (or git) dependency; see [Installing In A Consuming Project](#installing-in-a-consuming-project) below.
+* Everything flows through one object: `with google_maps_browser() as scraper:` yields a `GoogleMapsScraper`. Open one per thread if you fan out — see [Parallel Fan-out](references/parallel-fanout.md).
+* Search: `scraper.search_places_adaptive(query, latitude=.., longitude=..)` → `list[MapsSearchLink]`. Handles Google's ~120-results-per-query cap by splitting the map viewport automatically; safe to use even when you don't expect a saturated result set.
+* Place detail: `scraper.scrape_place(url, fallback_name=.., rank=..)` → `PlaceProfile`. Never raises — a selector miss just leaves that field blank, so check for empty strings, not exceptions.
+* Identity matching: `scraper.search_and_match(outlet, business)` → `PlaceProfile | None`, scored by phone/domain/name confidence. See [Matching](references/matching.md) before hand-rolling any similarity check.
+* Reviews: `scraper.scrape_reviews(maps_url)` → `list[MapsReview]`. Unlimited by default (`max_reviews=None`) — this is the one call that raises: `GoogleReviewsUnavailableError` when there's no reviews UI to open at all (blocked/limited view, or truly zero reviews).
+* Pass `locale=` to `google_maps_browser` matching the business's country (`"en-AU"`, `"en-NZ"`, ...) — it changes the address/phone formatting Google renders, which downstream parsing assumes.
+* No retry/backoff/proxy rotation is built in. This is a DOM scraper, not an anti-block service — see [Limits](#limits).
+* Package development (tests, lint, versioning): see [Development](references/development.md).
+
+## Search, Then Scrape
+
+```python
+from gmbscraper import google_maps_browser
+
+with google_maps_browser(locale="en-AU") as scraper:
+    links = scraper.search_places_adaptive("plumbers", latitude=-33.87, longitude=151.21)
+    for link in links:
+        place = scraper.scrape_place(link.maps_url, fallback_name=link.fallback_name)
+        print(place.name, place.rating, place.review_count)
+```
+
+`MapsSearchLink` has `maps_url`, `fallback_name`, and `search_rank` (`None` for links found via viewport-splitting rather than the original query). Dedup on `maps_url` — adaptive search can revisit the same place across overlapping quadrants.
+
+## Matching A Known Business
+
+Use this instead of writing your own name-similarity check — a plain fuzzy-name match produces false positives across chains and franchises. `search_and_match` needs at least one strong identity signal (phone, website, or an exact name) to return anything:
+
+```python
+from gmbscraper import BusinessIdentity, OutletIdentity, google_maps_browser
+
+with google_maps_browser() as scraper:
+    place = scraper.search_and_match(
+        OutletIdentity(name="Acme Plumbing", phone="0400 000 000", address="1 Main St, Sydney"),
+        BusinessIdentity(name="Acme Plumbing Pty Ltd", website="acmeplumbing.com.au"),
+    )
+    if place is not None:
+        print(place.match_reason)  # e.g. "phone_and_domain_match"
+```
+
+`place is None` means no candidate cleared the confidence bar — treat it as "no match," not as an error. Full tier breakdown and the standalone matching functions (for scoring your own candidate lists) are in [Matching](references/matching.md).
+
+## Scraping Reviews
+
+```python
+from gmbscraper import GoogleReviewsUnavailableError, google_maps_browser
+
+with google_maps_browser() as scraper:
+    try:
+        reviews = scraper.scrape_reviews(place.maps_url)
+    except GoogleReviewsUnavailableError:
+        reviews = []
+```
+
+Each `MapsReview` has `stars`, `username`, `text`, `date_text` (raw), `date` (resolved ISO string, `""` if unparseable), and `external_id` — call `.resolved_external_id()` instead of reading `.external_id` directly when you need a stable dedup key, since Google omits the id on some cards and the method falls back to a content hash.
+
+Pass `max_reviews=N` to stop early once you have enough; omitting it scrapes everything reachable (bounded by an idle-scroll cutoff, not a hard count).
+
+## Installing In A Consuming Project
+
+Not published to PyPI yet, so add it as a `uv` path source rather than a version pin. From a project two directories under `Documents/Work/<project>/<subdir>` (matches both `automation/worker` and `reviewMonster/backend`):
+
+```toml
+# pyproject.toml
+[project]
+dependencies = ["gmbscraper"]
+
+[tool.uv.sources]
+gmbscraper = { path = "../../../open-source/google-maps-python" }
+```
+
+Then `uv sync`. Adjust the relative path if your project sits at a different depth. `automation/worker/pyproject.toml` has a working example to copy from.
+
+If your project also needs Playwright's browser binary (it almost certainly does, since gmbscraper only declares the `playwright` Python package): `uv run playwright install --with-deps chromium`. Check whether the target repo's Dockerfile already runs this for its own Playwright usage before adding a second install step.
+
+## Limits
+
+* No retry/backoff and no proxy rotation. Google will eventually throttle a browser that scrapes hard enough from one IP; `is_limited_maps_view`-style detection exists only inside review scraping (surfaced as `GoogleReviewsUnavailableError`), not on the search/place-detail path — a throttled search silently returns thin/empty results rather than raising. If you need resilience against sustained blocking at scale, that's a paid API's job (Outscraper, SerpApi), not this package's.
+* Name/phone/domain normalization (`normalize_name`, `normalize_phone`, `normalize_domain`) is AU/NZ-tuned: it strips `pty`/`ltd`, AU/NZ multi-part TLD suffixes (`com.au`, `co.nz`, ...), and converts phone numbers to a local-format suffix assuming AU-style `+61` numbers. Matching businesses outside AU/NZ will work but with weaker name normalization.
+* `match_place` mutates the `PlaceProfile` it's given (sets `.match_reason`) rather than returning a copy — don't reuse the same `PlaceProfile` instance across multiple `match_place` calls against different identities, or the reason from an earlier failed match can leak into a later check.

gmbscraper-0.1.0/skills/references/development.md

@@ -0,0 +1,28 @@
+# Development
+
+Working on `gmbscraper` itself (not just consuming it).
+
+## Setup
+
+```bash
+uv sync
+uv run playwright install --with-deps chromium  # only needed to exercise real scraping, not for the unit tests below
+```
+
+## Validation
+
+```bash
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+```
+
+The test suite covers `parsing.py`, `_matching.py`, and `_parallel.py` only — everything that touches a real `Page`/`BrowserContext` (`_page.py`, `_places.py`, `_adaptive_search.py`, `_reviews.py`, `_scraper.py`) has no automated coverage and is verified by running it against live Google Maps. Keep new logic in the parsing/matching/parallel modules pure and unit-testable where possible; push anything that must touch a `page` object into the browser-facing modules, which stay manually verified.
+
+## Versioning
+
+`src/gmbscraper/_version.py` is the single source of truth (`__version__ = "x.y.z"`), read by both the package's own `__init__.py` and `pyproject.toml`'s `[tool.hatch.version]`. Bump it there — nowhere else.
+
+## Not Yet Published
+
+There's no PyPI release and no publish workflow yet. Consuming projects use a `tool.uv.sources` path dependency (see the main [SKILL.md](../SKILL.md#installing-in-a-consuming-project)). If this gets published later, mirror `instantly-python-sdk`'s pattern (`instantlyai` on PyPI, `scripts/release.sh`, version-pinned dependency in consumers) rather than inventing a new one.

gmbscraper-0.1.0/skills/references/matching.md

@@ -0,0 +1,55 @@
+# Matching
+
+How `search_and_match` decides a scraped Google Maps place is "the same business" as one of your own records, and how to use the scoring functions directly if you're matching against a candidate list you already have (e.g. from your own `search_places_adaptive` results) instead of letting `search_and_match` search for you.
+
+## The Two Identity Types
+
+* `BusinessIdentity(name, website=None)` — the business as your system knows it (a company/provider record). One `BusinessIdentity` typically covers many outlets.
+* `OutletIdentity(name, phone=None, address=None)` — the specific location being matched. `name` here is usually the outlet/branch name, not the parent business name — pass the parent name too (as `BusinessIdentity.name`) since Google Business Profile listings are sometimes titled with the outlet name and sometimes the parent brand.
+
+Both are plain dataclasses — construct them fresh per match attempt, don't share instances.
+
+## Confidence Tiers
+
+`match_place(place, outlet, business)` checks, in order of strength:
+
+1. `phone_and_domain_match` — normalized phone AND normalized domain both match.
+2. `phone_match` — phone matches, domain doesn't (or business has no website on record).
+3. `domain_match` — domain matches, phone doesn't.
+4. `exact_name_match` — no phone/domain signal, but the normalized place name exactly equals the normalized outlet or business name.
+
+If none of the four fire, `match_place` returns `None` — there is no "weak match" tier below `exact_name_match`. A fuzzy/partial name match is not enough on its own; that's deliberate, since a partial-name-only match rate is where false positives across chains and franchises come from.
+
+`is_definitive_match(place)` is `True` for any of the four reasons — used internally by `search_and_match` to stop scraping further candidates as soon as it finds one, rather than checking every result on the page.
+
+## Gate Before You Scrape
+
+`has_match_key(outlet, business)` tells you up front whether there's *any* chance of a match — phone, website, or a name to compare. If it's `False`, don't bother searching/scraping candidates at all; there's nothing to match against and you'll only burn browser time for a guaranteed `None`. `search_and_match` does not call this gate itself (it assumes you've already decided the record is worth attempting), so callers doing bulk enrichment should check it themselves before queuing a browser task:
+
+```python
+from gmbscraper import BusinessIdentity, OutletIdentity, has_match_key
+
+if not has_match_key(outlet, business):
+    continue  # nothing to match on — skip without touching the browser
+```
+
+## Scoring Your Own Candidate List
+
+If you already have a list of scraped `PlaceProfile` candidates (e.g. you called `scrape_place` yourself in a loop) and just need to pick the best one, skip `search_and_match` and use the scoring functions directly:
+
+```python
+from gmbscraper import match_place, pick_best_match
+
+scored = [
+    matched for place in candidates if (matched := match_place(place, outlet, business)) is not None
+]
+best = pick_best_match(scored)  # None if scored is empty
+```
+
+`pick_best_match` sorts by confidence tier first, then by `PlaceProfile.rank` (position in your candidate list) as a tiebreaker — pass the `rank` you scraped each candidate at (`scrape_place(url, rank=i)`) so ties resolve toward earlier/more relevant search results.
+
+## Normalization Gotchas
+
+* `normalize_phone` assumes AU-style numbers: it strips a `+61`/`0011 61` prefix down to a local `0`-leading number, then compares the last 9 digits. Phone matching against non-AU/NZ numbers may under-match.
+* `normalize_domain` unwraps Google's `google.com/url?q=...` redirect links before comparing, and treats a fixed list of AU/NZ multi-part suffixes (`com.au`, `co.nz`, `org.au`, ...) as part of the registrable domain rather than stripping them like an ordinary two-part TLD.
+* `normalize_name` strips legal suffixes (`pty`, `ltd`, `inc`, ...) and a fixed stop-word list (`the`, `group`, `services`, `co`, ...) before comparing — two differently-branded businesses that both reduce to the same stripped name (e.g. two outlets both named "The Community Group") would collide on `exact_name_match`. Combine name matching with phone/domain whenever you have them; don't rely on name alone for anything you can't afford to get wrong.

gmbscraper-0.1.0/skills/references/parallel-fanout.md

@@ -0,0 +1,46 @@
+# Parallel Fan-out
+
+`chunk_items` and `run_chunked` split a batch of work across threads, each running its own browser. Reach for these when you have more than a handful of places/leads/reviews to process in one job and want to run several browsers concurrently instead of one after another.
+
+## One Browser Per Thread — Not One Shared Browser
+
+Playwright's *sync* API (what `google_maps_browser` uses) is not thread-safe. Each worker thread must open its own `google_maps_browser()` context — never pass a single `GoogleMapsScraper` into multiple threads. `run_chunked` hands each worker a *chunk of items*, not a shared scraper, specifically so each worker opens its own browser internally:
+
+```python
+from gmbscraper import google_maps_browser, run_chunked
+
+
+def worker(chunk: list[MyItem], worker_id: int) -> MyStats:
+    stats = MyStats()
+    with google_maps_browser() as scraper:  # one browser per worker thread
+        for item in chunk:
+            ...  # scraper.scrape_place(...) / .search_and_match(...) / .scrape_reviews(...)
+    return stats
+
+
+final = run_chunked(items, workers=4, empty_stats=MyStats, worker=worker)
+```
+
+If `workers >= len(items)` (or `workers=1`), `run_chunked` runs inline on the calling thread without spawning an executor at all — safe to always pass a `--workers` CLI flag through even when it's 1.
+
+## Additive Stats
+
+`worker` must return an object satisfying the `AdditiveStats` protocol — just an `add(self, other) -> None` method that merges another instance's counts into itself. `run_chunked` calls `empty_stats()` once up front and `.add()` once per completed worker:
+
+```python
+from dataclasses import dataclass
+
+
+@dataclass
+class MyStats:
+    matched: int = 0
+    errors: int = 0
+
+    def add(self, other: "MyStats") -> None:
+        self.matched += other.matched
+        self.errors += other.errors
+```
+
+## Chunking Only
+
+If you want the even split without the threading (e.g. you're managing your own executor, or persisting through a DB session per chunk the way `automation`'s NDIS jobs do), call `chunk_items(items, workers)` directly — it returns `workers` lists (fewer if `len(items) < workers`), round-robin distributed so no chunk is more than one item larger than another.

gmbscraper-0.1.0/src/gmbscraper/__init__.py

@@ -0,0 +1,39 @@
+"""Playwright-based scraper for Google Maps / Google Business Profile listings and reviews."""
+
+from gmbscraper._matching import has_match_key, is_definitive_match, match_place, pick_best_match
+from gmbscraper._parallel import chunk_items, run_chunked
+from gmbscraper._reviews import GoogleReviewsUnavailableError, scrape_reviews
+from gmbscraper._scraper import GoogleMapsScraper, google_maps_browser
+from gmbscraper._version import __version__
+from gmbscraper.models import (
+    BusinessIdentity,
+    MapsReview,
+    MapsSearchLink,
+    MapsView,
+    OutletIdentity,
+    PlaceProfile,
+    SearchWindow,
+)
+from gmbscraper.parsing import normalize_text
+
+__all__ = [
+    "BusinessIdentity",
+    "GoogleMapsScraper",
+    "GoogleReviewsUnavailableError",
+    "MapsReview",
+    "MapsSearchLink",
+    "MapsView",
+    "OutletIdentity",
+    "PlaceProfile",
+    "SearchWindow",
+    "__version__",
+    "chunk_items",
+    "google_maps_browser",
+    "has_match_key",
+    "is_definitive_match",
+    "match_place",
+    "normalize_text",
+    "pick_best_match",
+    "run_chunked",
+    "scrape_reviews",
+]