## Quick Start for AI Agents

Point your agent to: https://gmapsscraper.io/llms.txt
Or install a skill: npx skills add gmapsscraper/google-maps-agent-skills/google-maps-scraper
All skills: https://github.com/gmapsscraper/google-maps-agent-skills

---

# GMaps Scraper API Documentation
# Base URL: https://gmapsscraper.io/api/v1

## Authentication

All requests require a Bearer token:

  Authorization: Bearer gmaps_sk_your_key_here

Get your free API key at: https://gmapsscraper.io/dashboard (API Keys tab)
Free accounts include 10 credits (5 searches).

---

## Endpoints

### POST /api/v1/scrape

Create a new Google Maps scraping job. Costs 2 credits.

Request:

  curl -X POST https://gmapsscraper.io/api/v1/scrape \
    -H "Authorization: Bearer gmaps_sk_your_key_here" \
    -H "Content-Type: application/json" \
    -d '{"keywords":["coffee shop in new york"],"email":true,"depth":2}'

Parameters:

  keywords (required) — Array of search terms, e.g. ["dentist in Austin TX"]
  name (optional) — Job name for reference
  lang (optional) — Language code, default "en"
  zoom (optional) — Map zoom 1-21, default 15
  depth (optional) — Search depth 1-3, default 2. Higher = more results
  lat (optional) — Center latitude (auto-geocoded from keywords if omitted)
  lon (optional) — Center longitude (auto-geocoded from keywords if omitted)
  radius (optional) — Search radius in meters, default 5000
  email (optional) — Extract emails from websites, default false
  fast_mode (optional) — Skip deep website crawling, default true
  max_time (optional) — Max job duration in seconds, default 3600

Response (201 Created):

  {
    "id": "6f0c1af8-3c4e-4742-84bb-590938ae8930",
    "credits_remaining": 8
  }

---

### GET /api/v1/jobs/:id

Check job status. Poll every 10 seconds until status is "complete".

Request:

  curl https://gmapsscraper.io/api/v1/jobs/6f0c1af8-3c4e-4742-84bb-590938ae8930 \
    -H "Authorization: Bearer gmaps_sk_your_key_here"

Response:

  {
    "id": "6f0c1af8-3c4e-4742-84bb-590938ae8930",
    "status": "complete",
    "name": "coffee shop in new york"
  }

Status values: "running", "complete", "failed"

---

### GET /api/v1/jobs/:id/download

Download results as CSV when job is complete.

Request:

  curl https://gmapsscraper.io/api/v1/jobs/6f0c1af8-3c4e-4742-84bb-590938ae8930/download \
    -H "Authorization: Bearer gmaps_sk_your_key_here" \
    --output results.csv

Response: CSV file with columns:
  title, address, phone, website, email, rating, reviews_count,
  category, latitude, longitude, google_maps_url, opening_hours

---

### GET /api/v1/credits

Check your remaining credit balance.

Request:

  curl https://gmapsscraper.io/api/v1/credits \
    -H "Authorization: Bearer gmaps_sk_your_key_here"

Response:

  {
    "credits": 8
  }

---

## Error Codes

  401 — Invalid or missing API key
  402 — Insufficient credits. Purchase more at https://gmapsscraper.io/#pricing
  422 — Invalid request parameters
  429 — Daily request limit exceeded (1000 requests/day per key)
  502 — Scraping backend temporarily unavailable
  500 — Internal server error

Error response format:

  {
    "error": "Human-readable error message"
  }

---

## Rate Limits

  - 1000 requests per day per API key
  - Each scrape job costs 2 credits
  - Status checks and downloads are free (no credit cost)

---

## Complete Example: Scrape → Poll → Download

  # 1. Start a scrape job
  JOB=$(curl -s -X POST https://gmapsscraper.io/api/v1/scrape \
    -H "Authorization: Bearer gmaps_sk_your_key_here" \
    -H "Content-Type: application/json" \
    -d '{"keywords":["plumber in chicago"],"email":true}')

  JOB_ID=$(echo $JOB | jq -r '.id')

  # 2. Poll until complete
  while true; do
    STATUS=$(curl -s https://gmapsscraper.io/api/v1/jobs/$JOB_ID \
      -H "Authorization: Bearer gmaps_sk_your_key_here" | jq -r '.status')
    echo "Status: $STATUS"
    if [ "$STATUS" = "complete" ]; then break; fi
    sleep 10
  done

  # 3. Download results
  curl -s https://gmapsscraper.io/api/v1/jobs/$JOB_ID/download \
    -H "Authorization: Bearer gmaps_sk_your_key_here" \
    --output plumbers_chicago.csv

---

## Tips

- Use multiple keywords in one request for broader coverage (same credit cost)
- Set email: true and depth: 2 for maximum data extraction
- Be specific with location: "dentist in downtown Austin TX" > "dentist in Texas"
- Save your CSV — you can re-process it anytime without spending credits
- Location is auto-geocoded from keywords — no need to provide lat/lon manually

## Pricing

- Free: 10 credits (5 searches)
- Starter: $29/month
- Pro: $79/month
- Advanced: $149/year

Details: https://gmapsscraper.io/#pricing