boltscraper 1.0.0__py3-none-any.whl

boltscraper/__init__.py

@@ -0,0 +1,27 @@
+"""
+Bolt Scraper Official Python SDK
+Fast, reliable, and proxy-free scraping for Google Maps, Google Reviews, and Websites.
+"""
+
+from .client import BoltScraper, VERSION
+from .exceptions import (
+    BoltScraperError,
+    AuthenticationError,
+    QuotaExceededError,
+    NotFoundError,
+    RateLimitError,
+    UpstreamError
+)
+from .webhooks import WebhooksResource
+
+__version__ = VERSION
+__all__ = [
+    "BoltScraper",
+    "WebhooksResource",
+    "BoltScraperError",
+    "AuthenticationError",
+    "QuotaExceededError",
+    "NotFoundError",
+    "RateLimitError",
+    "UpstreamError"
+]

boltscraper/client.py

@@ -0,0 +1,166 @@
+"""
+Bolt Scraper Official Python SDK Client
+"""
+
+import os
+import time
+from typing import Optional, Dict, Any
+import requests
+
+from .exceptions import (
+    BoltScraperError,
+    AuthenticationError,
+    QuotaExceededError,
+    NotFoundError,
+    RateLimitError,
+    UpstreamError
+)
+from .maps import MapsResource
+from .reviews import ReviewsResource
+from .website import WebsiteResource
+from .webhooks import WebhooksResource
+
+DEFAULT_BASE_URL = "https://boltscraper.com/api/v1"
+VERSION = "1.0.0"
+
+
+class BoltScraper:
+    """
+    Official Python SDK client for Bolt Scraper.
+    
+    Usage:
+        from boltscraper import BoltScraper
+
+        # Initialize with your API key
+        client = BoltScraper(api_key="bs_live_your_key_here")
+
+        # 1. Search Google Maps in real time
+        results = client.maps.search("Plumbers in Austin, TX", page=1)
+
+        # 2. Extract customer reviews without OAuth
+        reviews = client.reviews.search("ChIJb8Jg9q-1RIYRAxvq_mZ0gXY", max_reviews=100)
+
+        # 3. Extract direct business emails and socials from a domain
+        company = client.website.scrape("https://example.com")
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: int = 60,
+        max_retries: int = 3,
+        auto_retry_rate_limit: bool = True
+    ):
+        self.api_key = api_key or os.getenv("BOLTSCRAPER_API_KEY")
+        if not self.api_key:
+            raise AuthenticationError(
+                "Missing Bolt Scraper API key. Pass 'api_key' to BoltScraper(api_key='bs_...') "
+                "or set the 'BOLTSCRAPER_API_KEY' environment variable. "
+                "Get your key at https://app.boltscraper.com"
+            )
+
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.auto_retry_rate_limit = auto_retry_rate_limit
+
+        self.session = requests.Session()
+        self.session.headers.update({
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            "User-Agent": f"boltscraper-python/{VERSION}"
+        })
+
+        # Initialize resources
+        self.maps = MapsResource(self)
+        self.reviews = ReviewsResource(self)
+        self.website = WebsiteResource(self)
+        self.webhooks = WebhooksResource(self)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        params: Optional[Dict[str, Any]] = None,
+        json: Optional[Dict[str, Any]] = None,
+        raw_bytes: bool = False
+    ) -> Any:
+        url = f"{self.base_url}{path}"
+        retries = 0
+
+        while True:
+            try:
+                response = self.session.request(
+                    method=method,
+                    url=url,
+                    params=params,
+                    json=json,
+                    timeout=self.timeout
+                )
+            except requests.exceptions.RequestException as e:
+                raise BoltScraperError(f"Network request to Bolt Scraper failed: {str(e)}")
+
+            if response.status_code == 200:
+                if raw_bytes:
+                    return response.content
+                try:
+                    return response.json()
+                except ValueError:
+                    return response.text
+
+            # Handle 429 with automatic exponential backoff
+            if response.status_code == 429:
+                retry_after = int(response.headers.get("Retry-After", 2 ** retries))
+                if self.auto_retry_rate_limit and retries < self.max_retries:
+                    retries += 1
+                    time.sleep(retry_after)
+                    continue
+                try:
+                    err_json = response.json()
+                except ValueError:
+                    err_json = {}
+                raise RateLimitError(
+                    f"Bolt Scraper rate limit exceeded (60 req/min). Retry after {retry_after}s.",
+                    retry_after=retry_after,
+                    response_body=err_json
+                )
+
+            # Parse error payload
+            try:
+                err_body = response.json()
+                err_msg = err_body.get("error") or err_body.get("message") or response.text
+            except ValueError:
+                err_body = {}
+                err_msg = response.text or f"HTTP {response.status_code}"
+
+            if response.status_code == 401:
+                raise AuthenticationError(
+                    f"Authentication failed: {err_msg}. Verify your 'bs_...' API key at https://app.boltscraper.com",
+                    status_code=401,
+                    response_body=err_body
+                )
+            elif response.status_code == 403:
+                raise QuotaExceededError(
+                    f"Quota exceeded: {err_msg}. Upgrade your plan at https://boltscraper.com/pricing",
+                    status_code=403,
+                    response_body=err_body
+                )
+            elif response.status_code == 404:
+                raise NotFoundError(
+                    f"Resource not found: {err_msg}",
+                    status_code=404,
+                    response_body=err_body
+                )
+            elif response.status_code in (502, 503, 504):
+                raise UpstreamError(
+                    f"Target upstream error (0 credits billed): {err_msg}",
+                    status_code=response.status_code,
+                    response_body=err_body
+                )
+            else:
+                raise BoltScraperError(
+                    f"Bolt Scraper API error ({response.status_code}): {err_msg}",
+                    status_code=response.status_code,
+                    response_body=err_body
+                )

boltscraper/exceptions.py

@@ -0,0 +1,38 @@
+"""
+Bolt Scraper Python SDK - Exception Classes
+"""
+
+class BoltScraperError(Exception):
+    """Base exception for all Bolt Scraper SDK errors."""
+    def __init__(self, message: str, status_code: int = None, response_body: dict = None):
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.response_body = response_body or {}
+
+
+class AuthenticationError(BoltScraperError):
+    """Raised on 401 Unauthorized - invalid or missing API key."""
+    pass
+
+
+class QuotaExceededError(BoltScraperError):
+    """Raised on 403 Forbidden - monthly lead or crawl credits exhausted."""
+    pass
+
+
+class NotFoundError(BoltScraperError):
+    """Raised on 404 Not Found - resource or job ID not found."""
+    pass
+
+
+class RateLimitError(BoltScraperError):
+    """Raised on 429 Too Many Requests - hit 60 req/min limit."""
+    def __init__(self, message: str, retry_after: int = 1, status_code: int = 429, response_body: dict = None):
+        super().__init__(message, status_code, response_body)
+        self.retry_after = retry_after
+
+
+class UpstreamError(BoltScraperError):
+    """Raised on 502/504 Bad Gateway - target domain unreachable or upstream failure."""
+    pass

boltscraper/maps.py

@@ -0,0 +1,106 @@
+"""
+Google Maps Scraper Resource
+Handles real-time search, asynchronous scraping jobs, and lead exports.
+"""
+
+from typing import List, Union, Optional, Dict, Any
+
+
+class MapsResource:
+    def __init__(self, client):
+        self._client = client
+
+    def search(
+        self,
+        keyword: str,
+        page: int = 1,
+        hl: str = "en"
+    ) -> Dict[str, Any]:
+        """
+        Synchronous real-time Google Maps search (~2-4s response).
+        
+        Args:
+            keyword: Search query (e.g. 'Coffee shops in Seattle' or 'Dentists Paris')
+            page: Page number (1 to 15, yielding up to 20 results per page)
+            hl: Two-letter interface language code (e.g. 'en', 'es', 'de', 'fr')
+            
+        Returns:
+            Dictionary containing pagination metadata and extracted leads with 60+ attributes.
+        """
+        payload = {
+            "keyword": keyword,
+            "page": page,
+            "hl": hl
+        }
+        return self._client._request("POST", "/maps/search", json=payload)
+
+    def create_job(
+        self,
+        keywords: Union[str, List[str]],
+        title: Optional[str] = None,
+        scrape_websites: bool = True,
+        ultra_mode: bool = True,
+        max_results: Optional[int] = None,
+        webhook_url: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Create an asynchronous Google Maps background scraping job.
+        
+        Args:
+            keywords: Single search string or list of query strings
+            title: Custom label for the scraping task
+            scrape_websites: Automatically crawl discovered websites for emails and social links
+            ultra_mode: Enable multi-point grid scanning for up to 3x more listings
+            max_results: Optional cap on listings per query
+            webhook_url: Optional webhook URL to notify when completed
+            
+        Returns:
+            Dictionary containing job_id and initial job status.
+        """
+        if isinstance(keywords, str):
+            keywords = [keywords]
+
+        payload = {
+            "keywords": keywords,
+            "scrape_websites": scrape_websites,
+            "ultra_mode": ultra_mode
+        }
+        if title:
+            payload["title"] = title
+        if max_results:
+            payload["max_results"] = max_results
+        if webhook_url:
+            payload["webhook_url"] = webhook_url
+
+        return self._client._request("POST", "/maps/jobs", json=payload)
+
+    def list_jobs(self, page: int = 1, limit: int = 20) -> Dict[str, Any]:
+        """
+        List your recent Google Maps scraping jobs with status and progress.
+        """
+        params = {"page": page, "limit": limit}
+        return self._client._request("GET", "/maps/jobs", params=params)
+
+    def get_job(self, job_id: str) -> Dict[str, Any]:
+        """
+        Retrieve live progress and metadata for a specific scraping job.
+        """
+        return self._client._request("GET", f"/maps/jobs/{job_id}")
+
+    def download_csv(self, job_id: str) -> bytes:
+        """
+        Download the full CSV dataset for a completed or paused job.
+        """
+        return self._client._request("GET", f"/maps/jobs/{job_id}/download", raw_bytes=True)
+
+    def pause_job(self, job_id: str) -> Dict[str, Any]:
+        """Pause an active Google Maps scraping job."""
+        return self._client._request("POST", f"/maps/jobs/{job_id}/pause")
+
+    def resume_job(self, job_id: str) -> Dict[str, Any]:
+        """Resume a paused Google Maps scraping job."""
+        return self._client._request("POST", f"/maps/jobs/{job_id}/resume")
+
+    def stop_job(self, job_id: str) -> Dict[str, Any]:
+        """Stop/cancel a scraping job and finalize partial results."""
+        return self._client._request("POST", f"/maps/jobs/{job_id}/control")

