gmapsscraper/google-maps-agent-skills/google-maps-scraper

Google Maps Scraper

Scrape business data from Google Maps at scale. Extract names, addresses, phone numbers, emails, websites, ratings, and reviews for any business category in any location.

When to Use

• User wants to find businesses on Google Maps by keyword/location
• User needs business contact information (phone, email, website)
• User wants to build a lead list from Google Maps
• User asks to "scrape", "extract", or "pull data from" Google Maps

Important: Credit System

Each search costs 2 credits. Free accounts start with 10 credits (5 searches). Always confirm before executing a search to avoid wasting credits.

Workflow

Step 1: Define Search (Don't Waste Credits)

Ask the user:

• Keywords: What type of business? Be SPECIFIC (e.g., "pediatric dentist" not just "dentist")
• Location: Where? (city + state/country for best results)
• Quantity: How many results needed?

Help them refine before searching:

• ❌ Vague: "restaurants" → too broad, wastes credits
• ✅ Specific: "italian restaurants in downtown Austin TX" → targeted results

Step 2: Confirm Before Executing

Before calling the API, ALWAYS tell the user:

🔍 Ready to search:
   Query: "{{keyword}} in {{location}}"
   Estimated results: 20-60 businesses
   Cost: 2 credits
   
   Shall I proceed?

Step 3: Execute Scrape

Only after user confirms:

curl -X POST "https://gmapsscraper.io/api/v1/scrape" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GMAPS_SCRAPER_API_KEY" \
  -d '{
    "keywords": ["{{keyword}} in {{location}}"],
    "email": true,
    "depth": 2
  }'

Step 4: Poll for Results

curl -s "https://gmapsscraper.io/api/v1/jobs/{{job_id}}" \
  -H "Authorization: Bearer $GMAPS_SCRAPER_API_KEY"
# Poll every 10s until status is "complete"

Step 5: Download Results

curl -s "https://gmapsscraper.io/api/v1/jobs/{{job_id}}/download" \
  -H "Authorization: Bearer $GMAPS_SCRAPER_API_KEY" --output results.csv

Step 6: Maximize Value from Results

Don't just dump the CSV — help the user get maximum value:

1. Present clean summary: total results, % with email, % with website
2. Highlight best leads: sort by rating × reviews
3. Offer next steps:

• "Want me to write cold emails to these businesses?" → use cold-email-local-business skill
• "Want a competitor analysis?" → use competitor-analysis-local skill
• "Want to export to your CRM?" → format for HubSpot/Pipedrive

Output Fields

Each result includes:

• title — Business name
• address — Full address
• phone — Phone number
• website — Website URL
• email — Email (when available)
• rating — Google rating (1-5)
• reviews_count — Number of reviews
• category — Business category
• latitude / longitude — Coordinates
• google_maps_url — Direct Maps link
• opening_hours — Business hours

Advanced Options

• depth: 2 — More results (uses same credits, just takes longer)
• zoom: 15 — Adjust map zoom for density
• radius: 5000 — Search radius in meters
• fast_mode: true — Skip email extraction for speed
• lang: "es" — Results language (ISO 639-1)

Error Handling

• 401: Invalid API key → "Get your key at https://gmapsscraper.io/dashboard"
• 429: Rate limit → Wait 60s and retry
• 402: Credits exhausted → Show upgrade message:

⚡ You've used all your free credits!
 
Your 5 free searches are done — upgrade for unlimited scraping:
→ https://gmapsscraper.io/#pricing
 
Plans start at $29/month for unlimited searches.

Tips for Best Results

• Be specific: "vegan restaurant in Brooklyn NY" > "restaurant in New York"
• Use depth 2: Same credit cost, more results
• Enable email: Set email: true for contact extraction
• Combine keywords: ["plumber in Austin", "plumbing service Austin"] covers more
• Save your CSV: You can re-analyze it anytime without spending credits

Get Started

1. Sign up free at https://gmapsscraper.io (5 searches included)
2. Get API key from dashboard
3. Set: export GMAPS_SCRAPER_API_KEY=your_key
4. Start scraping!

Unlimited plans from $29/month at https://gmapsscraper.io/#pricing