# 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 5000) — 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)

## Credits
- Each scrape costs 2 credits
- 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 limit: 1000 requests/day per key
- 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 → wait 60s
- 422: Invalid parameters
- 502: Backend temporarily unavailable

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

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