# Google Maps MCP (`crawlerbros/google-maps-mcp`) Actor

Unified Apify MCP server for Google Maps. Search for businesses and extract comprehensive data including ratings, reviews, contact info, and more. Scrape detailed reviews from any Google Maps place.

- **URL**: https://apify.com/crawlerbros/google-maps-mcp.md
- **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community)
- **Categories:** MCP servers, Real estate, Other
- **Stats:** 38 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $3.00 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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 MCP Server

A unified Apify MCP (Model Context Protocol) server for comprehensive Google Maps scraping. This actor provides a single interface to search for businesses and scrape reviews using browser automation with Playwright.

### 🚀 Features

#### Multi-Mode Scraping

This MCP server supports two scraping modes:

1. **Search Mode** - Search and scrape business listings from Google Maps
2. **Reviews Mode** - Scrape reviews from a specific Google Maps business

#### Key Capabilities

✅ **Unified Interface** - Single actor for all Google Maps scraping needs
✅ **Browser Automation** - Reliable scraping using Playwright
✅ **No API Key Required** - Scrape public content without authentication
✅ **Comprehensive Data** - Extract all relevant business details and reviews
✅ **Automatic Pagination** - Load multiple results and reviews automatically
✅ **Structured Output** - Clean JSON data ready for AI consumption

### 📋 Input Parameters

#### Common Parameters

| Parameter | Type   | Required | Description                              |
| --------- | ------ | -------- | ---------------------------------------- |
| `mode`    | string | Yes      | Scraping mode: `search` or `reviews`     |

#### Search Mode Parameters

| Parameter     | Type    | Default | Description                                    |
| ------------- | ------- | ------- | ---------------------------------------------- |
| `searchQuery` | string  | -       | What to search for (e.g., "restaurant")        |
| `location`    | string  | `""`    | Where to search (e.g., "New York, NY")         |
| `maxResults`  | integer | `20`    | Maximum number of businesses to scrape (1-100) |

#### Reviews Mode Parameters

| Parameter    | Type    | Default | Description                                   |
| ------------ | ------- | ------- | --------------------------------------------- |
| `placeUrl`   | string  | -       | Google Maps place URL                         |
| `maxReviews` | integer | `50`    | Maximum number of reviews to scrape (1-1000)  |

### 📝 Input Examples

#### Example 1: Search for Businesses

```json
{
  "mode": "search",
  "searchQuery": "pizza restaurant",
  "location": "New York, NY",
  "maxResults": 20
}
```

#### Example 2: Scrape Reviews

```json
{
  "mode": "reviews",
  "placeUrl": "https://www.google.com/maps/place/Joe's+Pizza/@40.7308314,-73.9973325,17z",
  "maxReviews": 100
}
```

### 📊 Output Format

#### Search Mode Output

Each business includes:

```json
{
  "index": 1,
  "name": "Joe's Pizza",
  "category": "Pizza restaurant",
  "rating": 4.5,
  "review_count": 1234,
  "price_level": "$$",
  "address": "7 Carmine St, New York, NY 10014",
  "phone": "+1 212-366-1182",
  "website": "https://www.joespizzanyc.com/",
  "url": "https://www.google.com/maps/place/Joe's+Pizza/@40.7308314,-73.9973325,17z",
  "place_id": "ChIJxxx...",
  "latitude": 40.7308314,
  "longitude": -73.9973325,
  "scraped_at": "2025-11-02T20:30:00"
}
```

#### Reviews Mode Output (Flattened Format)

**One review per row** for easy analysis - each dataset item represents a single review with place metadata:

```json
{
  "place_metadata": {
    "place_url": "https://www.google.com/maps/place/...",
    "scraped_at": "2025-11-02T20:30:00",
    "business_name": "Joe's Pizza",
    "rating": 4.5,
    "total_reviews": 1234,
    "category": "Pizza restaurant",
    "address": "7 Carmine St, New York, NY 10014"
  },
  "review_id": "ChZDSUhNMG9nS0VJQ0FnSUQ...",
  "reviewer_name": "John Smith",
  "reviewer_avatar": "https://lh3.googleusercontent.com/...",
  "rating": 5.0,
  "review_text": "Best pizza in NYC! The crust is perfect and the sauce is amazing...",
  "review_date": "2 months ago",
  "likes": 42
}
```

**Benefits of Flattened Format:**

- ✅ Each row is one review (perfect for CSV export and data analysis)
- ✅ Easy to query, filter, and aggregate in databases
- ✅ Compatible with pandas DataFrames and SQL tables
- ✅ Place metadata included in every row (no joins needed)
- ✅ Simplified data pipeline integration

### 🎯 Use Cases

#### Business Intelligence

- **Market Research** - Analyze competitor locations and ratings
- **Location Planning** - Find optimal areas for new business locations
- **Competitive Analysis** - Track competitor reviews and ratings
- **Customer Insights** - Understand what customers value in your industry

