google-maps-scraper-kit

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkDeclared5 observations
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

for host in ("localhost", "127.0.0.1", "10.0.0.5", "192.168.1.1", "169.254.169.254", "::1", ""):

req = scrape.urllib.request.Request("http://8.8.8.8/")

self.assertIsNone(handler.redirect_request(req, None, 302, "Found", {}, "http://127.0.0.1/admin"))

self.assertEqual(scrape._fetch_html(f"http://127.0.0.1:{srv.server_port}/"), "")

with mock.patch.object(scrape, "BASE", f"http://127.0.0.1:{srv.server_port}"), \

with mock.patch.object(scrape, "BASE", f"http://127.0.0.1:{srv.server_port}"), \

**Whole-city runs:** when the user says all, every or entire city, or a run returns about 120 rows

Audit 0.4.1 · source sha 2c2b01f8fe5e · 31 Oct 2026Report an issue or request a re-scan

• PublisherMahanaicoach GitHub userOwner of the repository this skill is read from
• Source folderMahanaicoach/google-maps-scraper-kitThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdict2c2b01f8fe5eA new audit runs when the source changes
• Repository statusNot archivedPushed today
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Google Maps scraper for lead generation. Turns a business type and a place into a clean CSV of local businesses by driving the gosom/google-maps-scraper engine, running locally in Docker as a REST API on localhost:8080.…

---
name: google-maps-scraper
description: Google Maps scraper for lead generation. Turns a business type and a place into a clean CSV of local businesses by driving the gosom/google-maps-scraper engine, running locally in Docker as a REST API on localhost:8080. Returns 8 lead fields by default (name, phone, email, website, category, address, rating and review count), plus optional social profiles (Instagram, Facebook, LinkedIn, TikTok, YouTube, X), row filters such as businesses without a website, or all 36 raw fields. Use when the user wants a lead list, "a list of [businesses] in [place]", local business data, contact enrichment for places (emails, phones, socials), or a whole-city run past Google's ~120 results per search. Do not use for scraping Instagram, TikTok, YouTube, X or any other social media platform directly.
---

# Google Maps Scraper

Turn a business type and a location into clean lead rows by driving the local engine's job API.

## Mental model
The engine (gosom/google-maps-scraper) runs as a local Docker container with a REST API at
`http://localhost:8080`. It has no auth, so it stays bound to localhost. A scrape is an **async job**:
create it, poll until it is done, then download a CSV. One job can run many keywords. Each result has
up to **36 raw fields**.

