gmaps-extractor Documentation

gmaps-extractor is a Python library that extracts business data from Google Maps at scale. Give it an area and a category, and it returns every matching business with details, reviews, and contact information.

v2.0.0 -- Direct HTTP requests (no server needed), async support, streaming, event system, structured logging.

New here? Install the package, set up a proxy, and run your first collection:

What's New in v2.0.0

No server required -- Requests go directly to Google Maps via httpx. FastAPI is now optional.
Async API -- async_collect_v2() and stream_collect_v2() for non-blocking I/O.
Event system -- Lifecycle callbacks for monitoring collection progress.
Structured logging -- Uses Python's logging module instead of print().
Lightweight core -- Only requires httpx. FastAPI/uvicorn are optional extras.
570+ tests -- Comprehensive test suite with CI/CD.

See the Migration Guide for upgrading from v1.x.

Documentation

Article	Description
Installation	Install from PyPI or source
Prerequisites & Setup	Proxy requirements, cookies
Quick Start	Get running in 5 minutes
Python Library API	`GMapsExtractor`, `collect()`, `collect_v2()`, async methods
Configuration	Constructor args, environment variables, GMapsSettings
CLI Reference	`gmaps-collect-v2`, `gmaps-collect`, `gmaps-enrich-reviews`
Output Format	JSON structure, CSV columns, JSONL streaming
Subdivision Mode	Break large areas into neighborhoods for better coverage
Resuming Collections	Checkpoint/resume in V2
Rate Limiting & Performance	Adaptive delays, worker tuning, cell sizes
Error Handling	Exceptions, error patterns
Troubleshooting	Common problems and fixes
Examples	Complete working examples for Python and CLI
Known Limitations	Constraints and caveats
Migration Guide	Upgrading from v1.x to v2.0.0
Changelog	Version history

Package Info

PyPI name: gmaps-extractor
Import name: gmaps_extractor
Version: 2.0.0
Python: 3.9+
License: MIT