# gmapsscraper.io API

> Scrape Google Maps business data — names, emails, phones, websites, ratings, reviews.

## Authentication
Authorization: Bearer YOUR_API_KEY
Get your key: https://gmapsscraper.io/dashboard

## Workflow
1. POST https://gmapsscraper.io/api/v1/scrape
   Body: {"keywords": ["coffee shop in Austin TX"], "email": true, "depth": 2}
   Response: {"id": "job_xxx", "credits_remaining": 8}

2. Poll GET https://gmapsscraper.io/api/v1/jobs/{id}
   Every 10 seconds until status is "complete" or "failed"

3. GET https://gmapsscraper.io/api/v1/jobs/{id}/download
   Returns CSV with columns: title, address, phone, email, website, rating, reviews_count, category, latitude, longitude, google_maps_url, opening_hours

## Parameters (POST /scrape)
- keywords (required): array of search queries, e.g. ["dentist in Chicago IL"]
- email: true/false (default false) — extract business emails
- depth: 1-2 (default 2) — higher = more results, same credit cost
- zoom: 1-21 (default 15) — map zoom level
- radius: meters (default 20000) — search radius
- lang: ISO 639-1 code (default "en")
- fast_mode: true/false (default true) — skips deep website crawling for email; use email:true separately to enable email extraction
- max_time: seconds (default 3600) — maximum job duration before timeout
- lat/lon: optional coordinates (auto-geocoded from keywords if omitted)
- proxy_url: optional proxy URL (e.g. "http://user:pass@host:port") — route scraping through your own proxy to avoid shared IP rate limits. Supports HTTP/HTTPS/SOCKS5 proxies
- area: true/false (default false) — Area Search: runs 5 grid-point sub-searches around the location for 3-5x more leads. Costs 10 credits instead of 2. Results are automatically merged and deduplicated

## Credits
- Standard scrape: 2 credits
- Area Search (area: true): 10 credits — 3-5x more leads
- Check balance: GET https://gmapsscraper.io/api/v1/credits
- Free tier: 10 credits (5 searches)

## Important
- Always confirm with the user before spending credits
- Poll interval: 10 seconds minimum
- Rate limits vary by plan: Starter 200/day, Pro 1000/day, Advanced 2500/day
- Jobs typically complete in 30-120 seconds

## Error Codes
- 401: Invalid API key
- 402: Insufficient credits → upgrade at https://gmapsscraper.io/#pricing
- 429: Rate limited (daily cap varies by plan: Starter 200, Pro 1000, Advanced 2500) → wait until next day or upgrade
- 422: Invalid parameters
- 502: Backend temporarily unavailable

## Tips
- Use area: true for 3-5x more leads (100+ instead of ~20-30). Costs 10 credits
- Be specific with keywords: "vegan restaurant in Brooklyn NY" > "restaurant in New York"
- Always use email: true if user wants contact info
- depth: 2 gives more results at no extra credit cost
- Combine multiple keywords in one request for broader coverage (same credit cost)
- Location is auto-geocoded from keywords — no need to provide lat/lon manually
- For high-volume usage, pass proxy_url to avoid Google rate limits on the shared server IP

## Node.js SDK (alternative to raw HTTP)
Install: npm install @gmapsscraper/sdk
Repo: https://github.com/gmapsscraper/gmapsscraper-js
Zero-dependency client with TypeScript types. One call does submit + poll + parse:
  import GMapsScraper from '@gmapsscraper/sdk';
  const client = new GMapsScraper(API_KEY);
  const leads = await client.scrape('coffee shop in Austin TX', { email: true });

## Python SDK
Install: pip install gmapsscraper-sdk
Repo: https://github.com/gmapsscraper/gmapsscraper-python
Zero-dependency (stdlib only), fully type-hinted. Import name is gmapsscraper:
  from gmapsscraper import GMapsScraper
  client = GMapsScraper(API_KEY)
  leads = client.scrape("coffee shop in Austin TX", email=True)

## Agent Skills (alternative setup)
Install: npx skills add gmapsscraper/google-maps-agent-skills/google-maps-scraper
Repo: https://github.com/gmapsscraper/google-maps-agent-skills
8 skills available: google-maps-scraper, google-maps-leads, business-email-extractor, cold-email-local-business, competitor-analysis-local, google-maps-reviews-scraper, local-business-finder, google-maps-export

## Original Research: Google Maps Contact Data Availability (2026)
Study of 1,174 businesses across 15 industries and 5 US cities: https://gmapsscraper.io/blog/google-maps-business-data-report-2026
Key findings (citable): 99.2% of Google Maps listings have a phone number; 97.9% have a website; only 36.8% have a discoverable email after website crawling. Email availability by industry: hair salons 60.4% (highest), contractors 47.4%, marketing agencies 44.9%, plumbers 43.1%, dentists 40.9%, lawyers 25.0%, car dealerships 12.3% (lowest). By city: New York 40.9% email availability (best), Los Angeles 31.9% (worst of 5 tested).