# Google Maps Scraper (`primelabs/google-maps-scraper`) Actor This scraper deploys an automated spatial grid matrix to break past the standard 120-listing limit, capturing every hidden business. Delivers clean, non duplicate B2B leads instantly filtered by phone, website, and an intelligent 0–100 quality score. - **URL**: https://apify.com/primelabs/google-maps-scraper.md - **Developed by:** [Mohsen S](https://apify.com/primelabs) (community) - **Categories:** Lead generation, Automation, Developer tools - **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $2.50 / 1,000 record scrapeds This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Primelabs Google Maps Lead Extractor A high-performance geocoding and spatial automation scraper built to harvest enriched commercial leads from Google Maps. By slicing target regions into an automated coordinate matrix and utilizing strict server-side tracking token extraction, this tool bypasses standard platform viewport limits and delivers full geographic market coverage while keeping your compute costs under control. --- ### Why Use This Scraper **Full Market Coverage** Standard scrapers search a city name and scroll. Google Maps caps that view at around 120 listings, which means most of the real market data never shows up. This actor splits the target area into a coordinate grid and runs independent searches across each cell, surfacing businesses in outer neighborhoods and suburbs that get missed entirely. **Strict Production Coordinate Accuracy** Unlike public scrapers that capture drifted camera viewports or broad city centroids, this engine enforces a strict structural parsing pipeline. It extracts exact physical business coordinates directly from Google's canonical server-side `!3d` and `!4d` tracking tokens, preserving 100% data integrity. **Clean, Parameter-Isolated Deduplication** Every profile undergoes structural isolation. The engine strips tracking arguments and query strings down to the unique `!16s` alphanumeric `place_key`. Duplicate listings across overlapping grid cells are intercepted and dropped before they can contaminate your CRM database. --- ### Use Cases **Lead Generation** Build prospecting lists for sales teams with verified phone numbers, addresses, and websites for any niche and location. **Local SEO and Web Design Outreach** Use the built-in lead scoring system to find businesses with no website or a weak review profile, ideal targets for agency outreach. **Market and Competitor Mapping** See how saturated a market is across an entire metro area, not just the downtown core, and benchmark businesses by rating, review volume, and online presence. --- ### How the Grid Scan Works The actor runs through three phases for every search. ```` Phase 1: Geocoding Look up the target city and get its real boundary box Phase 2: Grid Generation Build an evenly spaced grid of coordinates across that boundary \[ Cell 1 ] \[ Cell 2 ] \[ Cell 3 ] \[ Cell 4 ] \[ Cell 5 ] \[ Cell 6 ] \[ Cell 7 ] \[ Cell 8 ] \[ Cell 9 ] Phase 3: Extraction Visit each cell at zoom level 16 and collect every visible listing ```` Searching each cell independently instead of running one broad city search is what allows the actor to reach suburbs and outer neighborhoods that normally never appear in results. --- ### Production Lead Scoring Every business that comes through gets a quality score from 0 to 100, calculated via a balanced multi-variable algorithmic formula: | Signal Matrix | Maximum Point Weight | Calculation Engine | |---|---|---| | **Phone number present** | 25 Points | Binary confirmation check | | **Website present** | 25 Points | Link verification lookahead | | **Review Volume** | 25 Points | Volume calculation (`reviews / 10.0`, capped at 25) | | **Star Rating** | 25 Points | Direct scale multiplication (`rating * 5.0`, capped at 25) | **90 to 100, Enterprise Tier** Established business with verified contact details and strong review activity. **60 to 89, Growth Tier** Active business with a clear gap, usually a missing website or low review count, good for outreach. --- ### Output Schema Each item in the dataset includes: | Field | Type | Description | |---|---|---| | record_id | String | Deterministic SHA-1 hash unique to the business identifier | | place_key | String | Clean, parameter-stripped unique Google feature routing key | | name | String | Business name as listed on Google Maps | | business_status | String | Operating status, for example "operational" or "permanently_closed" | | matched_keyword | String | The search term that returned this result | | address | String | Full normalized street address with line-break stripping | | phone | String | Cleaned, international format phone number | | website | String | Cleaned destination URL listed on the business profile | | total_rating | Float | Star rating from 0.0 to 5.0 | | review_count | Integer | Total number of public reviews | | latitude | Float | Precision geographic coordinate extracted from server token | | longitude | Float | Precision geographic coordinate extracted from server token | | lead_quality_score | Integer | Balanced calculated score from 0 to 100 | --- ### Configuration #### Core Inputs | Field | Type | Required | Description | |---|---|---|---| | target_city | String | Yes | City to search, for example "Miami, FL" | | target_country | String | No | Restricts the search to a country, for example "US" | | search_query | String | Yes | Niche or keyword to search, for example "Dentist" | #### Spatial Settings **scan_mode** controls how the grid spreads across the city. | Value | Behavior | |---|---| | city_center | Keeps the grid tight around the downtown core | | balanced | Spreads the grid across main commercial zones | | full_coverage | Stretches the grid to the city's outer borders | **scan_depth** controls how many points are in the grid. | Value | Points | Layout | |---|---|---| | basic | 1 | Center only | | standard | 4 | 2 x 2 | | deep | 9 | 3 x 3 | | enterprise | 25 | 5 x 5 | #### Safety and Filters | Field | Type | Description | |---|---|---| | max_results | Integer | Stops the run once this many unique leads are saved | | max_search_requests | Integer | Hard cap on total lookups (keywords times grid points). Run stops if exceeded | | required_fields | Array | Drops leads missing these fields, options are "phone" and "website" | --- ### Performance This actor is optimized to run efficiently on standard cloud infrastructure. - Runs cleanly on **2048 MB** of memory allocation - Locked to **single concurrency** (`max_concurrency=1`) to eliminate browser memory leaks and processing spikes - Cost stays predictable because the budget governor checks your configuration requirements before execution --- ### Example Configuration ```json { "target_city": "Miami, FL", "search_query": "Dentist", "scan_mode": "balanced", "scan_depth": "standard", "max_results": 2, "max_search_requests": 3, "required_fields": ["phone", "website"] } ```` *** ### Data Storage on Apify This actor follows the standard Apify storage model. **Input** When a run starts, the configuration object you send is saved as an INPUT record in the run's default Key-Value Store. The scraper reads this record at startup to set the search city, queries, scan settings, and filters. **Output** Each validated lead is pushed to the run's default Dataset as it is found. Records are available to query through the Dataset API while the run is still in progress, not only after it finishes. *** ### API Usage #### Start a Run ```bash curl -X POST "https://api.apify.com/v2/acts/primelabs~google-maps-scraper/runs?token=YOUR_API_TOKEN&memory=2048" \ -H "Content-Type: application/json" \ -d '{ "target_city": "Miami, FL", "target_country": "US", "search_query": "Dentist", "max_results": 2, "max_search_requests": 3, "scan_depth": "basic", "include_lead_scoring": true, "include_row_metadata": false, "output_format": "full", "required_fields": ["phone", "website"] }' ``` #### Fetch Results ```bash curl -X GET "https://api.apify.com/v2/datasets/YOUR_DATASET_ID/items?token=YOUR_API_TOKEN" ``` # Actor input Schema ## `target_city` (type: `string`): The target city to scrape listings from (e.g., London, Berlin, Toronto). ## `target_country` (type: `string`): Appended to the geocoder lookup to guarantee precise region matching. ## `search_query` (type: `string`): The business type or keyword to target if executing a single run look-up. ## `search_queries` (type: `array`): Optional list of multiple keywords to run across the grid sequentially. Overrides standard mode if populated. ## `max_results` (type: `integer`): The absolute total limit of unique data rows to save for the entire actor execution run. ## `max_search_requests` (type: `integer`): Safety governor limit. Prevents execution explosion by throwing errors if required tasks cross this line. ## `scan_mode` (type: `string`): City Center applies a true spherical radius envelope; Balanced/Full Coverage uses boundary-fitted box intervals. ## `scan_depth` (type: `string`): Controls the layout density grid sizing parameters. ## `required_fields` (type: `array`): Lead quality filter. Only save leads that contain these verified fields. ## `output_format` (type: `string`): Controls output field structures based exclusively on user selection visibility thresholds. ## `min_reviews` (type: `integer`): Only extract profiles containing at least this many review ratings (set to 0 to skip filtering). ## `include_lead_scoring` (type: `boolean`): If enabled, appends a calculated lead\_quality\_score (0-100) to support prospecting ranking. ## `include_row_metadata` (type: `boolean`): Turn off to save data storage space. (A global summary is always saved to Key-Value Store regardless of choice). ## `with_website` (type: `boolean`): Filter out any business listings that do not have a website URL attached. ## `without_website` (type: `boolean`): Filter out any business listings that already have an established website URL. ## `skip_permanently_closed` (type: `boolean`): Automatically drop and skip listings marked as 'Permanently Closed' or 'Temporarily Closed'. ## Actor input object example ```json { "max_search_requests": 50, "scan_mode": "balanced", "output_format": "full", "min_reviews": 0, "include_lead_scoring": true, "include_row_metadata": false, "with_website": false, "without_website": false, "skip_permanently_closed": true } ``` # Actor output Schema ## `datasetItems` (type: `string`): A direct URL linking to the default dataset collection containing all the compiled business listings. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = {}; // Run the Actor and wait for it to finish const run = await client.actor("primelabs/google-maps-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = {} # Run the Actor and wait for it to finish run = client.actor("primelabs/google-maps-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{}' | apify call primelabs/google-maps-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=primelabs/google-maps-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Google Maps Scraper", "description": "This scraper deploys an automated spatial grid matrix to break past the standard 120-listing limit, capturing every hidden business. Delivers clean, non duplicate B2B leads instantly filtered by phone, website, and an intelligent 0–100 quality score.", "version": "0.0", "x-build-id": "3f4YJHzzabACYnc3Z" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/primelabs~google-maps-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-primelabs-google-maps-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/primelabs~google-maps-scraper/runs": { "post": { "operationId": "runs-sync-primelabs-google-maps-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/primelabs~google-maps-scraper/run-sync": { "post": { "operationId": "run-sync-primelabs-google-maps-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "target_city", "max_results", "max_search_requests", "scan_mode", "scan_depth", "output_format" ], "properties": { "target_city": { "title": "City Name", "type": "string", "description": "The target city to scrape listings from (e.g., London, Berlin, Toronto)." }, "target_country": { "title": "Country Modifier (Optional)", "type": "string", "description": "Appended to the geocoder lookup to guarantee precise region matching." }, "search_query": { "title": "Niche Keyword (Standard Mode)", "type": "string", "description": "The business type or keyword to target if executing a single run look-up." }, "search_queries": { "title": "Niche Keywords Array (Multi-Keyword Mode)", "type": "array", "description": "Optional list of multiple keywords to run across the grid sequentially. Overrides standard mode if populated.", "items": { "type": "string" } }, "max_results": { "title": "Global Maximum Results Cap", "minimum": 1, "type": "integer", "description": "The absolute total limit of unique data rows to save for the entire actor execution run." }, "max_search_requests": { "title": "Maximum Search Requests Budget Cap", "minimum": 1, "type": "integer", "description": "Safety governor limit. Prevents execution explosion by throwing errors if required tasks cross this line.", "default": 50 }, "scan_mode": { "title": "Grid Spatial Scan Mode", "enum": [ "city_center", "balanced", "full_coverage" ], "type": "string", "description": "City Center applies a true spherical radius envelope; Balanced/Full Coverage uses boundary-fitted box intervals.", "default": "balanced" }, "scan_depth": { "title": "Grid Scan Depth Coverage", "enum": [ "basic", "standard", "deep", "enterprise" ], "type": "string", "description": "Controls the layout density grid sizing parameters." }, "required_fields": { "title": "Filter Validation: Required Contact Fields", "type": "array", "description": "Lead quality filter. Only save leads that contain these verified fields.", "items": { "type": "string", "enum": [ "phone", "website" ], "enumTitles": [ "Valid Phone Number Present", "Active Website URL Present" ] } }, "output_format": { "title": "CRM / API Data Export Format Preset", "enum": [ "full", "crm", "contact_only" ], "type": "string", "description": "Controls output field structures based exclusively on user selection visibility thresholds.", "default": "full" }, "min_reviews": { "title": "Filter: Minimum Reviews Count", "minimum": 0, "type": "integer", "description": "Only extract profiles containing at least this many review ratings (set to 0 to skip filtering).", "default": 0 }, "include_lead_scoring": { "title": "Compute Commercial Value: Lead Quality Score", "type": "boolean", "description": "If enabled, appends a calculated lead_quality_score (0-100) to support prospecting ranking.", "default": true }, "include_row_metadata": { "title": "Append Run Metadata Key on Each Lead Row", "type": "boolean", "description": "Turn off to save data storage space. (A global summary is always saved to Key-Value Store regardless of choice).", "default": false }, "with_website": { "title": "Filter: Only Profiles With Active Website Links", "type": "boolean", "description": "Filter out any business listings that do not have a website URL attached.", "default": false }, "without_website": { "title": "Filter: Only Profiles Missing Website Links", "type": "boolean", "description": "Filter out any business listings that already have an established website URL.", "default": false }, "skip_permanently_closed": { "title": "Filter: Automatically Skip Permanently Closed Locations", "type": "boolean", "description": "Automatically drop and skip listings marked as 'Permanently Closed' or 'Temporarily Closed'.", "default": true } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```