gmapsscraper-sdk 0.1.0

Official Python SDK for the gmapsscraper.io API — scrape Google Maps business data: names, emails, phones, websites, ratings, reviews.

gmapsscraper

Official Python SDK for the 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

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.

Quick start

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):

# 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:

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
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 (also great as LLM context)
• 📦 Node.js SDK — npm install @gmapsscraper/sdk
• 🤖 Claude / AI agent skills — use gmapsscraper from Claude Code and other agents
• 🧩 Chrome extension — scrape Google Maps without code
• ✍️ Blog: Google Maps scraping guides

License

MIT © gmapsscraper.io