⚡ Fast & Cheap ($1.20/1k): Monitor & scrape Google Maps contributor reviews, profiles & Local Guide histories. Paste any Place URL, query or contributor link for ratings & photos.
HTTP Request & Wire-Byte Proxy Accounting (src/contributor_scraper.py): Attached run_ctx to HttpContributorScraper with _inc() and _account_response() to record accurate requests_total, sessions_used, session_rotations, retries, challenges, challenge_codes.* (http_403, http_429, http_407, soft_block), and incremental wire-byte proxy_mb across all GET/POST/shortlink/MAS RPC calls.
Canonical Run Attributes (src/__main__.py): Populated proxy_country, exit_code=0, and stop_reason="budget_limit_reached" across run.start and run.end, and restored the working public Local Guide prefill in .actor/INPUT_SCHEMA.json.
SDK Upgrade: Upgraded bundled wheel to unitbytes_sdk-1.3.6-py3-none-any.whl.
Verification: 86/86 pytest unit and live integration tests passing.
[1.0.53] - 2026-10-26
🛡️ Rotating-Proxy MAS Token Resilience, Log Sanitization & Shutdown Guards
Rotating-Proxy MAS Token/IP Mismatch Retry (/locationhistory/preview/mas): Distinguished genuinely restricted profiles (data[15] == 3 with data[13] is None) from transient rotating-proxy exit-IP changes between shell_resp and resp_mas (data[15] == 0 or data[13] sub-RPC error codes while prof[0] is None), retrying with a fresh session so public Local Guides are never falsely classified as PRIVATE.
Strict RPC URL & ValidationError Sanitization: Sanitized all URLs logged or raised in _fetch_with_retry / _post_with_retry and sanitized ValidationError warnings in src/__main__.py to guarantee zero internal RPC endpoint or proxy credential leaks.
Safe Event.PERSIST_STATE Shutdown Guard: Guarded persist_state against firing after Actor teardown (_is_initialized == False).
Verification: 85/85 pytest tests and 26/26 live real-data scenarios in scripts/test_user_inputs.py passing.
[1.0.45] - 2026-10-23
🚀 Universal Input Format Support, Keyword Filtering & 10,000 Contributors per Place
10+ Universal Input Formats: Added full parity with unitbytes/google-maps-reviews-tracker across all public Google Maps and Google Search formats:
Place URL (/maps/place/...)
Business Search Query (Katz's Delicatessen New York)
Area / Neighborhood Query (Juhu — auto-resolves top reviewable venue)
Raw Google Place ID (ChIJ... / place_id:ChIJ...)
Google Search #lrd= Modal Link (https://www.google.com/search?q=...#lrd=0x...)
writereview?placeid= Link (https://search.google.com/local/writereview?placeid=ChIJ...)
g.page/r/<CODE>/review Link (https://g.page/r/CeqMy1fnRzUxEBM/review)
General Contributor Profile (/maps/contrib/<ID> or raw 21-digit User ID)
Mobile Share Shortlink (https://maps.app.goo.gl/... resolving to places, /maps/place/.../data=...!1s<review_id>, or contributors)
Contributor Place Review Link (/maps/contrib/<ID>/place/<PLACE_ID>)
Direct /maps/reviews/data=... permalinks, decimal ?cid=... links, raw 0x...:0x... Feature IDs, and business.google.com links containing cid=, ftid=, or placeid= (while safely skipping private merchant dashboard links without a public ID at $0.00 cost).
Server-Side Review Keyword Filter (keyword): Added optional keyword (placeKeyword) filtering via Google's qv9Egd RPC so users can discover and audit only the contributors who mentioned a specific keyword (e.g., "pastrami", "scam", "rude", "manager") on a business listing.
Up to 10,000 Contributors per Business (maxReviewersPerPlace: 10000): Removed the 500 cap and raised maxReviewersPerPlace to 10,000, backed by deep qv9Egd IEEE-754 timestamp cursor pagination and chunked relevance score-band slicing.
Contributor & Local Guide SEO + Input Telemetry: Restored high-converting "Google Maps Contributor & Local Guide Reviews Scraper" title/SEO metadata and emitted structured input_shape telemetry on both run.start and run.end.
[1.0.36] - 2026-10-22
🚀 Paginated Business Place URL Discovery (qv9Egd Cursor Synthesis)
Deep Business Place Reviewer Pagination (/maps/place/...): Upgraded discover_contributors_from_place_url and added scrape_place_reviews_paginated using pure-HTTP qv9Egd (/MapsUgcPostService.ListUgcPosts) Protobuf + IEEE-754 cursor pagination (make_newest_cursor) and batched batchexecute relevance score-band slicing (make_relevance_slice_cursors).
High-Volume Place Review Extraction: Capable of extracting 200–350+ unique reviews and contributor IDs per Place URL in ~12s with zero duplicates and zero browser overhead.
[1.0.23] - 2026-10-22
🚀 1-Step Business Place & Review Permalink Reviewer Discovery
Business Place URL Reviewer Auto-Discovery (/maps/place/...): Users can now paste Google Maps Business Place URLs directly into contributors (or placeUrls / startUrls) to automatically discover the place's reviewers and scrape their full contributor profiles and lifetime review histories in 1 step.
Direct Review Share Link Resolution (/maps/reviews/data=...): Automatically resolves Google Maps review permalinks to the review author's 21-digit contributor_id and audits their complete contributor history.
Zero Charge on Private Profiles (status: "PRIVATE"): Private profiles with zero public data points are no longer charged a profile PPE event ($0.00).
Store Search SEO & Console Prefill: Updated Actor title ("Google Maps Contributor Reviews & Profile History Scraper") and SEO metadata for "google maps contributor" and "google maps reviews" discovery, and set "prefill": 50 on maxReviews.
Sanitized input_shape Telemetry: Populated structured input_shape metrics in BigQuery run telemetry (unitbytes-cloud.telemetry.v_runs).
[1.0.22] - 2026-10-20
🌟 User Experience & Guidance Enhancements
Place URL Auto-Detection & Guidance: Automatically detects when users paste Google Maps business/place listings (/maps/place/... or /maps/search/...) and sets an actionable terminal status message advising them to use a Google Maps Place Reviews scraper instead of showing a generic missing error.
Clean Input Validation Messaging: Replaced raw multiline Pydantic tracebacks on empty/cleared inputs with a friendly, one-line status prompt ("Input validation error: Please provide at least one Google Maps contributor profile URL or numeric User ID in the input.").
Multi-Target Summary Transparency: Terminal status messages for multi-contributor runs now explicitly distinguish active contributors from unavailable ones (e.g. "Completed! Extracted 50 review(s) across 3 contributor(s) (1 unavailable/skipped).").
200-Review Ceiling Transparency: Added informational logging when top Local Guides exceed the 200 single-query ceiling, and aligned the input schema and documentation descriptions.
[1.0.21] - 2026-10-20
🛡️ Billing API Binary Step-Down & Strict Guarding
Binary Step-Down Partial Drain: When a batch charge fails on Apify Cloud due to account spending caps or billing API rejection, safe_charge() now uses binary step-down to drain the exact affordable item count and returns _FallbackChargeResult(event_charge_limit_reached=True, charged_count=drained) to ensure unpaid items are never pushed to the dataset.
Strict Mock & Attribute Guarding: Guarded event_charge_limit_reached evaluation to strictly require a boolean (isinstance(..., bool)), preventing unconfigured test mocks from inadvertently tripping the spending cap.
Billing Test Expansion: Added unit tests covering _FallbackChargeResult handling, local uninitialized error suppression, and binary step-down partial drain.
[1.0.20] - 2026-10-16
🛡️ Production Proxy Isolation & Soft-Block Defense
Cloud Proxy Isolation & Telemetry: Enforced strict proxy isolation so Apify Cloud customer runs (Actor.is_at_home() == True) exclusively utilize Apify Proxy (defaulting to RESIDENTIAL) or user-supplied custom proxies, completely blocking fallback to private MR_SCRAPER_PROXY. Emits accurate proxy_type ("apify_residential", "custom", "custom_mrscraper", "none") to BigQuery telemetry.
Soft IP Block Detection & TCP Reset: Added detection for Google soft IP blocks (HTTP 200 interstitial/CAPTCHA/unusual traffic notices, missing APP_INITIALIZATION_STATE). Automatically rotates Apify residential proxy sessions (session-<hex>) and recreates clean curl_cffi HTTP/TCP pools (init_session()) with up to 2 retries.
Missing/Banned Target Fast-Exit: Genuinely missing, deleted, or banned profiles (HTTP 404 or unparseable URLs) now exit immediately without retries, pushing an empty dataset ([]), billing $0.00, setting an informative terminal status message ("Completed: Target <x> does not exist / is unavailable."), and finishing cleanly with exit_code=0.
Budget Limit Terminal Message Preservation: Fixed status message overwrite bug so event_charge_limit_reached retains its terminal status message ("Completed: Maximum run budget reached ({total_charged} items charged).") upon run termination.
Residential Proxy TLS Verification (verify=False): Configured verify=False on requests.Session (Commandment 13) to eliminate SSL handshake failures across intermediate residential proxy gateways.
[1.0.19] - 2026-10-14
🛡️ Critical PPE Billing & Budget Protection
Budget Cap Enforcement & Zero-Leak Guarantee: Resolved critical exploit where maxTotalChargeUsd or account credit depletion caused Actor.charge() to return event_charge_limit_reached=True without raising an exception, which allowed unbilled items to reach the dataset.
Strict Post-Charge Dataset Gatekeeping: Moved Actor.push_data() to execute strictly after successful PPE billing confirmation. If a budget limit is encountered mid-batch, review items are dynamically sliced to match the exact charged_count.
Clean Run Circuit-Breaker: Added BudgetLimitReachedException to immediately halt the queue orchestrator, abort in-flight workers, set an informative terminal status message, and exit cleanly with exit_code=0.
Truth-in-Telemetry: Telemetry reports actual billed events (total_charged) rather than total pushed items.
[1.0.18] - 2026-10-01
🛡️ Production Hardening & Reliability
Pure HTTP RPC Scraper: Maintained 100% pure HTTP architecture utilizing curl_cffi TLS impersonation and Google Maps MAS ProtoJSON RPC without browser overhead.
PPE Billing Protection: Audited and hardened Actor.charge() logic. Strictly enforces zero review charges on private profiles, profiles with 0 reviews, or missing profiles. Safely wraps all billing events in non-fatal try/except.
Graceful ValidationError Handling: Replaced container aborts/Actor.fail() on invalid inputs with informative Actor.set_status_message() and graceful Actor.exit(exit_code=0).
Proxy 407 & Rate Limit Rotation: Added automated detection and handling of proxy 407 authentication errors, 429 rate limits, and 403 blocks with smooth jittered exponential backoff and seamless session rotation.
Clean Public Logs & Live Telemetry: Eliminated stack traces from public logs (preserving exc_info in DEBUG only) and integrated real-time progress updates via Actor.set_status_message().
Real-Data Verification Suite: Created tests/test_all_inputs.py and tests/test_proxy_rotation.py verifying real extraction against public profiles, private accounts, numeric IDs, and share shortlinks.
[1.0.16] - 2026-09-29
🚀 Developer Experience & Automation
Hyper-Flexible Input Compatibility: Automatically recognizes and normalizes single contributor IDs (contributorId), ID batches (contributorIds), standard Apify request objects (startUrls), and limit aliases (limit, maxItems, maxResultsPerContributor).
Instant Exploration Mode: Defaulted initial trial batches to 10 reviews per contributor for rapid 1-second results and minimal credit usage, while retaining full support for up to 200 reviews.
Database & Webhook Pipelines: Added ready-to-run copy-paste integration recipes for Supabase, PostgreSQL, Make, and Zapier.
Safe Limit Clamping: Automatically normalizes high review limits to the maximum allowable boundary (200) without throwing validation errors.
[1.0.10] - 2026-09-25
✨ Improvements & Branding
Store Branding & Visual Polish: Published new high-resolution widescreen banner and dynamic cache-busting trial action buttons.
Photo Capabilities Clarification: Enhanced documentation detailing review-attached high-resolution photos and added cross-reference to the companion Contributor Photos Scraper.
Safe Review Scaling: Built-in safeguards to reliably deliver maximum allowable review batches (up to 200 items per contributor) with zero data loss or drops.
Support Routing: Updated direct support channels (contact@unitbytes.com) and public Apify Issues tracking.
[1.0.8] - 2026-09-15
🚀 Data Enrichments
Exact Review Timestamps: Added microsecond-precision timestamps (review_timestamp epoch ms) and ISO 8601 UTC dates (review_datetime_utc) for temporal auditing.
Guided Dining & Review Aspects: Extracted reviewer-reported dining mode (Dine-in, Takeout, Delivery), meal types (Brunch, Lunch, Dinner), spend per person, and guided ratings for food, service, and atmosphere.
Place Geolocation Details: Direct clickable Google Maps place permalinks, physical street addresses, city, country, price tiers, and coordinates.
Business Owner Replies: Full extraction of business owner responses with reply text and exact dates.