boltscraper/reviews.py

@@ -0,0 +1,80 @@
+"""
+Google Reviews Scraper Resource
+Extracts all customer reviews, ratings, reviewer metadata, and owner replies without OAuth.
+"""
+
+from typing import List, Union, Optional, Dict, Any
+
+
+class ReviewsResource:
+    def __init__(self, client):
+        self._client = client
+
+    def search(
+        self,
+        place_id: str,
+        max_reviews: int = 500,
+        sort: str = "newest"
+    ) -> Dict[str, Any]:
+        """
+        Synchronously extract customer reviews for a Google Place ID without OAuth.
+        
+        Args:
+            place_id: Google Maps Place ID or listing URL
+            max_reviews: Maximum reviews to extract (up to 5,000+)
+            sort: Sort order ('newest', 'most_relevant', 'highest_rating', 'lowest_rating')
+        """
+        payload = {
+            "place_id": place_id,
+            "max_reviews": max_reviews,
+            "sort": sort
+        }
+        return self._client._request("POST", "/reviews/search", json=payload)
+
+    def create_job(
+        self,
+        place_ids: Union[str, List[str]],
+        max_reviews_per_place: int = 500,
+        sort: str = "newest",
+        webhook_url: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Create an asynchronous batch reviews extraction job.
+        """
+        if isinstance(place_ids, str):
+            place_ids = [place_ids]
+
+        payload = {
+            "place_ids": place_ids,
+            "max_reviews_per_place": max_reviews_per_place,
+            "sort": sort
+        }
+        if webhook_url:
+            payload["webhook_url"] = webhook_url
+
+        return self._client._request("POST", "/reviews/jobs", json=payload)
+
+    def list_jobs(self, page: int = 1, limit: int = 20) -> Dict[str, Any]:
+        """List recent reviews scraping jobs."""
+        params = {"page": page, "limit": limit}
+        return self._client._request("GET", "/reviews/jobs", params=params)
+
+    def get_job(self, job_id: str) -> Dict[str, Any]:
+        """Retrieve progress and metadata for a reviews extraction job."""
+        return self._client._request("GET", f"/reviews/jobs/{job_id}")
+
+    def download_csv(self, job_id: str) -> bytes:
+        """Download reviews CSV export."""
+        return self._client._request("GET", f"/reviews/jobs/{job_id}/download", raw_bytes=True)
+
+    def pause_job(self, job_id: str) -> Dict[str, Any]:
+        """Pause a running reviews scraping job."""
+        return self._client._request("POST", f"/reviews/jobs/{job_id}/pause")
+
+    def resume_job(self, job_id: str) -> Dict[str, Any]:
+        """Resume a paused reviews scraping job."""
+        return self._client._request("POST", f"/reviews/jobs/{job_id}/resume")
+
+    def stop_job(self, job_id: str) -> Dict[str, Any]:
+        """Stop a reviews scraping job."""
+        return self._client._request("POST", f"/reviews/jobs/{job_id}/control")

boltscraper/webhooks.py

@@ -0,0 +1,79 @@
+"""
+Webhooks Resource & Security Verification Helpers
+"""
+
+import hmac
+import hashlib
+from typing import Optional, Dict, Any, Union
+
+
+class WebhooksResource:
+    def __init__(self, client):
+        self._client = client
+
+    def list(self) -> Dict[str, Any]:
+        """List all registered webhook endpoints."""
+        return self._client._request("GET", "/webhooks")
+
+    def create(
+        self,
+        name: str,
+        webhook_url: str,
+        secret: Optional[str] = None,
+        platform: str = "all",
+        send_auto: bool = True
+    ) -> Dict[str, Any]:
+        """
+        Register a new webhook endpoint.
+        
+        Args:
+            name: Friendly label (e.g. 'Production CRM Pipeline')
+            webhook_url: Target destination URL
+            secret: Optional HMAC secret for payload signature verification
+            platform: 'all', 'maps', or 'website'
+            send_auto: Automatically dispatch on job completion
+        """
+        payload = {
+            "name": name,
+            "webhook_url": webhook_url,
+            "platform": platform,
+            "send_auto": send_auto
+        }
+        if secret:
+            payload["secret"] = secret
+        return self._client._request("POST", "/webhooks", json=payload)
+
+    def update(self, webhook_id: str, **kwargs) -> Dict[str, Any]:
+        """Update an existing webhook configuration."""
+        return self._client._request("PUT", f"/webhooks/{webhook_id}", json=kwargs)
+
+    def delete(self, webhook_id: str) -> Dict[str, Any]:
+        """Remove a webhook endpoint."""
+        return self._client._request("DELETE", f"/webhooks/{webhook_id}")
+
+    @staticmethod
+    def verify_signature(
+        raw_body: Union[str, bytes],
+        signature_header: str,
+        secret: str
+    ) -> bool:
+        """
+        Verify incoming webhook HMAC SHA-256 signature from the X-Bolt-Signature header.
+        
+        Args:
+            raw_body: Exact raw request body as bytes or string
+            signature_header: Value of the 'X-Bolt-Signature' HTTP header (e.g. 'sha256=abcdef...')
+            secret: Your configured webhook secret key
+            
+        Returns:
+            True if the signature is valid, False otherwise.
+        """
+        if not signature_header or not signature_header.startswith("sha256="):
+            return False
+
+        if isinstance(raw_body, str):
+            raw_body = raw_body.encode("utf-8")
+
+        expected_sig = signature_header.split("sha256=")[1]
+        computed_sig = hmac.new(secret.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
+        return hmac.compare_digest(expected_sig, computed_sig)

boltscraper/website.py

@@ -0,0 +1,67 @@
+"""
+Website Scraper Resource
+Extracts direct business emails, phone numbers, and social links from company domains.
+"""
+
+from typing import List, Union, Optional, Dict, Any
+
+
+class WebsiteResource:
+    def __init__(self, client):
+        self._client = client
+
+    def scrape(self, url: str) -> Dict[str, Any]:
+        """
+        Synchronously scrape a single website domain for emails, phone numbers, and social media URLs.
+        Automatically crawls subpages (/contact, /about, /team, etc.).
+        
+        Args:
+            url: Company website URL (e.g. 'https://stripe.com')
+            
+        Returns:
+            Dictionary containing extracted emails, phones, and social profile links.
+        """
+        payload = {"url": url}
+        return self._client._request("POST", "/website/scrape", json=payload)
+
+    def create_job(
+        self,
+        urls: Union[str, List[str]],
+        name: Optional[str] = None,
+        webhook_url: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Create an asynchronous batch website extraction task for up to 10,000 URLs.
+        
+        Args:
+            urls: Single domain string or list of website URLs
+            name: Optional descriptive label for the task
+            webhook_url: Optional callback URL when task completes
+        """
+        if isinstance(urls, str):
+            urls = [urls]
+
+        payload = {"urls": urls}
+        if name:
+            payload["name"] = name
+        if webhook_url:
+            payload["webhook_url"] = webhook_url
+
+        return self._client._request("POST", "/website/jobs", json=payload)
+
+    def list_jobs(self, page: int = 1, limit: int = 20) -> Dict[str, Any]:
+        """List recent website contact enrichment jobs."""
+        params = {"page": page, "limit": limit}
+        return self._client._request("GET", "/website/jobs", params=params)
+
+    def get_job(self, job_id: str) -> Dict[str, Any]:
+        """Retrieve progress and metadata for a website scraping job."""
+        return self._client._request("GET", f"/website/jobs/{job_id}")
+
+    def download_csv(self, job_id: str) -> bytes:
+        """Download full website contact enrichment CSV dataset."""
+        return self._client._request("GET", f"/website/jobs/{job_id}/download", raw_bytes=True)
+
+    def stop_job(self, job_id: str) -> Dict[str, Any]:
+        """Stop/cancel a website scraping job."""
+        return self._client._request("POST", f"/website/jobs/{job_id}/control")

boltscraper-1.0.0.dist-info/METADATA

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: boltscraper
+Version: 1.0.0
+Summary: Official Python SDK for Bolt Scraper — Extract business leads, reviews, and direct emails from Google Maps and websites without bans.
+Author-email: Bolt Scraper Team <support@boltscraper.com>
+License: MIT
+Project-URL: Homepage, https://boltscraper.com
+Project-URL: Documentation, https://boltscraper.com/api/
+Project-URL: Repository, https://github.com/boltscraper/google-maps-scraper-python
+Project-URL: Bug Tracker, https://github.com/boltscraper/google-maps-scraper-python/issues
+Project-URL: Free API Key, https://app.boltscraper.com
+Keywords: google-maps-scraper,google-maps-api,lead-generation,python-scraper,google-places-api,email-extractor,google-reviews-scraper,local-seo,b2b-leads,web-scraping
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.0
+Dynamic: license-file
+Dynamic: requires-python
+
+# Google Maps Scraper Python API (`boltscraper`)
+
+[![PyPI version](https://img.shields.io/pypi/v/boltscraper.svg?color=ff4747)](https://pypi.org/project/boltscraper/)
+[![Python versions](https://img.shields.io/pypi/pyversions/boltscraper.svg)](https://pypi.org/project/boltscraper/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Free Tier](https://img.shields.io/badge/Free%20Credits-1%2C000%20Leads%2Fmo-green.svg)](https://app.boltscraper.com)
+
+The official Python SDK for **[Bolt Scraper](https://boltscraper.com)** — fast, proxy-free, cloud-native data extraction for **Google Maps listings**, **Google customer reviews**, and **company websites**.
+
+Extract **60+ business attributes** (names, phones, direct emails, social profiles, hours, ratings, coordinates) without browser automation overhead, CAPTCHA hassles, or IP bans.
+
+---
+
+## Why Developers Use `boltscraper`
+
+| Feature | Selenium / BeautifulSoup | Google Places API (New) | Bolt Scraper Python SDK |
+| :--- | :--- | :--- | :--- |
+| **Speed & Setup** | Slow browser overhead | Complex GCP console setup | **5 lines of Python code** |
+| **IP Bans & CAPTCHAs** | Frequent blocks & CAPTCHAs | None (metered API) | **0% bans** (automatic proxy rotation) |
+| **Direct Emails** | Requires custom scraping | **Not offered (0% returned)** | **Included** (crawls company websites) |
+| **Customer Reviews** | DOM fragile / breaks | Max 5 reviews only | **Extracts all 5,000+ reviews** |
+| **Data Storage** | Unstructured HTML | 30-day cache ban | **100% owned indefinitely** |
+| **Pricing** | Proxy costs ($50+/mo) | **$32 – $65+ per 1k requests** | **$0 Free tier** ($0.38 / 1k on paid) |
+
+---
+
+## Installation
+
+```bash
+pip install boltscraper
+```
+
+Requires Python 3.8+.
+
+---
+
+## Quickstart
+
+Get your free API key at **[app.boltscraper.com](https://app.boltscraper.com)** (includes 1,000 free lead credits every month).
+
+```python
+from boltscraper import BoltScraper
+
+# Initialize client (or set BOLTSCRAPER_API_KEY environment variable)
+client = BoltScraper(api_key="bs_live_YOUR_API_KEY")
+
+# 1. Real-time Google Maps search (~2-4 seconds)
+results = client.maps.search("Coffee shops in Seattle", page=1)
+
+print(f"Found {results['pagination']['total_results']} places:")
+for place in results["data"]:
+    print(f"Name:    {place['Name']}")
+    print(f"Phone:   {place['Phone']} ({place['Phone Type']})")
+    print(f"Website: {place['Website']}")
+    print(f"Rating:  {place['Average Rating']} ({place['Review Count']} reviews)")
+    print("-" * 40)
+```
+
+---
+
+## Core Capabilities & Examples
+
+### 1. Synchronous Real-time Maps Search
+Perfect for search bars, AI agent tool calling, and live user queries. Returns instant JSON without background polling:
+
+```python
+response = client.maps.search(
+    keyword="Dentists in Austin, TX",
+    page=1,
+    hl="en"
+)
+
+for lead in response["data"]:
+    print(lead["Name"], lead["Full Address"], lead["Coordinates"])
+```
+
+### 2. Large-Scale Asynchronous Batch Jobs
+Scrape entire cities or hundreds of queries with automatic website email enrichment and Ultra Mode:
+
+```python
+# Launch background scraping job
+job = client.maps.create_job(
+    keywords=["Roofers in Miami, FL", "Solar contractors in Miami, FL"],
+    title="Miami Home Services",
+    scrape_websites=True,   # Crawls company websites for direct emails & socials
+    ultra_mode=True,        # Multi-point grid scan for up to 3x more results
+    webhook_url="https://your-crm.com/api/webhooks/bolt"
+)
+
+job_id = job["job_id"]
+print(f"Started job: {job_id}")
+
+# Check status
+status = client.maps.get_job(job_id)
+print(f"Status: {status['status']} — Extracted: {status['total_leads']} leads")
+
+# Download CSV dataset upon completion
+csv_bytes = client.maps.download_csv(job_id)
+with open("miami_leads.csv", "wb") as f:
+    f.write(csv_bytes)
+```
+
+### 3. Google Reviews Extraction (Without OAuth)
+Bypass Google's 5-review API limitation and extract all customer reviews, ratings, reviewer levels, and owner responses:
+
+```python
+# Synchronously extract up to 5,000+ reviews for any Google Place ID
+reviews_data = client.reviews.search(
+    place_id="ChIJb8Jg9q-1RIYRAxvq_mZ0gXY",
+    max_reviews=500,
+    sort="newest"  # 'newest', 'most_relevant', 'highest_rating', 'lowest_rating'
+)
+
+for review in reviews_data.get("reviews", []):
+    print(f"★ {review['rating']} by {review['reviewer_name']}")
+    print(f"Text: {review['text']}")
+    print(f"Date: {review['date']}")
+```
+
+### 4. Website Email & Social Link Enrichment
+Turn raw domain lists into enriched B2B contact lists:
+
+```python
+# Instant single-domain enrichment (crawls /contact, /about, /team subpages)
+company = client.website.scrape("https://example.com")
+
+print("Direct Emails:", company.get("emails", []))
+print("Phone Numbers:", company.get("phones", []))
+print("Social Links: ", company.get("socials", {}))
+```
+
+### 5. Webhook Signature Verification
+Verify incoming webhook payloads with HMAC SHA-256 to ensure authenticity:
+
+```python
+from boltscraper import WebhooksResource
+
+# In your FastAPI / Flask / Django webhook handler:
+is_valid = WebhooksResource.verify_signature(
+    raw_body=request.body,
+    signature_header=request.headers.get("X-Bolt-Signature"),
+    secret="YOUR_WEBHOOK_SECRET"
+)
+
+if not is_valid:
+    return "Invalid signature", 401
+```
+
+---
+
+## 60+ Extracted Data Points
+
+Each Google Maps listing returns comprehensive, production-ready structured data:
+
+* **Identity**: Business Name, Category, Sub-categories, Google Category IDs, Place ID, CID, KGMID, Feature ID.
+* **Location**: Full Address, Street Address, City, State, ZIP/Postal Code, Country, Municipality, Latitude, Longitude, Timezone.
+* **Contact**: Formatted Phone, Phone Type (Mobile, Landline, VOIP), International Phone, Phone URI (`tel:`), Website URL, Domain.
+* **Enrichment**: Direct Emails discovered from company websites, Social Media URLs (LinkedIn, Facebook, Instagram, Twitter/X, YouTube).
+* **Reputation & Hours**: Star Rating, Total Reviews Count, Review URL, Operating Status (Open, Closed), Opening Hours (Monday–Sunday schedules).
+* **Media Assets**: Logo URL, Main Photo URL, Photos Page URL, Favicon URL.
+
+---
+
+## Rate Limits & Error Handling
+
+All requests are rate-limited to **60 requests per minute** per API key. The SDK automatically handles `429 Too Many Requests` responses with exponential backoff using the server's `Retry-After` header.
+
+```python
+from boltscraper.exceptions import (
+    AuthenticationError,
+    QuotaExceededError,
+    RateLimitError,
+    BoltScraperError
+)
+
+try:
+    results = client.maps.search("Plumbers Denver")
+except AuthenticationError:
+    print("Invalid API key. Check https://app.boltscraper.com")
+except QuotaExceededError:
+    print("Monthly quota exhausted. Upgrade plan at https://boltscraper.com/pricing")
+except RateLimitError as e:
+    print(f"Rate limited. Reset in {e.retry_after} seconds.")
+except BoltScraperError as e:
+    print(f"API Error ({e.status_code}): {e.message}")
+```
+
+---
+
+## Documentation & Resources
+
+* **Documentation Portal**: [https://boltscraper.com/api/](https://boltscraper.com/api/)
+* **In-Depth Guides & Tutorials**: [https://boltscraper.com/blogs/](https://boltscraper.com/blogs/)
+* **Pricing Calculator**: [Google Places API Cost Calculator](https://boltscraper.com/tools/google-places-api-pricing-calculator/)
+* **Sign Up (1,000 Free Leads/mo)**: [https://app.boltscraper.com](https://app.boltscraper.com)
+
+---
+
+## License
+
+MIT License. Copyright (c) 2026 Bolt Scraper.

boltscraper-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+boltscraper/__init__.py,sha256=C4oA2VKRHn-A_HHaXEr6cNgwmtLPM2uXsVrK8grqzb4,585
+boltscraper/client.py,sha256=TdgG5PIXLsVDbxksrtDOVH3jK_GImgkmH_af2uXqNV0,5787
+boltscraper/exceptions.py,sha256=reSVw8uSgQRWRu7yo-3aVf3RobCjd7zmD2yQNS1Xr2M,1221
+boltscraper/maps.py,sha256=XfY8sKql5xlXJ75k2IiXRv0ijfQJ9BWvfRMNCNvaX1c,3809
+boltscraper/reviews.py,sha256=zr0f_chHMQjM1ZrHSzEDlvzOk0iad5mx_f4X1znmyDs,2840
+boltscraper/webhooks.py,sha256=4P-xn2iOMX0GVKVchZoTdN7hUj_7A-bV8Too1u4b7lQ,2641
+boltscraper/website.py,sha256=74BlOQn81qMOfWI4wRRE3gVzC7fcDnQi_TQRvDzOXTs,2471
+boltscraper-1.0.0.dist-info/licenses/LICENSE,sha256=m0WjlGcPKwD5Afv6_6vbFpie56LOufldgXLS5QS12bM,1095
+boltscraper-1.0.0.dist-info/METADATA,sha256=nY9IYZqKBBkNsofqZJ3phwwFuVKR2TfNt374S7hExoA,9068
+boltscraper-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+boltscraper-1.0.0.dist-info/top_level.txt,sha256=d8DeYv2GoUSYzjtZCD_SduSZo2EOriZhgUmDgv51Djo,12
+boltscraper-1.0.0.dist-info/RECORD,,

boltscraper-1.0.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
+

boltscraper-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bolt Scraper (https://boltscraper.com)
+
+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.

boltscraper-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+boltscraper