google-maps-leads-scraper 0.1.0__py3-none-any.whl

google_maps_leads_scraper/__init__.py

@@ -0,0 +1,21 @@
+"""Export Google Maps businesses, place details and reviews with Python and the Scrape.do Google Maps API."""
+
+from .client import GoogleMapsScraper, ScrapeError
+from .models import PLACE_FIELDS, REVIEW_FIELDS, Place, Review, dedupe, format_hours, format_ll, parse_place, parse_reviews, parse_search
+
+__all__ = [
+    "GoogleMapsScraper",
+    "PLACE_FIELDS",
+    "Place",
+    "REVIEW_FIELDS",
+    "Review",
+    "ScrapeError",
+    "dedupe",
+    "format_hours",
+    "format_ll",
+    "parse_place",
+    "parse_reviews",
+    "parse_search",
+]
+
+__version__ = "0.1.0"

google_maps_leads_scraper/cli.py

@@ -0,0 +1,141 @@
+"""Command line entry point.
+
+    google-maps-leads-scraper search "coffee shop" --ll 30.2672,-97.7431 --pages 3 -f csv -o leads.csv
+    google-maps-leads-scraper place ChIJ...
+    google-maps-leads-scraper reviews --data-id 0x...:0x... --sort newest --pages 2
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import sys
+from typing import Any, Dict, List, Optional
+
+from . import __version__
+from .client import SORT_OPTIONS, TOKEN_ENV, GoogleMapsScraper, ScrapeError
+from .models import PLACE_FIELDS, REVIEW_FIELDS, dedupe
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="google-maps-leads-scraper",
+        description="Export Google Maps businesses and reviews to JSON or CSV through the Scrape.do Google Maps API.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("-t", "--token", help=f"Scrape.do API token (default: ${TOKEN_ENV})")
+    common.add_argument("--gl", default="us", help="Country code for results (default: us)")
+    common.add_argument("--hl", default="en", help="Language code (default: en)")
+    common.add_argument("-f", "--format", choices=("json", "csv"), default="json", help="Output format (default: json)")
+    common.add_argument("-o", "--output", help="Write to this file instead of stdout")
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    search = sub.add_parser("search", parents=[common], help="Businesses for one or more queries")
+    search.add_argument("queries", nargs="+", help='Search terms, e.g. "dentist" or "coffee shop in Austin, TX"')
+    search.add_argument("--ll", action="append", default=[], help="Centre point lat,lng (repeatable for a grid)")
+    search.add_argument("--zoom", type=float, default=14, help="Map zoom for --ll (default: 14)")
+    search.add_argument("--pages", type=int, default=1, help="Pages per query and point, 20 places each, max 6 (default: 1)")
+    search.add_argument("--details", action="store_true", help="Also fetch each place's details (10 credits per place)")
+
+    place = sub.add_parser("place", parents=[common], help="Details for places by place_id")
+    place.add_argument("place_ids", nargs="*", help="Google place IDs (ChIJ...)")
+    place.add_argument("--cid", action="append", default=[], help="Look up by data_cid instead (repeatable)")
+
+    reviews = sub.add_parser("reviews", parents=[common], help="Reviews for one place")
+    target = reviews.add_mutually_exclusive_group(required=True)
+    target.add_argument("--data-id", help="Feature ID, e.g. 0x8644b5b055cd46fd:0x90bd2653f9c3ab4d")
+    target.add_argument("--place-id", help="Google place ID (ChIJ...)")
+    reviews.add_argument("--sort", choices=SORT_OPTIONS, default="newest", help="Review order (default: newest)")
+    reviews.add_argument("--pages", type=int, default=1, help="Review pages, about 10 each (default: 1)")
+    reviews.add_argument("--query", default="", help="Only reviews that mention this word")
+    return parser
+
+
+def _write(rows: List[Dict[str, Any]], records: List[Dict[str, Any]], fields: List[str], fmt: str, output: Optional[str]) -> None:
+    stream = open(output, "w", encoding="utf-8", newline="" if fmt == "csv" else None) if output else sys.stdout
+    try:
+        if fmt == "csv":
+            writer = csv.DictWriter(stream, fieldnames=fields, extrasaction="ignore")
+            writer.writeheader()
+            writer.writerows(rows)
+        else:
+            json.dump(records, stream, indent=2, ensure_ascii=False)
+            stream.write("\n")
+    finally:
+        if output:
+            stream.close()
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        maps = GoogleMapsScraper(token=args.token, gl=args.gl, hl=args.hl)
+    except ValueError as exc:
+        print(exc, file=sys.stderr)
+        return 2
+
+    failures = 0
+    if args.command == "search":
+        places = []
+        for query in args.queries:
+            for point in args.ll or [None]:
+                label = f"{query!r}" + (f" @ {point}" if point else "")
+                try:
+                    found = maps.search(query, ll=point, pages=args.pages, zoom=args.zoom)
+                except (ScrapeError, ValueError) as exc:
+                    failures += 1
+                    print(f"fail  {label}: {exc}", file=sys.stderr)
+                    continue
+                print(f"ok    {label}: {len(found)} place(s)", file=sys.stderr)
+                places.extend(found)
+        places = dedupe(places)
+        if args.details:
+            detailed = []
+            for p in places:
+                try:
+                    detailed.append(maps.place(p.place_id, p.data_cid) if (p.place_id or p.data_cid) else p)
+                except (ScrapeError, ValueError) as exc:
+                    print(f"fail  details {p.name}: {exc}", file=sys.stderr)
+                    detailed.append(p)
+            places = detailed
+        _write([p.to_row() for p in places], [p.to_dict() for p in places], PLACE_FIELDS, args.format, args.output)
+        count = len(places)
+    elif args.command == "place":
+        if not args.place_ids and not args.cid:
+            print("Pass at least one place_id or --cid.", file=sys.stderr)
+            return 2
+        places = []
+        for pid in args.place_ids:
+            try:
+                places.append(maps.place(place_id=pid))
+            except (ScrapeError, ValueError) as exc:
+                failures += 1
+                print(f"fail  {pid}: {exc}", file=sys.stderr)
+        for cid in args.cid:
+            try:
+                places.append(maps.place(data_cid=cid))
+            except (ScrapeError, ValueError) as exc:
+                failures += 1
+                print(f"fail  cid {cid}: {exc}", file=sys.stderr)
+        _write([p.to_row() for p in places], [p.to_dict() for p in places], PLACE_FIELDS, args.format, args.output)
+        count = len(places)
+    else:
+        try:
+            found = maps.reviews(
+                data_id=args.data_id or "", place_id=args.place_id or "", sort_by=args.sort, pages=args.pages, query=args.query
+            )
+        except (ScrapeError, ValueError) as exc:
+            print(f"fail  reviews: {exc}", file=sys.stderr)
+            return 1
+        _write([r.to_row() for r in found], [r.to_dict() for r in found], REVIEW_FIELDS, args.format, args.output)
+        count = len(found)
+
+    print(f"{count} record(s), {maps.credits_used} credits used" + (f", saved to {args.output}" if args.output else ""), file=sys.stderr)
+    return 1 if failures and not count else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

google_maps_leads_scraper/client.py

@@ -0,0 +1,203 @@
+"""Call the Scrape.do Google Maps API.
+
+Google Maps renders everything with JavaScript and serves a consent wall,
+CAPTCHAs and rate limits to scripts. The Scrape.do Google Maps API runs the
+request from a residential IP and returns the result as parsed JSON, so there
+is no HTML or protobuf to decode:
+
+* ``/plugin/google/maps/search``  businesses for a query around a point
+  (20 per page, about 120 per query)
+* ``/plugin/google/maps/place``   one business by ``place_id`` or ``data_cid``
+* ``/plugin/google/maps/reviews`` reviews by ``data_id`` or ``place_id``
+
+Every successful call costs 10 credits.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from typing import Any, Dict, Iterator, List, Optional
+
+import requests
+
+from .models import Place, Review, dedupe, format_ll, next_page_token, parse_place, parse_reviews, parse_search
+
+API_BASE = "https://api.scrape.do/plugin/google/maps"
+TOKEN_ENV = "SCRAPEDO_TOKEN"
+PAGE_SIZE = 20
+MAX_PAGES = 6  # Google Maps stops at about 120 results per query
+SORT_OPTIONS = ("most_relevant", "newest", "highest_rating", "lowest_rating")
+
+
+class ScrapeError(RuntimeError):
+    """Raised when the API call fails."""
+
+    def __init__(self, message: str, status_code: Optional[int] = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class GoogleMapsScraper:
+    """Search Google Maps, look up places and read reviews.
+
+    >>> maps = GoogleMapsScraper(token="YOUR_SCRAPEDO_TOKEN")
+    >>> places = maps.search("coffee shop", ll="30.2672,-97.7431", pages=2)
+    >>> details = maps.place(places[0].place_id)
+    >>> reviews = maps.reviews(data_id=places[0].data_id, sort_by="newest")
+    """
+
+    def __init__(
+        self,
+        token: Optional[str] = None,
+        gl: str = "us",
+        hl: str = "en",
+        timeout: float = 90.0,
+        retries: int = 2,
+        session: Optional[requests.Session] = None,
+    ):
+        self.token = token or os.environ.get(TOKEN_ENV, "")
+        if not self.token:
+            raise ValueError(f"A Scrape.do API token is required. Pass token=... or set {TOKEN_ENV}.")
+        self.gl = gl
+        self.hl = hl
+        self.timeout = timeout
+        self.retries = max(0, retries)
+        self.session = session or requests.Session()
+        self.requests_made = 0
+
+    # -- transport -----------------------------------------------------------------
+
+    def call(self, endpoint: str, params: Dict[str, Any]) -> Dict[str, Any]:
+        """GET ``/plugin/google/maps/<endpoint>`` and return the decoded JSON."""
+        query = {k: v for k, v in params.items() if v not in (None, "")}
+        query["token"] = self.token
+        url = f"{API_BASE}/{endpoint}"
+        last_error: Optional[ScrapeError] = None
+        for attempt in range(self.retries + 1):
+            try:
+                response = self.session.get(url, params=query, timeout=self.timeout)
+            except requests.RequestException as exc:
+                last_error = ScrapeError(f"Request failed: {exc}")
+            else:
+                if response.status_code == 200:
+                    self.requests_made += 1  # only successful calls are billed
+                    try:
+                        return response.json()
+                    except ValueError:
+                        last_error = ScrapeError("The API returned a non-JSON body", 200)
+                else:
+                    last_error = ScrapeError(
+                        f"{endpoint} failed with status {response.status_code}: {response.text[:200]}",
+                        status_code=response.status_code,
+                    )
+                    # A bad token or bad parameters will not fix themselves
+                    if 400 <= response.status_code < 500 and response.status_code != 429:
+                        break
+            if attempt < self.retries:
+                time.sleep(2 * (attempt + 1))
+        assert last_error is not None
+        raise last_error
+
+    # -- search --------------------------------------------------------------------
+
+    def iter_search(self, query: str, ll: Optional[str] = None, pages: int = 1, zoom: float = 14) -> Iterator[Place]:
+        """Yield places for ``query`` page by page (20 per page, at most 6 pages).
+
+        ``ll`` centres the search: ``"30.2672,-97.7431"`` or ``"@30.2672,-97.7431,14z"``.
+        Without it, put the location in the query ("coffee shop in Austin, TX").
+        """
+        if not query.strip():
+            raise ValueError("query is empty")
+        center = format_ll(ll, zoom) if ll else None
+        seen = set()
+        for page in range(min(max(1, pages), MAX_PAGES)):
+            payload = self.call(
+                "search",
+                {"q": query, "ll": center, "gl": self.gl, "hl": self.hl, "start": page * PAGE_SIZE or None},
+            )
+            places = parse_search(payload)
+            fresh = [p for p in places if p.key not in seen]
+            for place in fresh:
+                seen.add(place.key)
+                yield place
+            if len(places) < PAGE_SIZE or not fresh:
+                break
+
+    def search(self, query: str, ll: Optional[str] = None, pages: int = 1, zoom: float = 14) -> List[Place]:
+        """All places for one query as a list (see :meth:`iter_search`)."""
+        return list(self.iter_search(query, ll=ll, pages=pages, zoom=zoom))
+
+    def search_grid(self, queries: List[str], points: List[str], pages: int = 1, zoom: float = 14) -> List[Place]:
+        """Run every query at every point and merge the results without duplicates.
+
+        One query tops out at about 120 places, so covering a city means
+        repeating it across several centre points (and related categories).
+        """
+        found: List[Place] = []
+        for query in queries:
+            for point in points or [None]:
+                found.extend(self.iter_search(query, ll=point, pages=pages, zoom=zoom))
+        return dedupe(found)
+
+    # -- place ---------------------------------------------------------------------
+
+    def place(self, place_id: str = "", data_cid: str = "") -> Place:
+        """Full details for one place: hours, rating breakdown, attributes and more."""
+        if not place_id and not data_cid:
+            raise ValueError("Pass place_id or data_cid")
+        payload = self.call("place", {"place_id": place_id or None, "data_cid": None if place_id else data_cid, "hl": self.hl})
+        return parse_place(payload)
+
+    # -- reviews -------------------------------------------------------------------
+
+    def iter_reviews(
+        self,
+        data_id: str = "",
+        place_id: str = "",
+        sort_by: str = "newest",
+        pages: int = 1,
+        query: str = "",
+        topic_id: str = "",
+    ) -> Iterator[Review]:
+        """Yield reviews page by page (about 10 per page).
+
+        ``sort_by`` is one of ``most_relevant``, ``newest``, ``highest_rating``,
+        ``lowest_rating``. ``query`` filters by a word; ``topic_id`` by one of the
+        topics Google extracted. Pass one of the two, not both.
+        """
+        if not data_id and not place_id:
+            raise ValueError("Pass data_id or place_id")
+        if sort_by not in SORT_OPTIONS:
+            raise ValueError(f"sort_by must be one of {', '.join(SORT_OPTIONS)}")
+        if query and topic_id:
+            raise ValueError("Pass query or topic_id, not both")
+        token = ""
+        seen = set()
+        for _ in range(max(1, pages)):
+            params = {
+                "data_id": data_id or None,
+                "place_id": None if data_id else place_id,
+                "sort_by": None if sort_by == "most_relevant" else sort_by,
+                "query": query or None,
+                "topic_id": topic_id or None,
+                "next_page_token": token or None,
+                "hl": self.hl,
+            }
+            payload = self.call("reviews", params)
+            fresh = [r for r in parse_reviews(payload, place_id=place_id, data_id=data_id) if r.review_id not in seen]
+            for review in fresh:
+                seen.add(review.review_id)
+                yield review
+            token = next_page_token(payload)
+            if not token or not fresh:
+                break
+
+    def reviews(self, data_id: str = "", place_id: str = "", sort_by: str = "newest", pages: int = 1, **kwargs: str) -> List[Review]:
+        """All reviews as a list (see :meth:`iter_reviews`)."""
+        return list(self.iter_reviews(data_id=data_id, place_id=place_id, sort_by=sort_by, pages=pages, **kwargs))
+
+    @property
+    def credits_used(self) -> int:
+        """Credits spent so far by this client (10 per call)."""
+        return self.requests_made * 10

google_maps_leads_scraper/models.py

@@ -0,0 +1,275 @@
+"""Turn Scrape.do Google Maps API responses into flat records.
+
+The Scrape.do Google Maps API returns parsed JSON: ``local_results`` for a
+search, ``place_results`` for one place and ``reviews`` for a review page. The
+helpers here map those objects to dataclasses that export cleanly to CSV.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import asdict, dataclass, field
+from typing import Any, Dict, Iterable, List, Optional
+
+DAYS = ("monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday")
+
+PLACE_FIELDS = [
+    "name", "category", "categories", "rating", "reviews", "phone", "website", "address",
+    "latitude", "longitude", "hours", "open_state", "place_id", "data_id", "data_cid",
+    "plus_code", "thumbnail", "maps_url",
+]
+
+REVIEW_FIELDS = [
+    "place_id", "data_id", "review_id", "rating", "date", "iso_date", "text", "likes",
+    "author", "author_reviews", "local_guide", "owner_reply", "owner_reply_date", "link",
+]
+
+_LL_RE = re.compile(r"^@?\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)(?:\s*,\s*(\d+(?:\.\d+)?)z?)?\s*$")
+_SPACES = re.compile(r"[   ]")
+
+
+def clean_text(value: Any) -> str:
+    """Normalize the narrow and non-breaking spaces Google puts in times."""
+    if value is None:
+        return ""
+    return _SPACES.sub(" ", str(value)).strip()
+
+
+def format_ll(value: str, zoom: float = 14) -> str:
+    """Return the ``@lat,lng,zoomz`` form the API expects.
+
+    Accepts ``"30.2672,-97.7431"``, ``"30.2672, -97.7431, 13"`` or an already
+    formatted ``"@30.2672,-97.7431,14z"``.
+    """
+    match = _LL_RE.match(value or "")
+    if not match:
+        raise ValueError(f"Not a coordinate pair: {value!r} (expected 'lat,lng' or '@lat,lng,14z')")
+    lat, lng, z = match.groups()
+    if not -90 <= float(lat) <= 90 or not -180 <= float(lng) <= 180:
+        raise ValueError(f"Coordinates out of range: {value!r}")
+    zoom_str = z if z else (f"{zoom:g}")
+    return f"@{lat},{lng},{zoom_str}z"
+
+
+def format_hours(hours: Any) -> str:
+    """Flatten ``operating_hours`` (dict) or ``hours`` (list of dicts) to one line.
+
+    >>> format_hours({"monday": "7 AM-2 PM", "tuesday": "Closed"})
+    'Mon: 7 AM-2 PM; Tue: Closed'
+    """
+    merged: Dict[str, str] = {}
+    if isinstance(hours, dict):
+        merged = {str(k).lower(): clean_text(v) for k, v in hours.items()}
+    elif isinstance(hours, list):
+        for item in hours:
+            if isinstance(item, dict):
+                merged.update({str(k).lower(): clean_text(v) for k, v in item.items()})
+    else:
+        return ""
+    parts = [f"{day[:3].title()}: {merged[day]}" for day in DAYS if day in merged]
+    return "; ".join(parts)
+
+
+def maps_url(place_id: str = "", data_cid: str = "") -> str:
+    """A link that opens the place in Google Maps."""
+    if data_cid:
+        return f"https://maps.google.com/?cid={data_cid}"
+    if place_id:
+        return f"https://www.google.com/maps/place/?q=place_id:{place_id}"
+    return ""
+
+
+@dataclass
+class Place:
+    """One business from a search result or a place lookup."""
+
+    name: str = ""
+    category: str = ""
+    categories: List[str] = field(default_factory=list)
+    rating: Optional[float] = None
+    reviews: Optional[int] = None
+    phone: str = ""
+    website: str = ""
+    address: str = ""
+    latitude: Optional[float] = None
+    longitude: Optional[float] = None
+    hours: str = ""
+    open_state: str = ""
+    place_id: str = ""
+    data_id: str = ""
+    data_cid: str = ""
+    plus_code: str = ""
+    thumbnail: str = ""
+    maps_url: str = ""
+    description: str = ""
+    rating_breakdown: Dict[str, int] = field(default_factory=dict)
+    attributes: Dict[str, List[str]] = field(default_factory=dict)
+
+    @classmethod
+    def from_api(cls, item: Dict[str, Any]) -> "Place":
+        coords = item.get("gps_coordinates") or {}
+        types = [clean_text(t) for t in (item.get("types") or []) if t]
+        category = clean_text(item.get("type")) or (types[0] if types else "")
+        if category and category not in types:
+            types.insert(0, category)
+        hours = format_hours(item.get("operating_hours") or item.get("hours"))
+        attributes: Dict[str, List[str]] = {}
+        for ext in item.get("extensions") or []:
+            if isinstance(ext, dict):
+                for key, values in ext.items():
+                    if isinstance(values, list):
+                        attributes[str(key)] = [clean_text(v) for v in values]
+        breakdown = {
+            str(row.get("stars")): int(row.get("amount") or 0)
+            for row in item.get("rating_summary") or []
+            if isinstance(row, dict) and row.get("stars") is not None
+        }
+        description = item.get("description")
+        if isinstance(description, dict):
+            description = description.get("snippet") or ""
+        place_id = str(item.get("place_id") or "")
+        data_cid = str(item.get("data_cid") or "")
+        return cls(
+            name=clean_text(item.get("title")),
+            category=category,
+            categories=types,
+            rating=_to_float(item.get("rating")),
+            reviews=_to_int(item.get("reviews")),
+            phone=clean_text(item.get("phone")),
+            website=clean_text(item.get("website")),
+            address=clean_text(item.get("address")),
+            latitude=_to_float(coords.get("latitude")),
+            longitude=_to_float(coords.get("longitude")),
+            hours=hours,
+            open_state=clean_text(item.get("open_state") or (item.get("hours") if isinstance(item.get("hours"), str) else "")),
+            place_id=place_id,
+            data_id=str(item.get("data_id") or ""),
+            data_cid=data_cid,
+            plus_code=clean_text(item.get("plus_code")),
+            thumbnail=clean_text(item.get("thumbnail")),
+            maps_url=maps_url(place_id, data_cid),
+            description=clean_text(description),
+            rating_breakdown=breakdown,
+            attributes=attributes,
+        )
+
+    @property
+    def key(self) -> str:
+        """Stable identity used to drop duplicates across pages and queries."""
+        return self.place_id or self.data_id or self.data_cid or f"{self.name}|{self.address}"
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+    def to_row(self) -> Dict[str, Any]:
+        row = {name: getattr(self, name) for name in PLACE_FIELDS}
+        row["categories"] = ", ".join(self.categories)
+        return {k: ("" if v is None else v) for k, v in row.items()}
+
+
+@dataclass
+class Review:
+    """One Google Maps review."""
+
+    review_id: str = ""
+    rating: Optional[int] = None
+    date: str = ""
+    iso_date: str = ""
+    text: str = ""
+    likes: int = 0
+    author: str = ""
+    author_reviews: Optional[int] = None
+    local_guide: bool = False
+    owner_reply: str = ""
+    owner_reply_date: str = ""
+    link: str = ""
+    place_id: str = ""
+    data_id: str = ""
+
+    @classmethod
+    def from_api(cls, item: Dict[str, Any], place_id: str = "", data_id: str = "") -> "Review":
+        user = item.get("user") or {}
+        response = item.get("response") or {}
+        snippet = item.get("snippet")
+        if not snippet:
+            snippet = (item.get("extracted_snippet") or {}).get("original")
+        reply = response.get("snippet") or (response.get("extracted_snippet") or {}).get("original")
+        return cls(
+            review_id=str(item.get("review_id") or ""),
+            rating=_to_int(item.get("rating")),
+            date=clean_text(item.get("date")),
+            iso_date=clean_text(item.get("iso_date")),
+            text=clean_text(snippet),
+            likes=_to_int(item.get("likes")) or 0,
+            author=clean_text(user.get("name")),
+            author_reviews=_to_int(user.get("reviews")),
+            local_guide=bool(user.get("local_guide")),
+            owner_reply=clean_text(reply),
+            owner_reply_date=clean_text(response.get("date")),
+            link=clean_text(item.get("link")),
+            place_id=place_id,
+            data_id=data_id,
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+    def to_row(self) -> Dict[str, Any]:
+        return {name: ("" if getattr(self, name) is None else getattr(self, name)) for name in REVIEW_FIELDS}
+
+
+def parse_search(payload: Dict[str, Any]) -> List[Place]:
+    """Places from one search response (``local_results``)."""
+    results = payload.get("local_results") or []
+    if isinstance(results, dict):  # a query that resolves to a single place
+        results = [results]
+    return [Place.from_api(item) for item in results if isinstance(item, dict)]
+
+
+def parse_place(payload: Dict[str, Any]) -> Place:
+    """The place from a place response (``place_results``)."""
+    item = payload.get("place_results")
+    if not isinstance(item, dict):
+        raise ValueError("Response has no place_results")
+    return Place.from_api(item)
+
+
+def parse_reviews(payload: Dict[str, Any], place_id: str = "", data_id: str = "") -> List[Review]:
+    """Reviews from one reviews response."""
+    return [
+        Review.from_api(item, place_id=place_id, data_id=data_id)
+        for item in payload.get("reviews") or []
+        if isinstance(item, dict)
+    ]
+
+
+def next_page_token(payload: Dict[str, Any]) -> str:
+    return str((payload.get("pagination") or {}).get("next_page_token") or "")
+
+
+def dedupe(places: Iterable[Place]) -> List[Place]:
+    """Keep the first occurrence of every place."""
+    seen = set()
+    out: List[Place] = []
+    for place in places:
+        if place.key in seen:
+            continue
+        seen.add(place.key)
+        out.append(place)
+    return out
+
+
+def _to_float(value: Any) -> Optional[float]:
+    try:
+        return float(value) if value not in (None, "") else None
+    except (TypeError, ValueError):
+        return None
+
+
+def _to_int(value: Any) -> Optional[int]:
+    if value in (None, ""):
+        return None
+    try:
+        return int(str(value).replace(",", "").split(".")[0])
+    except (TypeError, ValueError):
+        return None

google_maps_leads_scraper-0.1.0.dist-info/METADATA

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: google-maps-leads-scraper
+Version: 0.1.0
+Summary: Export Google Maps businesses (name, phone, website, address, rating, hours, coordinates), place details and reviews to CSV with Python and the Scrape.do Google Maps API.
+Author: Buğrahan Saka
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/bugrahansss/google-maps-leads-scraper
+Project-URL: Source, https://github.com/bugrahansss/google-maps-leads-scraper
+Project-URL: Issues, https://github.com/bugrahansss/google-maps-leads-scraper/issues
+Project-URL: Guide, https://scrape.do/blog/google-maps-scraping/
+Keywords: google maps,google maps scraper,lead generation,web scraping,places,reviews,scrapedo
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25
+Dynamic: license-file
+
+# Google Maps Leads Scraper
+
+[![PyPI](https://img.shields.io/pypi/v/google-maps-leads-scraper)](https://pypi.org/project/google-maps-leads-scraper/)
+[![Python](https://img.shields.io/pypi/pyversions/google-maps-leads-scraper)](https://pypi.org/project/google-maps-leads-scraper/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Turn a Google Maps search into a lead list. Give it a query and a point on the map; get back every business with its **name, phone, website, address, rating, review count, opening hours, coordinates and place ID**, as JSON or CSV. It can also pull a single place's full details (rating breakdown, plus code, attributes) and its **reviews** with owner replies.
+
+It runs on the [Scrape.do Google Maps API](https://scrape.do/?utm_source=github&utm_medium=readme&utm_campaign=google-maps-leads-scraper), which returns parsed JSON, so there is no HTML, protobuf or browser automation to maintain.
+
+```bash
+pip install google-maps-leads-scraper
+export SCRAPEDO_TOKEN=your_token
+google-maps-leads-scraper search "coffee shop" --ll 30.2672,-97.7431 --pages 6 -f csv -o austin-coffee.csv
+```
+
+```
+ok    'coffee shop' @ 30.2672,-97.7431: 104 place(s)
+104 record(s), 60 credits used, saved to austin-coffee.csv
+```
+
+## Why not just request google.com/maps?
+
+Google Maps is a JavaScript app. The page you get from `requests` has no business data in it, and the internal endpoints the app calls (`/search?tbm=map`, `/maps/preview/place`) answer in a nested protobuf-over-JSON array with an anti-XSSI prefix and no stable field names. Scripts that send many of them meet the consent wall, CAPTCHAs and rate limits, and the reviews endpoint most old tutorials used (`listentitiesreviews`) has been retired.
+
+The Scrape.do Google Maps API makes the request from a residential IP and returns clean JSON:
+
+| Endpoint | Input | Returns |
+| --- | --- | --- |
+| `/plugin/google/maps/search` | `q`, `ll`, `start` | 20 places per page, about 120 per query |
+| `/plugin/google/maps/place` | `place_id` or `data_cid` | one place with hours, rating breakdown, attributes |
+| `/plugin/google/maps/reviews` | `data_id` or `place_id`, `sort_by` | about 10 reviews per page, owner replies, topics |
+
+Every successful call costs 10 credits, so a full page of 20 leads costs 10 credits and 1,000 leads cost about 500. The free plan has 1,000 credits a month.
+
+## Command line
+
+```bash
+# One query around a point, 6 pages (the ~120 place maximum)
+google-maps-leads-scraper search "plumber" --ll 40.7128,-74.0060 --pages 6 -f csv -o nyc-plumbers.csv
+
+# The location can be in the query instead
+google-maps-leads-scraper search "vegan restaurant in Lisbon" --gl pt
+
+# Several queries across several points, merged without duplicates
+google-maps-leads-scraper search "dentist" "orthodontist" \
+  --ll 30.2672,-97.7431 --ll 30.3072,-97.7559 --pages 2 -f csv -o dentists.csv
+
+# Full details for places
+google-maps-leads-scraper place ChIJ_UbNVbC1RIYRTavD-VMmvZA
+
+# Reviews, newest first, two pages
+google-maps-leads-scraper reviews --data-id 0x8644b5b055cd46fd:0x90bd2653f9c3ab4d --sort newest --pages 2 -f csv -o reviews.csv
+```
+
+`--ll` takes `lat,lng`, `lat,lng,zoom` or the `@lat,lng,14z` form from a Maps URL. `search --details` also fetches every place's detail page (10 more credits per place).
+
+## Python
+
+```python
+from google_maps_leads_scraper import GoogleMapsScraper
+
+maps = GoogleMapsScraper(token="YOUR_SCRAPEDO_TOKEN")  # or set SCRAPEDO_TOKEN
+
+places = maps.search("coffee shop", ll="30.2672,-97.7431", pages=3)
+for p in places[:3]:
+    print(p.name, p.rating, p.reviews, p.phone, p.website)
+
+details = maps.place(places[0].place_id)
+print(details.hours)              # Mon: 7 AM–2 PM; Tue: 7 AM–2 PM; ...
+print(details.rating_breakdown)   # {'1': 16, '2': 6, '3': 14, '4': 41, '5': 604}
+
+for review in maps.reviews(data_id=places[0].data_id, sort_by="lowest_rating", pages=2):
+    print(review.rating, review.date, review.text[:80], "| reply:", bool(review.owner_reply))
+
+print(maps.credits_used)
+```
+
+To cover a whole city, run the query around several points; `search_grid` does that and drops duplicates by place ID. See [`examples/leads_grid.py`](examples/leads_grid.py).
+
+## Output fields
+
+**Places:** `name`, `category`, `categories`, `rating`, `reviews`, `phone`, `website`, `address`, `latitude`, `longitude`, `hours`, `open_state`, `place_id`, `data_id`, `data_cid`, `plus_code`, `thumbnail`, `maps_url`. JSON output adds `rating_breakdown` and `attributes` (accessibility, service options and so on).
+
+**Reviews:** `place_id`, `data_id`, `review_id`, `rating`, `date`, `iso_date`, `text`, `likes`, `author`, `author_reviews`, `local_guide`, `owner_reply`, `owner_reply_date`, `link`.
+
+`place_id` feeds `place`; `data_id` feeds `reviews`.
+
+## Use it responsibly
+
+Business listings are public, but reviews carry the names of the people who wrote them. Store only what you need, follow the privacy rules that apply to you (GDPR, CCPA), respect opt-outs before cold outreach, and read Google's terms for your use case.
+
+## Also available
+
+- **No-code:** [Google Maps Leads Scraper on Apify](https://apify.com/scrapedo/google-maps-leads-scraper)
+- **Browser demo:** [Hugging Face Space](https://huggingface.co/spaces/bugrahans/google-maps-leads-scraper)
+- **Full guide:** [Google Maps Scraper: How to Scrape Google Maps for Leads](https://scrape.do/blog/google-maps-scraping/?utm_source=github&utm_medium=readme&utm_campaign=google-maps-leads-scraper), including the raw Python approach without the API
+
+## Tests
+
+```bash
+python -m unittest discover -s tests
+```
+
+The fixtures are made-up businesses on example.com; the tests never hit the network.
+
+## License
+
+MIT

google_maps_leads_scraper-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+google_maps_leads_scraper/__init__.py,sha256=wnxQvE49T74D4LJxrz6P241-05LbYCRGJ1-48mKpURw,561
+google_maps_leads_scraper/cli.py,sha256=8NXEj4WG0GZ7KWQnzKpGcYznOJe-0B9SVri-UGl7Wy4,6767
+google_maps_leads_scraper/client.py,sha256=BeCqwrYkfrM2hjXE3MwB4vD6rB35GJRL7TgeUSLpsPg,8690
+google_maps_leads_scraper/models.py,sha256=orV5oFxvq4Lp7j1XhPXI-7zYYFzDYJfKsxiUGKJM5Yc,10046
+google_maps_leads_scraper-0.1.0.dist-info/licenses/LICENSE,sha256=ROg_cpaduSqtDgeddNL4Csjnu7TkWQsINx0OuPmUTwM,1071
+google_maps_leads_scraper-0.1.0.dist-info/METADATA,sha256=q8vizKzllV-C1BO8ObAV8tDfIIS3xqBC6SqK7_AjWH8,6790
+google_maps_leads_scraper-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+google_maps_leads_scraper-0.1.0.dist-info/entry_points.txt,sha256=z_TxxeTmkjpQfUgHlPYzsE2KjiaE8gq_TYZz4uxvjTg,81
+google_maps_leads_scraper-0.1.0.dist-info/top_level.txt,sha256=zOqylLqJi8rIqR00ewTj-nhXXb6pKjKDm2f4w5Dwpsk,26
+google_maps_leads_scraper-0.1.0.dist-info/RECORD,,

google_maps_leads_scraper-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

google_maps_leads_scraper-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+google-maps-leads-scraper = google_maps_leads_scraper.cli:main

google_maps_leads_scraper-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Buğrahan Saka
+
+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.

google_maps_leads_scraper-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+google_maps_leads_scraper