## Step 0: Check the engine is running
```bash
curl -s http://localhost:8080/api/v1/jobs >/dev/null 2>&1 && echo UP || echo DOWN
```
If `DOWN` and the working folder has `docker-compose.yml` (the full kit): run `docker compose up -d`
there, wait ~10s, and retry. No `docker-compose.yml`: see the next paragraph. If Docker is not
installed, point the user to
[SETUP.md](https://github.com/Mahanaicoach/google-maps-scraper-kit/blob/master/SETUP.md).

**Skill installed on its own?** `npx skills add` copies this file only, without
`docker-compose.yml` or `scripts/`. If the working folder has no `docker-compose.yml`, start the same
pinned engine with Docker alone:
```bash
docker run -d --name gmaps-scraper --restart unless-stopped -p 127.0.0.1:8080:8080 \
  -v gmaps_data:/gmapsdata \
  gosom/google-maps-scraper:v1.18.1@sha256:e205c02913c5a69c16fc2094b8e5b194a2f655166d2c1126d50548d216e6b1b2 \
  -web -data-folder /gmapsdata -c 4
```
The digest fixes the image to one exact build of the v1.18.1 release.

Without `scripts/scrape.py`, run Steps 1 to 3 below with `curl`. They need nothing but Docker.
The script-only features are then missing: socials, `--tech`, `--grid`, geocoding, the email crawl
and the 8-column cleanup. Set `email: true` in the job body, strip the CSV to the 8 lead fields
yourself, and if the user wants those features, point them to the README's Option A (the full kit).
This bare engine lacks the kit proxy's Host and Origin checks, so a web page in the user's browser
could reach it. Tell the user once, and offer `docker stop gmaps-scraper` when the scrape is done.

## Step 1: Create a job (`POST /api/v1/jobs`)
**Required fields. The API returns `422` without them:**
- `keywords`: array of search strings. **Bake the location into each term**: `"plumbers in Denver CO"`.
- `lat`, `lon`: **strings**, the city's coordinates: `"39.7392"`, `"-104.9903"`.
- `max_time`: integer **seconds**, the job's wall-clock limit, e.g. `300`. The API stores it as
  nanoseconds internally, but you always send seconds.
- `name`: any label for the job, e.g. `"job"` (`422 missing name` without it).
- `lang`: the 2-letter interface language, `"en"` (`422 missing lang` without it; `"eng"` is `invalid lang`).

**Recommended fields:**
- `depth` (default 10): how far to scroll, so roughly how many listings per keyword. Start at `5`.
- `zoom` `15` (city level), `radius` `10000` (meters), `fast_mode` `false`.
- **`email` `true`** only in this raw curl flow, where it is the only way to get emails. The engine
  then visits every website in a browser, which is slow and misses many. `scripts/scrape.py` keeps it
  `false` and crawls the websites itself, faster and with more hits, so prefer the script.

```bash
curl -s -X POST http://localhost:8080/api/v1/jobs \
  -H "Content-Type: application/json" \
  -d '{"name":"job","keywords":["coffee shops in Austin TX"],"lang":"en","zoom":15,
       "lat":"30.2672","lon":"-97.7431","fast_mode":false,"radius":10000,
       "depth":5,"email":true,"max_time":300}'
# → {"id":"<uuid>"}   (HTTP 201; note: lowercase "id")
```

> **Handle two things on every scrape:**
> 1. **Emails: on by default** (the script's crawl, or `email:true` on the raw API). Turn them off only if the user wants a fast run.
> 2. **Socials: ask first.** Before creating the job, ask the user once whether they also want
>    Instagram, Facebook and LinkedIn profiles (see "Social profiles" below). Never skip the question silently.

## Step 2: Poll until done (`GET /api/v1/jobs/{id}`)
The response field is `"Status"` (capital S). It moves from `working` to `ok` (success) or `failed`.

> **Harness rule:** the Bash tool **blocks foreground `sleep`**. Run the poll loop as a
> **background** Bash command (`run_in_background: true`) and read its output file when notified.
> Never poll with a foreground `sleep`.

Background poll snippet. It parses the value safely: match up to the closing quote, do not anchor on `$`.
```bash
ID="<uuid>"   # only the id from the POST response in Step 1
case "$ID" in ""|*[!0-9a-f-]*) echo "not a job id"; exit 1;; esac
for i in $(seq 1 40); do
  S=$(curl -s "http://localhost:8080/api/v1/jobs/$ID" | grep -oE '"Status":"[^"]*"' | head -1 | cut -d'"' -f4)
  echo "status=$S"
  [ "$S" = ok ] && { echo DONE; break; }
  [ "$S" = failed ] && { echo FAILED; break; }
  sleep 15
done
[ "$S" = ok ] || echo "NOT DONE after 10 min (status=$S): see Troubleshooting"
```

## Step 3: Download and parse (`GET /api/v1/jobs/{id}/download`)
```bash
ID="<uuid>"   # the same id as Step 2; each command runs in a fresh shell
case "$ID" in ""|*[!0-9a-f-]*) echo "not a job id"; exit 1;; esac
curl -sf "http://localhost:8080/api/v1/jobs/$ID/download

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

1. 2026-10-31
   ✓SAFE B 89 / 100

   first audit · source 2c2b01f8fe5e

Questions about google-maps-scraper-kit

• github.com/Mahanaicoach/google-maps-scraper-kit — the audited source at commit 2c2b01f8fe5e and every finding aboveObserved · 31 Oct 2026

Spotted something wrong? Report a correction · Methodology