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)