#### Data Analysis & Research

- **Sentiment Analysis** - Analyze customer sentiment from reviews
- **Trend Detection** - Identify popular locations and emerging trends
- **Service Quality** - Compare service quality across locations
- **Price Analysis** - Study pricing patterns across regions

#### AI & ML Applications

- **Training Data** - Build datasets for recommendation systems
- **RAG Systems** - Feed business and review data to AI models
- **Chatbot Training** - Use reviews for customer service bots
- **Content Generation** - Analyze successful business descriptions

### 🛠️ Local Development

#### Prerequisites

```bash
pip install -r requirements.txt
playwright install chromium
```

#### Create Input File

Create `storage/key_value_stores/default/INPUT.json`:

**For Search Mode:**

```json
{
  "mode": "search",
  "searchQuery": "coffee shop",
  "location": "San Francisco, CA",
  "maxResults": 10
}
```

**For Reviews Mode:**

```json
{
  "mode": "reviews",
  "placeUrl": "https://www.google.com/maps/place/Blue+Bottle+Coffee/@37.7749295,-122.4194155,17z",
  "maxReviews": 50
}
```

#### Run Locally

```bash
cd Google/mcp
apify run
```

#### Check Results

Results are saved in:

- `storage/datasets/default/` - Individual records
- `storage/key_value_stores/default/OUTPUT.json` - Complete output

### 🚀 Deployment

#### Using Apify CLI

```bash
## Login to Apify
apify login

## Push to Apify platform
apify push
```

#### Manual Upload

