gmapsscraper-sdk 0.1.0__py3-none-any.whl

gmapsscraper/__init__.py

@@ -0,0 +1,231 @@
+"""Official Python SDK for the gmapsscraper.io API.
+
+Scrape Google Maps business data — names, addresses, phones, emails,
+websites, ratings, reviews. Get a free API key (10 credits) at
+https://gmapsscraper.io/dashboard
+"""
+
+from __future__ import annotations
+
+import csv as _csv
+import io
+import json
+import time
+import urllib.error
+import urllib.request
+from urllib.parse import quote
+from typing import Any, Callable, Dict, Iterable, List, Optional, Tuple, Union
+
+__version__ = "0.1.0"
+__all__ = ["GMapsScraper", "GMapsScraperError", "parse_csv"]
+
+DEFAULT_BASE_URL = "https://gmapsscraper.io/api/v1"
+
+# (method, url, headers, body) -> (status_code, response_text)
+HttpCallable = Callable[[str, str, Dict[str, str], Optional[str]], Tuple[int, str]]
+
+BusinessRecord = Dict[str, str]
+Job = Dict[str, Any]
+
+
+class GMapsScraperError(Exception):
+    """Raised for HTTP errors, network failures, failed jobs and timeouts.
+
+    Attributes:
+        status: HTTP status code, if the error came from an HTTP response.
+        body: Parsed JSON error body or failed job dict, when available.
+    """
+
+    def __init__(self, message: str, status: Optional[int] = None, body: Any = None):
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+def _default_http(
+    method: str, url: str, headers: Dict[str, str], body: Optional[str], timeout: float = 120.0
+) -> Tuple[int, str]:
+    request = urllib.request.Request(
+        url,
+        data=body.encode("utf-8") if body is not None else None,
+        headers=headers,
+        method=method,
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            return response.getcode(), response.read().decode("utf-8")
+    except urllib.error.HTTPError as exc:
+        return exc.code, exc.read().decode("utf-8", "replace")
+
+
+class GMapsScraper:
+    """Client for the gmapsscraper.io REST API.
+
+    Args:
+        api_key: Your API key — get one at https://gmapsscraper.io/dashboard
+        base_url: API base URL (default: https://gmapsscraper.io/api/v1).
+        http_timeout: Per-request HTTP timeout in seconds for the default
+            transport (default: 120). Independent of the job-polling ``timeout``.
+        http: Optional transport override for testing:
+            ``(method, url, headers, body) -> (status_code, response_text)``.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        http_timeout: float = 120.0,
+        http: Optional[HttpCallable] = None,
+    ):
+        if not isinstance(api_key, str) or not api_key.strip():
+            raise TypeError("api_key is required — get one at https://gmapsscraper.io/dashboard")
+        self._api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self._http = http or (
+            lambda method, url, headers, body: _default_http(method, url, headers, body, timeout=http_timeout)
+        )
+
+    def __repr__(self) -> str:  # never expose the API key in logs/repr
+        return f"GMapsScraper(base_url={self.base_url!r})"
+
+    def _request(self, path: str, *, method: str = "GET", body: Any = None, raw: bool = False) -> Any:
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "User-Agent": f"gmapsscraper-python/{__version__}",
+        }
+        payload = None
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            payload = json.dumps(body)
+        try:
+            status, text = self._http(method, f"{self.base_url}{path}", headers, payload)
+        except GMapsScraperError:
+            raise
+        except Exception as exc:
+            raise GMapsScraperError(f"Network error: {exc}") from exc
+        if not 200 <= status < 300:
+            err_body: Any = None
+            try:
+                err_body = json.loads(text)
+            except ValueError:
+                pass
+            api_error = err_body.get("error") if isinstance(err_body, dict) else None
+            if isinstance(api_error, str) and api_error:
+                message = api_error
+            elif api_error is not None:
+                message = json.dumps(api_error)
+            else:
+                message = f"Request failed with HTTP {status}"
+            raise GMapsScraperError(message, status=status, body=err_body)
+        if raw:
+            return text
+        try:
+            return json.loads(text)
+        except ValueError as exc:
+            raise GMapsScraperError(f"Failed to parse response: {exc}", status=status) from exc
+
+    def create_job(self, keywords: Union[str, Iterable[str]], **options: Any) -> Dict[str, Any]:
+        """Submit a scrape job. Costs 2 credits.
+
+        Option names match the REST API wire format and are stable:
+        ``email``, ``depth``, ``zoom``, ``radius``, ``lang``, ``fast_mode``,
+        ``max_time``, ``lat``, ``lon``, ``name``.
+
+        Returns:
+            ``{"id": "job_xxx", "credits_remaining": 8}``
+        """
+        try:
+            kw = [keywords] if isinstance(keywords, str) else list(keywords)
+        except TypeError:
+            raise TypeError(
+                'keywords must be a non-empty string or an iterable of non-empty strings, '
+                'e.g. "coffee shop in Austin TX"'
+            ) from None
+        if not kw or any(not isinstance(k, str) or not k.strip() for k in kw):
+            raise TypeError(
+                'keywords must be a non-empty string or an iterable of non-empty strings, '
+                'e.g. "coffee shop in Austin TX"'
+            )
+        return self._request("/scrape", method="POST", body={**options, "keywords": kw})
+
+    def get_job(self, job_id: str) -> Job:
+        """Get job status: ``{"id", "status": "running"|"complete"|"failed", "name"}``."""
+        return self._request(f"/jobs/{quote(job_id, safe='')}")
+
+    def wait_for_job(
+        self,
+        job_id: str,
+        *,
+        poll_interval: float = 10.0,
+        timeout: float = 3600.0,
+        on_progress: Optional[Callable[[Job], None]] = None,
+    ) -> Job:
+        """Poll a job until it completes; raises GMapsScraperError on failure or timeout."""
+        start = time.monotonic()
+        while True:
+            job = self.get_job(job_id)
+            if on_progress is not None:
+                on_progress(job)
+            status = job.get("status")
+            if status == "complete":
+                return job
+            if status == "failed":
+                reason = job.get("error")
+                suffix = f": {reason}" if isinstance(reason, str) and reason else ""
+                raise GMapsScraperError(f"Job {job_id} failed{suffix}", body=job)
+            remaining = timeout - (time.monotonic() - start)
+            if remaining <= 0:
+                raise GMapsScraperError(f"Timed out after {timeout}s waiting for job {job_id}", body=job)
+            time.sleep(min(poll_interval, remaining))
+
+    def download_csv(self, job_id: str) -> str:
+        """Download job results as a raw CSV string.
+
+        Columns: title, address, phone, email, website, rating, reviews_count,
+        category, latitude, longitude, google_maps_url, opening_hours.
+
+        Note: the full CSV is buffered in memory; typical result sets are a few
+        hundred KB at most.
+        """
+        return self._request(f"/jobs/{quote(job_id, safe='')}/download", raw=True)
+
+    def download_records(self, job_id: str) -> List[BusinessRecord]:
+        """Download job results parsed into a list of dicts (one per business)."""
+        return parse_csv(self.download_csv(job_id))
+
+    def scrape(
+        self,
+        keywords: Union[str, Iterable[str]],
+        *,
+        poll_interval: float = 10.0,
+        timeout: float = 3600.0,
+        on_progress: Optional[Callable[[Job], None]] = None,
+        **options: Any,
+    ) -> List[BusinessRecord]:
+        """One call: create a job, wait for completion, return parsed records."""
+        job = self.create_job(keywords, **options)
+        job_id = job.get("id") if isinstance(job, dict) else None
+        if not job_id:
+            raise GMapsScraperError("Malformed response from /scrape: missing job id", body=job)
+        self.wait_for_job(job_id, poll_interval=poll_interval, timeout=timeout, on_progress=on_progress)
+        return self.download_records(job_id)
+
+    def credits(self) -> Dict[str, Any]:
+        """Get remaining credit balance: ``{"credits": 8}``."""
+        return self._request("/credits")
+
+
+def parse_csv(text: str) -> List[BusinessRecord]:
+    """Parse RFC 4180 CSV text (strips a UTF-8 BOM) into a list of dicts."""
+    if text.startswith("\ufeff"):
+        text = text[1:]
+    reader = _csv.DictReader(io.StringIO(text))
+    records: List[BusinessRecord] = []
+    for row in reader:
+        records.append({
+            key: (value if isinstance(value, str) else "")
+            for key, value in row.items()
+            if key is not None
+        })
+    return records

gmapsscraper_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: gmapsscraper-sdk
+Version: 0.1.0
+Summary: Official Python SDK for the gmapsscraper.io API — scrape Google Maps business data: names, emails, phones, websites, ratings, reviews.
+Project-URL: Homepage, https://gmapsscraper.io
+Project-URL: Repository, https://github.com/gmapsscraper/gmapsscraper-python
+Project-URL: Documentation, https://gmapsscraper.io/llms.txt
+Project-URL: Issues, https://github.com/gmapsscraper/gmapsscraper-python/issues
+Author: gmapsscraper.io
+License: MIT
+License-File: LICENSE
+Keywords: api client,b2b,business data,email extractor,google maps,google maps scraper,lead generation,leads,local business,places,reviews,scraper,sdk
+Classifier: Development Status :: 4 - Beta
+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.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# gmapsscraper
+
+[![PyPI version](https://img.shields.io/pypi/v/gmapsscraper-sdk.svg)](https://pypi.org/project/gmapsscraper-sdk/)
+[![Python versions](https://img.shields.io/pypi/pyversions/gmapsscraper-sdk.svg)](https://pypi.org/project/gmapsscraper-sdk/)
+[![license](https://img.shields.io/pypi/l/gmapsscraper-sdk.svg)](./LICENSE)
+
+Official Python SDK for the [gmapsscraper.io](https://gmapsscraper.io) API — a **Google Maps scraper** for lead generation. Extract business names, addresses, phone numbers, **emails**, websites, ratings, review counts, categories and coordinates from Google Maps in a few lines of Python.
+
+- 🪶 **Zero dependencies** — pure standard library (`urllib` + `csv`)
+- 🐍 **Python 3.9+**, fully type-hinted (`py.typed`)
+- 📧 **Email extraction** — crawls business websites for contact emails
+- 🗺️ **Auto-geocoding** — just write `"dentist in Chicago IL"`, no coordinates needed
+
+## Install
+
+```bash
+pip install gmapsscraper-sdk
+```
+
+The import name is simply `gmapsscraper`:
+
+Get a free API key (10 credits = 5 searches, no credit card) at **[gmapsscraper.io/dashboard](https://gmapsscraper.io/dashboard)**.
+
+## Quick start
+
+```python
+from gmapsscraper import GMapsScraper
+
+client = GMapsScraper("YOUR_API_KEY")
+
+# One call: submit → poll → download parsed results
+leads = client.scrape("coffee shop in Austin TX", email=True)
+
+print(len(leads), "businesses found")
+print(leads[0])
+# {
+#   "title": "Houndstooth Coffee",
+#   "address": "401 Congress Ave ...",
+#   "phone": "+1 512-...",
+#   "email": "hello@...",
+#   "website": "https://...",
+#   "rating": "4.7",
+#   "reviews_count": "1912",
+#   "category": "Coffee shop",
+#   "latitude": "30.2672", "longitude": "-97.7431",
+#   "google_maps_url": "https://www.google.com/maps/place/...",
+#   "opening_hours": "..."
+# }
+```
+
+## Step-by-step API
+
+If you want control over each stage (e.g. queue jobs and collect later):
+
+```python
+# 1. Submit a job (costs 2 credits, multiple keywords = same cost)
+job = client.create_job(
+    ["plumber in Miami FL", "plumbing service in Miami FL"],
+    email=True, depth=2,
+)
+
+# 2. Wait for completion (polls every 10s)
+client.wait_for_job(job["id"], on_progress=lambda j: print("status:", j["status"]))
+
+# 3a. Parsed dicts…
+records = client.download_records(job["id"])
+
+# 3b. …or the raw CSV
+csv_text = client.download_csv(job["id"])
+
+# Check your balance
+balance = client.credits()  # {"credits": 8}
+```
+
+## Options
+
+All options for `scrape()` / `create_job()` (names match the REST API wire format and are stable):
+
+| Option      | Type           | Default | Description                                          |
+| ----------- | -------------- | ------- | ---------------------------------------------------- |
+| `email`     | bool           | `False` | Extract business emails from websites                |
+| `depth`     | int (1–2)      | `2`     | Higher = more results, **same credit cost**          |
+| `zoom`      | int (1–21)     | `15`    | Map zoom level                                       |
+| `radius`    | int (meters)   | `20000` | Search radius                                        |
+| `lang`      | str            | `"en"`  | ISO 639-1 result language                            |
+| `fast_mode` | bool           | `True`  | Skip deep website crawling                           |
+| `max_time`  | int (s)        | `3600`  | Job timeout on the backend                           |
+| `lat`/`lon` | str \| float   | —       | Coordinates (auto-geocoded from keywords if omitted) |
+
+`scrape()` and `wait_for_job()` also accept `poll_interval` (seconds, default `10` — the API minimum; keep it there to avoid rate limits), `timeout` (seconds, default `3600`) and `on_progress(job)`.
+
+## Error handling
+
+All failures — HTTP errors, network failures, failed jobs and timeouts — raise `GMapsScraperError` with `status` and `body`. Invalid arguments raise `TypeError`:
+
+```python
+from gmapsscraper import GMapsScraper, GMapsScraperError
+
+try:
+    client.scrape("dentist in Chicago IL")
+except GMapsScraperError as err:
+    # 401 invalid key · 402 out of credits · 422 bad params · 429 rate limited
+    print(err.status, err)
+```
+
+| Status | Meaning                                                                    |
+| ------ | -------------------------------------------------------------------------- |
+| 401    | Invalid API key                                                             |
+| 402    | Insufficient credits — top up at [gmapsscraper.io](https://gmapsscraper.io/#pricing) |
+| 422    | Invalid parameters                                                          |
+| 429    | Rate limited (1000 req/day) or too many concurrent jobs (max 10)            |
+| 502    | Backend temporarily unavailable                                             |
+
+## Tips for better results
+
+- Be specific: `"vegan restaurant in Brooklyn NY"` beats `"restaurant in New York"`.
+- Pass several related keywords in one job — broader coverage, same 2 credits.
+- Set `email=True` whenever you need contact info for cold outreach.
+- Jobs typically finish in 30–120 seconds.
+
+## Related resources
+
+- 📘 [API documentation](https://gmapsscraper.io/llms.txt) (also great as LLM context)
+- 📦 [Node.js SDK](https://github.com/gmapsscraper/gmapsscraper-js) — `npm install @gmapsscraper/sdk`
+- 🤖 [Claude / AI agent skills](https://github.com/gmapsscraper/google-maps-agent-skills) — use gmapsscraper from Claude Code and other agents
+- 🧩 [Chrome extension](https://github.com/gmapsscraper/google-maps-scraper) — scrape Google Maps without code
+- ✍️ [Blog: Google Maps scraping guides](https://gmapsscraper.io/blog)
+
+## License
+
+[MIT](./LICENSE) © [gmapsscraper.io](https://gmapsscraper.io)

gmapsscraper_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+gmapsscraper/__init__.py,sha256=OYja3l3XOLdWh_AcXUZti7F_MooY-I1o3V9xi4hNwcU,8973
+gmapsscraper/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gmapsscraper_sdk-0.1.0.dist-info/METADATA,sha256=nEaNoVqQccr49MUOpRgddW6nT0z9_mpbFvRBjJVW3Z8,7143
+gmapsscraper_sdk-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+gmapsscraper_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=fCgj4saUI4ByHZbHiIm1v84ojd_gifiCfrTX3I1ZG-A,1072
+gmapsscraper_sdk-0.1.0.dist-info/RECORD,,

gmapsscraper_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

gmapsscraper_sdk-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gmapsscraper.io
+
+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.