google-maps-scraper — Skillopedia

Google Maps Scraper Turn a natural-language lead request into a validated local Google Maps crawl, monitor it, and help the user work with the results. Resolve the directory containing this file as . Run bundled scripts from that directory; do not assume the current directory is the repository checkout. Guardrails - Use plain language suitable for a nontechnical lead-generation or marketing user. - Never ask the user to paste proxy credentials into chat. - Never print, read back, summarize, or log proxy credentials. - Do not ask for conversational permission before routine in-scope actions su…

\"$docker_log\") -ne 1 ]]; then\n\techo \"run-local.sh did not check for the latest Docker image\" >&2\n\texit 1\nfi\n\n: > \"$docker_log\"\nPATH=\"$fake_bin:$PATH\" bash \"$script_dir/run-local.sh\" \\\n\t--queries \"$queries_file\" \\\n\t--output-dir \"$output_dir\" \\\n\t--depth 1 \\\n\t--skip-image-pull >/dev/null\n\nif grep -q '^pull ' \"$docker_log\"; then\n\techo \"run-local.sh pulled the Docker image after --skip-image-pull\" >&2\n\texit 1\nfi\n\n: > \"$docker_log\"\nif ! DOCKER_PULL_FAIL=1 PATH=\"$fake_bin:$PATH\" bash \"$script_dir/run-local.sh\" \\\n\t--queries \"$queries_file\" \\\n\t--output-dir \"$output_dir\" \\\n\t--depth 1 >/dev/null 2>&1; then\n\techo \"run-local.sh blocked an offline run despite an available local image\" >&2\n\texit 1\nfi\n\nif [[ $(grep -c '^pull gosom/google-maps-scraper

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