1. Create a new actor on [Apify Console](https://console.apify.com/)
2. Upload all files including `Dockerfile`, `requirements.txt`, and `.actor/` directory
3. Configure input parameters
4. Run the actor

### 📚 API Integration

#### JavaScript/Node.js

```javascript
const { ApifyClient } = require("apify-client");

const client = new ApifyClient({ token: "YOUR_API_TOKEN" });

// Search for businesses
const searchInput = {
  mode: "search",
  searchQuery: "sushi restaurant",
  location: "Los Angeles, CA",
  maxResults: 25
};

const run = await client.actor("YOUR_ACTOR_ID").call(searchInput);
const { items } = await client.dataset(run.defaultDatasetId).listItems();

console.log(`Found ${items.length} businesses`);
```

#### Python

```python
from apify_client import ApifyClient

client = ApifyClient('YOUR_API_TOKEN')

## Scrape reviews
reviews_input = {
    'mode': 'reviews',
    'placeUrl': 'https://www.google.com/maps/place/...',
    'maxReviews': 100
}

run = client.actor('YOUR_ACTOR_ID').call(run_input=reviews_input)

for item in client.dataset(run['defaultDatasetId']).iterate_items():
    print(f"Review: {item['review_text']}")
    print(f"Rating: {item['rating']}")
```

### ⚡ Performance Tips

#### Optimize Speed

- Start with lower `maxResults`/`maxReviews` for testing
- Use specific search queries for better results
- Limit location scope for faster searches
- Process fewer businesses per run for faster completion

#### Best Practices

- Add delays between requests (built-in)
- Don't scrape the same content repeatedly
- Respect Google's servers - use reasonable limits
- Consider batching requests across multiple runs

### ⚠️ Limitations

- **Public Content Only** - Cannot access restricted or private data
- **No Authentication** - Requires public access to content
- **Rate Limits** - Google may throttle excessive requests
- **Browser-Based** - Slower than direct API but more reliable
- **Dynamic Content** - Some features may change if Google updates layout

### 🐛 Troubleshooting

#### No Results Returned

- Verify search query and location are correct
- Check if the place URL is valid and accessible
- Try with smaller `maxResults`/`maxReviews` values first
- Review logs for specific error messages

#### Timeout Errors

- Content may be loading slowly
- Try with fewer items or smaller limits
- Check if Google Maps is accessible from your location

#### Missing Data Fields

- Some fields may be null if not available
- Not all businesses have all information
- Reviews may vary in completeness

### 🗺️ Complete Google Maps Scraper Suite

This actor is part of a comprehensive Google Maps data extraction toolkit by **crawlerbros**. All actors run on the free Apify plan, use no proxy by default, and return clean, structured data.

| Actor | What it does |
|---|---|
| 🏢 [Google Maps Business Scraper](https://apify.com/crawlerbros/google-maps-scraper) | Extract business data — name, address, phone, website, rating, reviews, hours, amenities |
| ⭐ [Google Maps Reviews Scraper](https://apify.com/crawlerbros/google-maps-reviews-scraper) | Scrape reviews with reviewer Local Guide level, photos, mentioned items, owner replies |
| 📸 [Google Maps Photos Scraper](https://apify.com/crawlerbros/google-maps-photos) | Extract all photos from any place — max-resolution URLs, contributor info, categories |
| 🕐 [Google Maps Business Hours Scraper](https://apify.com/crawlerbros/google-maps-business-hours) | Full 7-day hours, timezone, current local time, next open/close, holiday hours |
| 📊 [Google Maps Popular Times Scraper](https://apify.com/crawlerbros/google-maps-popular-times) | Busy hours histogram for all 7 days + current busyness + typical visit time |
| 📧 [Google Maps Email Extractor](https://apify.com/crawlerbros/google-maps-email-extractor) | Find business emails + social media links by crawling websites |
| 🗺️ [Google Maps Area Scanner](https://apify.com/crawlerbros/google-maps-area-scanner) | Geographic grid scanning — bypass the 120-place limit with bounding box / circle / polygon |
| 💼 [Google Maps Leads Scraper](https://apify.com/crawlerbros/google-maps-leads) | B2B lead generation with email + phone enrichment, US states + global countries |
| 🧭 [Google Maps Directions Scraper](https://apify.com/crawlerbros/google-maps-directions) | A→B routing — distance, duration, traffic, route alternatives for driving/walking/transit |
| 📍 [Google Maps Geocoding Scraper](https://apify.com/crawlerbros/google-maps-geocoding) | Bidirectional geocoding — address ↔ coordinates, with address components |
| 🔗 [Google Maps Similar Places Scraper](https://apify.com/crawlerbros/google-maps-similar-places) | "People also search for" / related place discovery — competitor & alternative finder |
| 🍽️ [Google Maps Menu Scraper](https://apify.com/crawlerbros/google-maps-menu) | Restaurant menu items, prices, descriptions, photos |
| 📌 [Google Maps Nearby Scraper](https://apify.com/crawlerbros/google-maps-nearby) | Find places near a coordinate point — lightweight POI search by category |
| 📋 [Google Maps Place List Scraper](https://apify.com/crawlerbros/google-maps-place-list) | Extract Google's curated "Top X in Y" lists — best hotels/restaurants/things to do |
| 🌍 [Google Maps Timezone Scraper](https://apify.com/crawlerbros/google-maps-timezone) | IANA timezone + current local time from coordinates |

### 📄 License

This actor is provided as-is for scraping public Google Maps data in accordance with Google's terms of service.

### 🔗 Related Actors

- [Google Maps Scraper](../google-maps/) - Dedicated business search scraper
- [Google Maps Reviews Scraper](../google-maps-reviews/) - Dedicated reviews scraper

### 💡 Notes

- This MCP server uses browser automation to access Google Maps public interface
- Always respect Google's robots.txt and terms of service
- Use responsibly and avoid overwhelming Google's servers
- Consider implementing additional rate limiting for large-scale scraping
- The actor works best with the Apify platform's infrastructure

### 🆘 Support

For issues, questions, or feature requests, please open an issue in the repository or contact support.

***

**Made with ❤️ for the AI community | Powered by Apify**

# Actor input Schema

## `mode` (type: `string`):

Choose the scraping mode: search for businesses, or scrape reviews from a specific place.

## `searchQuery` (type: `string`):

What to search for (e.g., 'restaurant', 'hotel', 'coffee shop'). Required for 'search' mode.

## `location` (type: `string`):

Location to search in (e.g., 'New York, NY', 'London, UK'). Required for 'search' mode.

## `maxResults` (type: `integer`):

Maximum number of business results to scrape. Only used in 'search' mode.

## `language` (type: `string`):

Language code for results (e.g., 'en', 'de', 'fr').

## `placeUrl` (type: `string`):

Google Maps place URL to scrape reviews from. Required for 'reviews' mode.

## `maxReviews` (type: `integer`):

Maximum number of reviews to scrape. Only used in 'reviews' mode.

## `proxyConfiguration` (type: `object`):

Select proxies to be used by this actor. Recommended for avoiding rate limits.

## Actor input object example

```json
{
  "mode": "search",
  "searchQuery": "pizza restaurant",
  "location": "New York, NY",
  "maxResults": 5,
  "language": "en",
  "placeUrl": "https://www.google.com/maps/place/Joe's+Pizza/@40.7308314,-73.9973325,17z",
  "maxReviews": 50
}
```

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "search",
    "searchQuery": "coffee shop in New York",
    "maxResults": 5,
    "language": "en"
};

// Run the Actor and wait for it to finish
const run = await client.actor("crawlerbros/google-maps-mcp").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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "search",
    "searchQuery": "coffee shop in New York",
    "maxResults": 5,
    "language": "en",
}

# Run the Actor and wait for it to finish
run = client.actor("crawlerbros/google-maps-mcp").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "search",
  "searchQuery": "coffee shop in New York",
  "maxResults": 5,
  "language": "en"
}' |
apify call crawlerbros/google-maps-mcp --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,crawlerbros/google-maps-mcp"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/f8d1fJGFQuLQW1MH0/builds/UeCIsL465WxkeOo31/openapi.json