# Google Maps Scraper (`zerobreak/google-maps-scraper`) Actor Google Maps scraper that collects business listings, place details, and customer reviews by search query or place ID. Extracts names, ratings, addresses, phones, websites, GPS coordinates, hours, popular times, images, and reviews at scale. - **URL**: https://apify.com/zerobreak/google-maps-scraper.md - **Developed by:** [ZeroBreak](https://apify.com/zerobreak) (community) - **Categories:** Lead generation, Automation, Other - **Stats:** 2 total users, 1 monthly users, 69.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $5.99 / 1,000 results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. 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 ## Google Maps Scraper Pulls business listings, place details, and reviews from Google Maps into a structured dataset. Useful for competitor research, local directories, lead generation, or any project that needs real place data. ### What it does Search by keyword, collect matching places, and optionally fetch richer detail or reviews for each result. - **Search**: Query like "pizza New York" or "hotels London" returns matching places - **Place details**: Per-place extras — popular times by hour, full weekly hours, images, description - **Reviews**: Customer reviews per place, with sort options ### Example use cases - Build a local business directory for a city - Track competitor ratings over time - Collect leads with phone numbers and websites - Research pricing or business density in a market - Get GPS coordinates for a mapping project ### Input | Field | Description | Default | |-------|-------------|---------| | `searchQuery` | Search term (e.g., "coffee shops Berlin") | — | | `placeIds` | Direct Place IDs (ChIJ... format) | — | | `includeDetails` | Fetch enriched data per place (popular times, images, description) | `true` | | `includeReviews` | Collect customer reviews per place | `false` | | `maxReviewsPerPlace` | Reviews per place | `20` | | `reviewSortBy` | relevance, newestFirst, ratingHigh, ratingLow | `relevance` | | `language` | Language code (e.g., "en", "de") | `en` | | `country` | Country code (e.g., "us", "gb") | `us` | | `googleDomain` | Google domain (e.g., "google.co.uk") | `google.com` | | `location` | GPS bias: @lat,lng,zoom (e.g., "@40.71,-74.00,14z") | — | | `maxItems` | Max places to return | `20` | | `requestTimeoutSecs` | Per-request timeout in seconds | `30` | Provide either `searchQuery` or `placeIds` (or both). #### Example input ```json { "searchQuery": "sushi restaurants Tokyo", "includeDetails": true, "includeReviews": true, "maxReviewsPerPlace": 50, "reviewSortBy": "newestFirst", "language": "en", "country": "jp", "googleDomain": "google.co.jp", "maxItems": 40 } ```` ### Output Each place is one dataset record: | Field | Description | |-------|-------------| | `placeId` | Google Maps Place ID (ChIJ...) | | `dataCid` | Numeric place identifier | | `dataId` | Hex place identifier (0xHEX:0xHEX) | | `position` | Position in search results | | `placeName` | Business name | | `rating` | Average rating (1.0–5.0) | | `reviewCount` | Total reviews | | `priceLevel` | Price range (e.g., "$10–20") | | `address` | Full street address | | `phone` | Phone number | | `website` | Website URL | | `placeType` | Primary category (e.g., "Restaurant") | | `placeTypes` | All categories | | `placeDescription` | Short editorial description | | `gpsLatitude` / `gpsLongitude` | Coordinates | | `isOpen` | Currently open (`true`/`false`) | | `openHours` | Current hours status (e.g., "Closed · Opens 10 AM") | | `operatingHours` | Full weekly schedule (list of day/time objects) | | `serviceOptions` | Dine-in, takeout, delivery flags | | `popularTimes` | Hourly busyness data by day | | `images` | Thumbnail image URLs | | `reviews` | Customer reviews array (if enabled) | | `scrapedAt` | ISO 8601 timestamp | #### Example output ```json { "placeId": "ChIJifIePKtZwokRVZ-UdRGkZzs", "placeName": "Joe's Pizza Broadway", "rating": 4.4, "reviewCount": 25442, "priceLevel": "$10-20", "address": "1435 Broadway, New York, NY 10018", "phone": "(646) 559-4878", "website": "https://www.joespizzanyc.com/", "placeType": "Pizza restaurant", "placeTypes": ["Pizza restaurant", "Pizza delivery", "Restaurant"], "placeDescription": "Classic NYC slice shop offering New York-style slices and pies.", "gpsLatitude": 40.7549, "gpsLongitude": -73.9864, "isOpen": false, "openHours": "Closed · Opens 10 AM", "operatingHours": [ { "monday": "10 AM–3 AM" }, { "tuesday": "10 AM–3 AM" }, { "friday": "10 AM–5 AM" } ], "serviceOptions": { "dine_in": true, "takeout": true, "delivery": false }, "popularTimes": { "monday": [ { "time": "10 AM", "busyness_score": 20 }, { "time": "12 PM", "busyness_score": 75 } ] }, "images": [ "https://lh3.googleusercontent.com/..." ], "reviews": [ { "reviewRating": 5, "reviewText": "Best pizza slice in New York. Period.", "reviewerName": "Sarah M.", "reviewDate": "2 months ago", "isLocalGuide": false, "likes": 12 } ], "scrapedAt": "2025-06-01T14:32:00+00:00" } ``` ### Notes - Search returns up to 20 results per page, 120 max total - Reviews paginate automatically up to your `maxReviewsPerPlace` limit - `includeDetails: true` makes one extra request per place - Use `location` as `@latitude,longitude,zoom` to target a specific area (e.g., `@48.8566,2.3522,13z` for Paris) - `placeIds` and `searchQuery` can be used together — duplicate place IDs are skipped automatically # Actor input Schema ## `searchQuery` (type: `string`): What to search for on Google Maps. Examples: 'pizza New York', 'hotels London', 'dentist near me'. ## `placeIds` (type: `array`): One or more Google Maps Place IDs (ChIJ... format) to look up directly. Use instead of, or in addition to, the search query. ## `includeDetails` (type: `boolean`): Fetch enriched place data (popular times, images, menu links, full hours) for each result. Requires one extra request per place. Disabled by default. ## `includeReviews` (type: `boolean`): Fetch customer reviews for each place. The number of reviews per place is controlled by 'Max reviews per place'. ## `maxReviewsPerPlace` (type: `integer`): Maximum number of reviews to collect per place when 'Include reviews' is enabled. ## `reviewSortBy` (type: `string`): How to sort reviews when fetching them. ## `language` (type: `string`): Language code for results (e.g. 'en', 'de', 'fr', 'tr'). Controls the language of place names and UI strings. ## `country` (type: `string`): Two-letter country code for geo-targeting results (e.g. 'us', 'gb', 'de'). ## `googleDomain` (type: `string`): Google domain to query. Change for country-specific results (e.g. 'google.co.uk', 'google.de', 'google.com.tr'). ## `location` (type: `string`): Optional GPS coordinates to bias search results. Format: @latitude,longitude,zoomLevel (e.g. '@40.7128,-74.0060,14z' for New York). Zoom levels: 1z (world) to 21z (street). ## `maxItems` (type: `integer`): Maximum number of places to return from a search query. ## `requestTimeoutSecs` (type: `integer`): Per-request timeout in seconds. ## Actor input object example ```json { "searchQuery": "restaurants New York", "placeIds": [], "includeDetails": false, "includeReviews": false, "maxReviewsPerPlace": 20, "reviewSortBy": "relevance", "language": "en", "country": "us", "googleDomain": "google.com", "maxItems": 20, "requestTimeoutSecs": 30 } ``` # 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 = { "searchQuery": "restaurants New York", "placeIds": [], "language": "en", "country": "us", "googleDomain": "google.com" }; // Run the Actor and wait for it to finish const run = await client.actor("zerobreak/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 = { "searchQuery": "restaurants New York", "placeIds": [], "language": "en", "country": "us", "googleDomain": "google.com", } # Run the Actor and wait for it to finish run = client.actor("zerobreak/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 '{ "searchQuery": "restaurants New York", "placeIds": [], "language": "en", "country": "us", "googleDomain": "google.com" }' | apify call zerobreak/google-maps-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=zerobreak/google-maps-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Google Maps Scraper", "description": "Google Maps scraper that collects business listings, place details, and customer reviews by search query or place ID. Extracts names, ratings, addresses, phones, websites, GPS coordinates, hours, popular times, images, and reviews at scale.", "version": "0.0", "x-build-id": "koE75W9fh5KOhBnzM" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/zerobreak~google-maps-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-zerobreak-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/zerobreak~google-maps-scraper/runs": { "post": { "operationId": "runs-sync-zerobreak-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/zerobreak~google-maps-scraper/run-sync": { "post": { "operationId": "run-sync-zerobreak-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", "properties": { "searchQuery": { "title": "Search query", "type": "string", "description": "What to search for on Google Maps. Examples: 'pizza New York', 'hotels London', 'dentist near me'." }, "placeIds": { "title": "Place IDs", "type": "array", "description": "One or more Google Maps Place IDs (ChIJ... format) to look up directly. Use instead of, or in addition to, the search query.", "items": { "type": "string" } }, "includeDetails": { "title": "Include place details", "type": "boolean", "description": "Fetch enriched place data (popular times, images, menu links, full hours) for each result. Requires one extra request per place. Disabled by default.", "default": false }, "includeReviews": { "title": "Include reviews", "type": "boolean", "description": "Fetch customer reviews for each place. The number of reviews per place is controlled by 'Max reviews per place'.", "default": false }, "maxReviewsPerPlace": { "title": "Max reviews per place", "minimum": 1, "maximum": 200, "type": "integer", "description": "Maximum number of reviews to collect per place when 'Include reviews' is enabled.", "default": 20 }, "reviewSortBy": { "title": "Review sort order", "enum": [ "relevance", "newestFirst", "ratingHigh", "ratingLow" ], "type": "string", "description": "How to sort reviews when fetching them.", "default": "relevance" }, "language": { "title": "Language", "type": "string", "description": "Language code for results (e.g. 'en', 'de', 'fr', 'tr'). Controls the language of place names and UI strings.", "default": "en" }, "country": { "title": "Country", "type": "string", "description": "Two-letter country code for geo-targeting results (e.g. 'us', 'gb', 'de').", "default": "us" }, "googleDomain": { "title": "Google domain", "type": "string", "description": "Google domain to query. Change for country-specific results (e.g. 'google.co.uk', 'google.de', 'google.com.tr').", "default": "google.com" }, "location": { "title": "GPS location", "type": "string", "description": "Optional GPS coordinates to bias search results. Format: @latitude,longitude,zoomLevel (e.g. '@40.7128,-74.0060,14z' for New York). Zoom levels: 1z (world) to 21z (street)." }, "maxItems": { "title": "Max places", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Maximum number of places to return from a search query.", "default": 20 }, "requestTimeoutSecs": { "title": "Request timeout (seconds)", "minimum": 5, "maximum": 120, "type": "integer", "description": "Per-request timeout in seconds.", "default": 30 } } }, "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 } } } } } } } } } } ```