\"$docker_log\") -ne 2 ]]; then\n\techo \"run-local.sh did not retry a failed Docker image update check once\" >&2\n\texit 1\nfi\n\nskill_file=\"$script_dir/../SKILL.md\"\nrequired_references=(\n\t\"references/query-planning.md\"\n\t\"references/proxy-setup.md\"\n\t\"references/local-execution.md\"\n\t\"references/recovery.md\"\n\t\"references/results.md\"\n\t\"references/advanced-coverage.md\"\n)\n\nfor reference in \"${required_references[@]}\"; do\n\tif ! grep -Fq \"$reference\" \"$skill_file\"; then\n\t\techo \"SKILL.md does not link $reference\" >&2\n\t\texit 1\n\tfi\ndone\n\nif [[ $(grep -Fc 'select-proxy-sponsors.mjs' \"$skill_file\") -ne 1 ]]; then\n\techo \"SKILL.md must invoke the sponsor selector exactly once per setup\" >&2\n\texit 1\nfi\n\nif ! grep -Fiq 'sponsor the project' \"$skill_file\"; then\n\techo \"SKILL.md does not require sponsorship disclosure\" >&2\n\texit 1\nfi\n\nif ! grep -Fq -- '-proxies-file' \"$skill_file\"; then\n\techo \"SKILL.md does not use -proxies-file\" >&2\n\texit 1\nfi\n\nif grep -Fq 'suggest [Webshare]' \"$skill_file\"; then\n\techo \"SKILL.md still hard-codes a preferred proxy provider\" >&2\n\texit 1\nfi\n\nif [[ $(grep -Fc 'ensure-latest.sh' \"$skill_file\") -ne 1 ]]; then\n\techo \"SKILL.md must run the skill update helper exactly once per workflow\" >&2\n\texit 1\nfi\n\nif ! grep -Fq -- '--skip-image-pull' \"$skill_file\"; then\n\techo \"SKILL.md does not avoid a redundant Docker pull after validation\" >&2\n\texit 1\nfi\n\nif ! grep -Fiq 'do not ask for conversational permission' \"$skill_file\"; then\n\techo \"SKILL.md does not prevent unnecessary permission questions\" >&2\n\texit 1\nfi\n\necho \"agent helper tests passed\"\n","content_type":"application/x-sh; charset=utf-8","language":"bash","size":5011,"content_sha256":"c2773019e718c0f942124cdee43bd2d1556ab6240337304973bdba2c6c96608a"},{"filename":"scripts/run-local.sh","content":"#!/usr/bin/env bash\n\nset -euo pipefail\n\nusage() {\n\tcat \u003c\u003c'EOF'\nUsage: run-local.sh --queries FILE --output-dir DIR [options]\n\nOptions:\n --format csv|json Output format (default: csv)\n --lang CODE Google Maps language (default: en)\n --depth NUMBER Search depth (default: 1)\n --proxy-file FILE Proxy URLs file created by configure-proxy.sh\n --email Extract emails from business websites\n --extra-reviews Extract additional reviews (requires JSON)\n --skip-image-pull Reuse the image checked earlier in this workflow\n --dry-run Print the secret-safe Docker command without running it\nEOF\n}\n\nqueries_file=\"\"\noutput_dir=\"\"\noutput_format=\"csv\"\nlang_code=\"en\"\ndepth=\"1\"\nproxy_file=\"\"\nextract_email=false\nextra_reviews=false\nskip_image_pull=false\ndry_run=false\n\nwhile (($# > 0)); do\n\tcase \"$1\" in\n\t\t--queries)\n\t\t\tqueries_file=${2:-}\n\t\t\tshift 2\n\t\t\t;;\n\t\t--output-dir)\n\t\t\toutput_dir=${2:-}\n\t\t\tshift 2\n\t\t\t;;\n\t\t--format)\n\t\t\toutput_format=${2:-}\n\t\t\tshift 2\n\t\t\t;;\n\t\t--lang)\n\t\t\tlang_code=${2:-}\n\t\t\tshift 2\n\t\t\t;;\n\t\t--depth)\n\t\t\tdepth=${2:-}\n\t\t\tshift 2\n\t\t\t;;\n\t\t--proxy-file)\n\t\t\tproxy_file=${2:-}\n\t\t\tshift 2\n\t\t\t;;\n\t\t--email)\n\t\t\textract_email=true\n\t\t\tshift\n\t\t\t;;\n\t\t--extra-reviews)\n\t\t\textra_reviews=true\n\t\t\tshift\n\t\t\t;;\n\t\t--skip-image-pull)\n\t\t\tskip_image_pull=true\n\t\t\tshift\n\t\t\t;;\n\t\t--dry-run)\n\t\t\tdry_run=true\n\t\t\tshift\n\t\t\t;;\n\t\t--help | -h)\n\t\t\tusage\n\t\t\texit 0\n\t\t\t;;\n\t\t*)\n\t\t\tprintf 'Unknown option: %s\\n' \"$1\" >&2\n\t\t\tusage >&2\n\t\t\texit 2\n\t\t\t;;\n\tesac\ndone\n\nif [[ -z \"$queries_file\" || ! -f \"$queries_file\" ]]; then\n\techo \"--queries must name an existing file.\" >&2\n\texit 2\nfi\n\nif [[ -z \"$output_dir\" ]]; then\n\techo \"--output-dir is required.\" >&2\n\texit 2\nfi\n\nif [[ \"$output_format\" != \"csv\" && \"$output_format\" != \"json\" ]]; then\n\techo \"--format must be csv or json.\" >&2\n\texit 2\nfi\n\nif [[ ! \"$depth\" =~ ^[1-9][0-9]*$ ]]; then\n\techo \"--depth must be a positive integer.\" >&2\n\texit 2\nfi\n\nif $extra_reviews && [[ \"$output_format\" != \"json\" ]]; then\n\techo \"--extra-reviews requires --format json.\" >&2\n\texit 2\nfi\n\nif [[ -n \"$proxy_file\" && ! -r \"$proxy_file\" ]]; then\n\techo \"--proxy-file must name a readable file.\" >&2\n\texit 2\nfi\n\nabsolute_file() {\n\tlocal directory\n\tlocal filename\n\tdirectory=$(cd \"$(dirname \"$1\")\" && pwd)\n\tfilename=$(basename \"$1\")\n\tprintf '%s/%s\\n' \"$directory\" \"$filename\"\n}\n\nmkdir -p \"$output_dir\"\nqueries_file=$(absolute_file \"$queries_file\")\noutput_dir=$(cd \"$output_dir\" && pwd)\n\nif [[ -n \"$proxy_file\" ]]; then\n\tproxy_file=$(absolute_file \"$proxy_file\")\nfi\n\ncontainer_name=\"gmaps-scraper-agent\"\nimage_name=\"gosom/google-maps-scraper\"\nresult_name=\"results.$output_format\"\n\ndocker_args=(\n\trun -d\n\t--name \"$container_name\"\n\t-v \"gmaps-playwright-cache:/opt\"\n\t-v \"$queries_file:/queries.txt:ro\"\n\t-v \"$output_dir:/out\"\n)\n\nif [[ -n \"$proxy_file\" ]]; then\n\tdocker_args+=(\n\t\t-v \"$proxy_file:/run/secrets/gmaps-proxies:ro\"\n\t)\nfi\n\ndocker_args+=(\n\t\"$image_name\"\n\t-input /queries.txt\n\t-results \"/out/$result_name\"\n\t-depth \"$depth\"\n\t-lang \"$lang_code\"\n\t-exit-on-inactivity 3m\n)\n\nif [[ \"$output_format\" == \"json\" ]]; then\n\tdocker_args+=(-json)\nfi\n\nif $extract_email; then\n\tdocker_args+=(-email)\nfi\n\nif $extra_reviews; then\n\tdocker_args+=(-extra-reviews)\nfi\n\nif [[ -n \"$proxy_file\" ]]; then\n\tdocker_args+=(-proxies-file /run/secrets/gmaps-proxies)\nfi\n\nif $dry_run; then\n\tprintf 'docker'\n\tprintf ' %q' \"${docker_args[@]}\"\n\tprintf '\\n'\n\texit 0\nfi\n\nif ! command -v docker >/dev/null 2>&1; then\n\techo \"Docker is not installed or is not available on PATH.\" >&2\n\texit 1\nfi\n\nif ! docker info >/dev/null 2>&1; then\n\techo \"Docker is installed, but the Docker daemon is not running.\" >&2\n\texit 1\nfi\n\nimage_available=false\nif docker image inspect \"$image_name\" >/dev/null 2>&1; then\n\timage_available=true\nfi\n\nif ! $skip_image_pull || ! $image_available; then\n\tif ! docker pull \"$image_name\"; then\n\t\techo \"The first image pull failed; retrying once.\" >&2\n\t\tif ! docker pull \"$image_name\"; then\n\t\t\tif ! $image_available; then\n\t\t\t\techo \"Unable to download the Google Maps Scraper Docker image.\" >&2\n\t\t\t\texit 1\n\t\t\tfi\n\t\t\techo \"Could not check for a newer Docker image. Continuing with the installed image.\" >&2\n\t\tfi\n\tfi\nfi\n\nif docker inspect \"$container_name\" >/dev/null 2>&1; then\n\tcontainer_status=$(docker inspect --format '{{.State.Status}}' \"$container_name\")\n\tif [[ \"$container_status\" == \"running\" ]]; then\n\t\techo \"A Google Maps Scraper agent crawl is already running.\" >&2\n\t\texit 1\n\tfi\n\tdocker rm \"$container_name\" >/dev/null\nfi\n\ndocker \"${docker_args[@]}\"\nprintf 'Results will be written to %s/%s\\n' \"$output_dir\" \"$result_name\"\n","content_type":"application/x-sh; charset=utf-8","language":"bash","size":4587,"content_sha256":"872c55d836ac86b73a2f08b0a63206979a1ae47f4437f236a6de19829bed3b71"},{"filename":"scripts/select-proxy-sponsors.mjs","content":"#!/usr/bin/env node\n\nimport { randomInt } from \"node:crypto\";\nimport { readFile } from \"node:fs/promises\";\nimport { pathToFileURL } from \"node:url\";\n\nconst defaultRegistryURL = new URL(\"../references/proxy-sponsors.json\", import.meta.url);\n\nexport function validateSponsors(sponsors) {\n if (!Array.isArray(sponsors)) {\n throw new Error(\"proxy sponsor registry must be an array\");\n }\n\n const identifiers = new Set();\n\n for (const sponsor of sponsors) {\n if (typeof sponsor !== \"object\" || sponsor === null) {\n throw new Error(\"each proxy sponsor must be an object\");\n }\n\n for (const field of [\"id\", \"name\", \"description\", \"referral_url\"]) {\n if (typeof sponsor[field] !== \"string\" || sponsor[field].trim() === \"\") {\n throw new Error(`proxy sponsor requires a non-empty ${field}`);\n }\n }\n\n if (identifiers.has(sponsor.id)) {\n throw new Error(`duplicate sponsor id: ${sponsor.id}`);\n }\n identifiers.add(sponsor.id);\n\n let referralURL;\n try {\n referralURL = new URL(sponsor.referral_url);\n } catch {\n throw new Error(`proxy sponsor ${sponsor.id} requires a valid referral_url`);\n }\n if (referralURL.protocol !== \"https:\") {\n throw new Error(`proxy sponsor ${sponsor.id} requires an HTTPS referral_url`);\n }\n\n if (typeof sponsor.active !== \"boolean\") {\n throw new Error(`proxy sponsor ${sponsor.id} requires a boolean active field`);\n }\n\n if (sponsor.offer !== undefined && typeof sponsor.offer !== \"string\") {\n throw new Error(`proxy sponsor ${sponsor.id} offer must be a string`);\n }\n }\n}\n\nexport function selectSponsors(sponsors, count = 3, chooseRandomInt = randomInt) {\n validateSponsors(sponsors);\n\n const activeSponsors = sponsors.filter(({ active }) => active);\n if (activeSponsors.length \u003c count) {\n throw new Error(`proxy sponsor registry requires at least ${count} active proxy sponsors`);\n }\n\n for (let index = activeSponsors.length - 1; index > 0; index -= 1) {\n const selectedIndex = chooseRandomInt(index + 1);\n [activeSponsors[index], activeSponsors[selectedIndex]] = [\n activeSponsors[selectedIndex],\n activeSponsors[index],\n ];\n }\n\n return activeSponsors.slice(0, count).map((sponsor) => {\n const selected = {\n id: sponsor.id,\n name: sponsor.name,\n description: sponsor.description,\n referral_url: sponsor.referral_url,\n active: sponsor.active,\n };\n\n if (sponsor.offer?.trim()) {\n selected.offer = sponsor.offer.trim();\n }\n\n return selected;\n });\n}\n\nasync function main() {\n const registryURL = process.argv[2] ? pathToFileURL(process.argv[2]) : defaultRegistryURL;\n const contents = await readFile(registryURL, \"utf8\");\n const sponsors = JSON.parse(contents);\n process.stdout.write(`${JSON.stringify(selectSponsors(sponsors), null, 2)}\\n`);\n}\n\nif (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {\n main().catch((error) => {\n process.stderr.write(`Unable to select proxy sponsors: ${error.message}\\n`);\n process.exitCode = 1;\n });\n}\n","content_type":"text/javascript; charset=utf-8","language":"javascript","size":3073,"content_sha256":"42f8097343e2c7701d879e9a13c8ef9e0a683b1454b92f041c226f4bfe0ec7fd"},{"filename":"scripts/select-proxy-sponsors.test.mjs","content":"import assert from \"node:assert/strict\";\nimport { readFileSync } from \"node:fs\";\nimport test from \"node:test\";\n\nimport { selectSponsors, validateSponsors } from \"./select-proxy-sponsors.mjs\";\n\nconst activeSponsors = [\n {\n id: \"a\",\n name: \"Provider A\",\n description: \"Provider A description\",\n referral_url: \"https://a.example.com\",\n active: true,\n },\n {\n id: \"b\",\n name: \"Provider B\",\n description: \"Provider B description\",\n referral_url: \"https://b.example.com\",\n offer: \"10% off\",\n active: true,\n },\n {\n id: \"c\",\n name: \"Provider C\",\n description: \"Provider C description\",\n referral_url: \"https://c.example.com\",\n active: true,\n },\n {\n id: \"d\",\n name: \"Provider D\",\n description: \"Provider D description\",\n referral_url: \"https://d.example.com\",\n active: false,\n },\n];\n\ntest(\"default registry includes Swiftproxy and its offer\", () => {\n const registryURL = new URL(\"../references/proxy-sponsors.json\", import.meta.url);\n const sponsors = JSON.parse(readFileSync(registryURL, \"utf8\"));\n const swiftproxy = sponsors.find(({ id }) => id === \"swiftproxy\");\n\n assert.deepEqual(swiftproxy, {\n id: \"swiftproxy\",\n name: \"Swiftproxy\",\n description:\n \"Residential proxy provider with 90M+ IPs across 220+ locations.\",\n referral_url: \"https://www.swiftproxy.net/?ref=gosom\",\n offer: \"Use code PROXY90 for 10% off.\",\n active: true,\n });\n});\n\ntest(\"selectSponsors returns three unique active sponsors\", () => {\n const selected = selectSponsors(activeSponsors, 3, () => 0);\n\n assert.equal(selected.length, 3);\n assert.equal(new Set(selected.map(({ id }) => id)).size, 3);\n assert.ok(selected.every(({ active }) => active));\n assert.ok(selected.every(({ id }) => id !== \"d\"));\n});\n\ntest(\"selectSponsors includes only configured offers\", () => {\n const selected = selectSponsors(activeSponsors, 3, () => 0);\n const withoutOffer = selected.find(({ id }) => id === \"a\");\n const withOffer = selected.find(({ id }) => id === \"b\");\n\n assert.ok(withoutOffer);\n assert.equal(\"offer\" in withoutOffer, false);\n assert.equal(withOffer.offer, \"10% off\");\n});\n\ntest(\"selectSponsors rejects registries with fewer than three active sponsors\", () => {\n const insufficient = activeSponsors.map((sponsor, index) => ({\n ...sponsor,\n active: index \u003c 2,\n }));\n\n assert.throws(\n () => selectSponsors(insufficient, 3, () => 0),\n /at least 3 active proxy sponsors/,\n );\n});\n\ntest(\"validateSponsors rejects duplicate identifiers\", () => {\n const duplicate = [...activeSponsors, { ...activeSponsors[0] }];\n\n assert.throws(() => validateSponsors(duplicate), /duplicate sponsor id: a/);\n});\n\ntest(\"validateSponsors rejects non-HTTPS referral links\", () => {\n const invalid = [\n { ...activeSponsors[0], referral_url: \"http://a.example.com\" },\n ...activeSponsors.slice(1),\n ];\n\n assert.throws(() => validateSponsors(invalid), /HTTPS referral_url/);\n});\n","content_type":"text/javascript; charset=utf-8","language":"javascript","size":2950,"content_sha256":"b142152eaf11fa30100a227dd11bdfe00bd610548af8d1f52f61e5b666cb6a08"},{"filename":"scripts/status-local.mjs","content":"#!/usr/bin/env node\n\nimport { execFileSync } from \"node:child_process\";\nimport { readFile } from \"node:fs/promises\";\nimport { pathToFileURL } from \"node:url\";\n\nexport async function countResults(outputPath, format) {\n if (format !== \"csv\" && format !== \"json\") {\n throw new Error(\"format must be csv or json\");\n }\n\n let contents;\n try {\n contents = await readFile(outputPath, \"utf8\");\n } catch (error) {\n if (error.code === \"ENOENT\") {\n return 0;\n }\n throw error;\n }\n\n const lineCount = contents.split(/\\r?\\n/).filter((line) => line.trim() !== \"\").length;\n return format === \"csv\" ? Math.max(0, lineCount - 1) : lineCount;\n}\n\nexport function elapsedSeconds(startedAt, now = new Date()) {\n const startMillis = Date.parse(startedAt);\n if (!Number.isFinite(startMillis)) {\n return 0;\n }\n\n return Math.max(0, Math.floor((now.getTime() - startMillis) / 1000));\n}\n\nfunction parseArguments(args) {\n const options = {\n container: \"gmaps-scraper-agent\",\n format: \"csv\",\n output: \"\",\n };\n\n for (let index = 0; index \u003c args.length; index += 1) {\n const argument = args[index];\n if (argument === \"--container\") {\n options.container = args[++index] ?? \"\";\n } else if (argument === \"--format\") {\n options.format = args[++index] ?? \"\";\n } else if (argument === \"--output\") {\n options.output = args[++index] ?? \"\";\n } else {\n throw new Error(`unknown option: ${argument}`);\n }\n }\n\n if (!options.output) {\n throw new Error(\"--output is required\");\n }\n\n return options;\n}\n\nasync function main() {\n const options = parseArguments(process.argv.slice(2));\n const rawState = execFileSync(\n \"docker\",\n [\"inspect\", \"--format\", \"{{json .State}}\", options.container],\n { encoding: \"utf8\", stdio: [\"ignore\", \"pipe\", \"pipe\"] },\n );\n const state = JSON.parse(rawState);\n const status = {\n container: options.container,\n status: state.Status,\n elapsed_seconds: elapsedSeconds(state.StartedAt),\n result_count: await countResults(options.output, options.format),\n output: options.output,\n };\n\n if (state.Status === \"exited\") {\n status.exit_code = state.ExitCode;\n }\n if (state.Error) {\n status.error = state.Error;\n }\n\n process.stdout.write(`${JSON.stringify(status, null, 2)}\\n`);\n}\n\nif (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {\n main().catch((error) => {\n process.stderr.write(`Unable to inspect local crawl: ${error.message}\\n`);\n process.exitCode = 1;\n });\n}\n","content_type":"text/javascript; charset=utf-8","language":"javascript","size":2509,"content_sha256":"56312eb6671eed1ac50e507b0827438623816db5421c13c9fd47df89984ad472"},{"filename":"scripts/status-local.test.mjs","content":"import assert from \"node:assert/strict\";\nimport { mkdtemp, writeFile } from \"node:fs/promises\";\nimport { tmpdir } from \"node:os\";\nimport { join } from \"node:path\";\nimport test from \"node:test\";\n\nimport { countResults, elapsedSeconds } from \"./status-local.mjs\";\n\ntest(\"countResults excludes the CSV header\", async () => {\n const directory = await mkdtemp(join(tmpdir(), \"gmaps-status-\"));\n const output = join(directory, \"results.csv\");\n await writeFile(output, \"title,address\\nCafe,Main Street\\nShop,High Street\\n\", \"utf8\");\n\n assert.equal(await countResults(output, \"csv\"), 2);\n});\n\ntest(\"countResults counts JSON Lines records\", async () => {\n const directory = await mkdtemp(join(tmpdir(), \"gmaps-status-\"));\n const output = join(directory, \"results.json\");\n await writeFile(output, '{\"title\":\"Cafe\"}\\n{\"title\":\"Shop\"}\\n', \"utf8\");\n\n assert.equal(await countResults(output, \"json\"), 2);\n});\n\ntest(\"countResults returns zero for a missing output file\", async () => {\n assert.equal(await countResults(\"/path/that/does/not/exist.csv\", \"csv\"), 0);\n});\n\ntest(\"elapsedSeconds returns a non-negative whole number\", () => {\n const startedAt = \"2026-07-22T12:00:00.000Z\";\n const now = new Date(\"2026-07-22T12:01:40.900Z\");\n\n assert.equal(elapsedSeconds(startedAt, now), 100);\n assert.equal(elapsedSeconds(\"2026-07-22T12:02:00.000Z\", now), 0);\n});\n","content_type":"text/javascript; charset=utf-8","language":"javascript","size":1355,"content_sha256":"04d22c2365d505eb36e75bdcc8ee5318ff214563f9824b614c7a56212439c995"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"Google Maps Scraper","type":"text"}]},{"type":"paragraph","content":[{"text":"Turn a natural-language lead request into a validated local Google Maps crawl, monitor it, and help the user work with the results.","type":"text"}]},{"type":"paragraph","content":[{"text":"Resolve the directory containing this file as ","type":"text"},{"text":"SKILL_DIR","type":"text","marks":[{"type":"code_inline"}]},{"text":". Run bundled scripts from that directory; do not assume the current directory is the repository checkout.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Guardrails","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use plain language suitable for a nontechnical lead-generation or marketing user.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Never ask the user to paste proxy credentials into chat.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Never print, read back, summarize, or log proxy credentials.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Do not ask for conversational permission before routine in-scope actions such as version checks, query preparation, validation, Docker execution, monitoring, or result inspection. Run them directly. If the agent platform requires approval, batch operations and surface only unavoidable approval prompts.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Do not claim a proxy guarantees results or is required for every crawl.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Start with conservative depth and concurrency.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Preserve partial output when a crawl fails or is interrupted.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Do not expose raw logs unless a concise excerpt is necessary for diagnosis and contains no secrets.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Workflow","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"0. Refresh the workflow","type":"text"}]},{"type":"paragraph","content":[{"text":"At the beginning of every new skill workflow, run this exactly once without asking for confirmation:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"bash \"$SKILL_DIR/scripts/ensure-latest.sh\"","type":"text"}]},{"type":"paragraph","content":[{"text":"The helper noninteractively updates only ","type":"text"},{"text":"google-maps-scraper","type":"text","marks":[{"type":"code_inline"}]},{"text":" when a newer installed-skill version is available. Re-read ","type":"text"},{"text":"SKILL.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" from ","type":"text"},{"text":"SKILL_DIR","type":"text","marks":[{"type":"code_inline"}]},{"text":" after it finishes so updated instructions apply immediately. If the check cannot reach the network, state briefly that the installed version will be used and continue.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"1. Understand the request","type":"text"}]},{"type":"paragraph","content":[{"text":"Infer sensible defaults and ask only for missing essentials:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Business type or search phrase","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Location","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Desired coverage: quick sample, normal search, or comprehensive area coverage","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Default to English, CSV, no email extraction, no extra reviews, and shallow depth. Read ","type":"text"},{"text":"query planning","type":"text","marks":[{"type":"link","attrs":{"href":"references/query-planning.md","title":null}}]},{"text":" when translating the request into queries or choosing coverage.","type":"text"}]},{"type":"paragraph","content":[{"text":"Summarize the inferred configuration briefly before setup. Do not ask for confirmation when the intent and location are already clear.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"2. Offer the proxy choice","type":"text"}]},{"type":"paragraph","content":[{"text":"Explain whether the requested volume makes a proxy optional or recommended. Ask the user to choose one path:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use an existing proxy","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"See proxy sponsor recommendations","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Continue without a proxy","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If the user requests recommendations, run the following selector exactly once for this setup:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"node \"$SKILL_DIR/scripts/select-proxy-sponsors.mjs\"","type":"text"}]},{"type":"paragraph","content":[{"text":"Display all three returned providers with equal formatting and neutral language. State clearly: ","type":"text"},{"text":"These providers sponsor the project, and the links are referral links.","type":"text","marks":[{"type":"strong"}]},{"text":" Show ","type":"text"},{"text":"offer","type":"text","marks":[{"type":"code_inline"}]},{"text":" only when the selector returns it. Never invent or modify an offer. Let the user reject all three, use another provider, or continue without a proxy.","type":"text"}]},{"type":"paragraph","content":[{"text":"Read ","type":"text"},{"text":"proxy setup","type":"text","marks":[{"type":"link","attrs":{"href":"references/proxy-setup.md","title":null}}]},{"text":" for the display template, safe credential flow, and selection failures.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"3. Configure credentials safely","type":"text"}]},{"type":"paragraph","content":[{"text":"When the user has a proxy URL, run the masked local prompt:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"bash \"$SKILL_DIR/scripts/configure-proxy.sh\"","type":"text"}]},{"type":"paragraph","content":[{"text":"The user enters credentials directly in the terminal. Do not request the value through chat. The helper returns a file path; use that path with ","type":"text"},{"text":"--proxy-file","type":"text","marks":[{"type":"code_inline"}]},{"text":". The scraper receives it through ","type":"text"},{"text":"-proxies-file","type":"text","marks":[{"type":"code_inline"}]},{"text":", never through inline ","type":"text"},{"text":"-proxies","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"If the agent surface cannot relay interactive terminal input, show the same command for the user to run in their own terminal and wait for it to finish. Never fall back to collecting credentials in chat.","type":"text"}]},{"type":"paragraph","content":[{"text":"Skip this phase when the user chooses no proxy.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"4. Prepare queries and validate locally","type":"text"}]},{"type":"paragraph","content":[{"text":"Write one query per line to a descriptive file under ","type":"text"},{"text":"/tmp","type":"text","marks":[{"type":"code_inline"}]},{"text":". For a normal first run, create a separate validation file containing one representative query.","type":"text"}]},{"type":"paragraph","content":[{"text":"Run the validation crawl with shallow depth and a dedicated output directory. Use the bundled execution helper described in ","type":"text"},{"text":"local execution","type":"text","marks":[{"type":"link","attrs":{"href":"references/local-execution.md","title":null}}]},{"text":". Include ","type":"text"},{"text":"--proxy-file","type":"text","marks":[{"type":"code_inline"}]},{"text":" only when configured.","type":"text"}]},{"type":"paragraph","content":[{"text":"The helper starts Docker in the background. Tell the user that the validation has started, then inspect it with the status helper until it completes. A validation succeeds only when the container exits successfully and produces at least one result.","type":"text"}]},{"type":"paragraph","content":[{"text":"If validation fails, follow ","type":"text"},{"text":"failure recovery","type":"text","marks":[{"type":"link","attrs":{"href":"references/recovery.md","title":null}}]},{"text":" before starting the full crawl.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"5. Run and monitor the full crawl","type":"text"}]},{"type":"paragraph","content":[{"text":"Use the same execution helper with the complete query file and selected options. When validation already checked the Docker image during this workflow, add ","type":"text"},{"text":"--skip-image-pull","type":"text","marks":[{"type":"code_inline"}]},{"text":" to avoid a redundant network request. Without a preceding validation, keep the default image check. Report:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"That the crawl has started","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Whether the first image download may add startup time","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Container state","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Elapsed time","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Current result count","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Poll periodically without blocking the conversation for more than one minute and without streaming logs. Do not promise an exact completion time.","type":"text"}]},{"type":"paragraph","content":[{"text":"For grid search, extra reviews, email extraction, and other non-default flags, read ","type":"text"},{"text":"advanced coverage","type":"text","marks":[{"type":"link","attrs":{"href":"references/advanced-coverage.md","title":null}}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"6. Present and continue working with results","type":"text"}]},{"type":"paragraph","content":[{"text":"After a successful crawl, read ","type":"text"},{"text":"result handling","type":"text","marks":[{"type":"link","attrs":{"href":"references/results.md","title":null}}]},{"text":". Count the complete result set and show at most 20 preview rows with the most useful available fields:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Business name","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Category","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Rating and review count","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Phone","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Website","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Address","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Emails when requested","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Offer to save, analyze, filter, convert, or expand the crawl. Suggest a deeper or grid search only when the user's coverage goal or unexpectedly low result count justifies it.","type":"text"}]},{"type":"paragraph","content":[{"text":"Show the GitHub star suggestion only after the first successful result presentation in a conversation:","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"If this workflow was useful, consider starring https://github.com/gosom/google-maps-scraper.","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Reference routing","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Read ","type":"text"},{"text":"query planning","type":"text","marks":[{"type":"link","attrs":{"href":"references/query-planning.md","title":null}}]},{"text":" for query construction, defaults, language, and coverage.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Read ","type":"text"},{"text":"proxy setup","type":"text","marks":[{"type":"link","attrs":{"href":"references/proxy-setup.md","title":null}}]},{"text":" before presenting sponsors or configuring credentials.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Read ","type":"text"},{"text":"local execution","type":"text","marks":[{"type":"link","attrs":{"href":"references/local-execution.md","title":null}}]},{"text":" for exact validation, run, and status commands.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Read ","type":"text"},{"text":"failure recovery","type":"text","marks":[{"type":"link","attrs":{"href":"references/recovery.md","title":null}}]},{"text":" when setup or a crawl fails.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Read ","type":"text"},{"text":"result handling","type":"text","marks":[{"type":"link","attrs":{"href":"references/results.md","title":null}}]},{"text":" when previewing, analyzing, filtering, or exporting results.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Read ","type":"text"},{"text":"advanced coverage","type":"text","marks":[{"type":"link","attrs":{"href":"references/advanced-coverage.md","title":null}}]},{"text":" only for grid search, deeper crawls, or advanced flags.","type":"text"}]}]}]}]},"metadata":{"date":"2026-11-02","name":"google-maps-scraper","author":"@skillopedia","source":{"stars":7191,"repo_name":"google-maps-scraper","origin_url":"https://github.com/gosom/google-maps-scraper/blob/HEAD/skills/google-maps-scraper/SKILL.md","repo_owner":"gosom","body_sha256":"0b733b979b083683c2af36e52a7bd113ae2a4b1845fee66479d40f7aa20c5eec","cluster_key":"adf8425d8e1a89c0f8d868ae8b9555cab7a00e7829fbea238455c10a4310b84f","clean_bundle":{"format":"clean-skill-bundle-v1","source":"gosom/google-maps-scraper/skills/google-maps-scraper/SKILL.md","text_bytes":31975,"source_commit":"903b96d7aa8863188022c04db220e44f3218c860","skills_sh_rank":6191,"attachment_count":15,"text_attachments":15,"attachment_storage":"skill_attachments","binary_attachments":0},"cluster_size":1,"skill_md_path":"skills/google-maps-scraper/SKILL.md","import_metadata":{"date":"2026-11-02","author":"@skillopedia","version":"v1","category":"browser-automation-scraping","category_label":"Browser"},"exact_dupes_collapsed_into_this":0},"license":"MIT","version":"v1","category":"browser-automation-scraping","metadata":{"email":"[email protected]","author":"gosom","version":"1.12.1","repository":"https://github.com/gosom/google-maps-scraper"},"import_tag":"skills-sh-top20k-2026-11","description":"Find businesses, leads, emails, reviews, ratings, and contact details from Google Maps. Use for requests such as \"find dentists in Berlin\", \"scrape Google Maps\", \"get local business leads\", or \"collect Google Maps reviews\". Runs the open-source scraper locally with Docker and guides nontechnical users through setup, monitoring, and results.\n","allowed-tools":"Bash(node:*) Bash(bash:*) Bash(docker:*) Read Write","compatibility":"Requires Docker and Node.js on macOS, Linux, or Windows through WSL."}},"renderedAt":1793666019940}

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.