# Google Maps Reviews Scraper (`neatrat/google-maps-reviews-scraper`) Actor

🌟 Scrape thousands of Google Map reviews with advanced filters. Fast, clean, and customizable.

- **URL**: https://apify.com/neatrat/google-maps-reviews-scraper.md
- **Developed by:** [Neatrat](https://apify.com/neatrat) (community)
- **Categories:** Automation, Developer tools
- **Features:** Limited permissions
- **Stats:** 161 total users, 3 monthly users, 91.7% runs succeeded, 10 bookmarks
- **User rating**: 1.47 out of 5 stars

## Pricing

from $1.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.

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

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Google Maps Reviews Scraper

An Apify actor that scrapes reviews from Google Maps places. Extract comprehensive review data including ratings, reviewer information, review text, dates, photos, owner responses, and metadata.

### Features

- 🔄 **Automatic retries**: Retry temporary refusals and return the reviews actually collected
- 🔄 **Proxy Included**: We handle proxy rotation automatically - no setup needed!
- 🔍 **Flexible Input**: Accepts Google Maps place ID or full Google Maps URL
- ⭐ **Rich Data**: Extracts ratings, reviewer names, review text, dates, languages, photos, and owner responses
- 🎯 **Advanced Filtering**: Filter by star ratings, keywords, date ranges, languages, and search queries
- 📄 **Pagination Support**: Automatically handles pagination to get all available reviews
- 🚀 **High Performance**: Optimized for speed and reliability with retry logic
- 🌍 **Multi-language Support**: Works with any language and region
- 🔍 **Search Functionality**: Search for specific terms within reviews

### Input Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `placeIdOrUrl` | String | *Required* | Google Maps place ID (e.g., '0x14a839000bbc66dd:0x517edaab612d6d13') or full Google Maps URL |
| `startPage` | Integer | 1 | Page number to start scraping from |
| `pagesToScrape` | Integer | 5 | Maximum number of pages to scrape (-1 for all available) |
| `reviewsPerPage` | String | "10" | Number of reviews per page to scrape ("10" or "20") |
| `maxReviews` | Integer | 10000 | Maximum number of reviews to scrape (-1 for no limit) |
| `sortBy` | String | "mostRelevant" | Sort reviews by "mostRelevant", "newest", "highestRating", or "lowestRating" |
| `ratings` | Array | \[1,2,3,4,5] | Filter reviews by star ratings (1-5) |
| `language` | Array | \[] | Filter reviews by language codes (e.g., \["en", "fr", "de"]) |
| `keywords` | Array | \[] | Filter reviews containing specific keywords |
| `searchQuery` | String | "" | Search for reviews containing specific terms |
| `endDate` | String | null | Only include reviews posted before this date (YYYY-MM-DD format) |
| `recentDays` | Integer | 0 | Only include reviews from the last N days (0 = disabled) |
| `uniqueOnly` | Boolean | true | Remove duplicate reviews (by review ID) |

### Output Data

Each review contains the following fields:

| Field | Type | Description |
|-------|------|-------------|
| `reviewId` | String | Unique review identifier |
| `rating` | Integer | Star rating (1-5) |
| `reviewer` | String | Name of the reviewer |
| `date` | String | Review date in ISO format (YYYY-MM-DD) |
| `text` | String | Original review text content |
| `translatedText` | String | Translated review text (if available) |
| `language` | String | Language code of the review |
| `userImage` | String | URL to reviewer's profile image |
| `photos` | Array | URLs of photos attached to the review |
| `ownerResponse` | String | Business owner's response to the review (if any) |
| `localGuideInfo` | String | Local Guide information for the reviewer |
| `placeId` | String | Google Maps place ID |
| `timestamp` | Integer | Unix timestamp of the review |
| `position` | Integer | Position/order of review in the results |

### Usage Examples

#### Basic Usage

```json
{
  "placeIdOrUrl": "https://www.google.com/maps/place/Google/@59.326069,-95.989235,3z/data=!3m1!4b1!4m6!3m5!1s0xfdeda002b05abf3:0x30dd244877e2a5bc!8m2!3d59.326069!4d-95.989235!16s%2Fg%2F11vf0j1l59?entry=ttu&g_ep=EgoyMDI1MDUyMS4wIKXMDSoJLDEwMjExNDUzSAFQAw%3D%3D",
  "maxReviews": 1000,
  "reviewsPerPage": "20",
  "pagesToScrape": 10
}
```

#### Advanced Filtering

```json
{
  "placeIdOrUrl": "0x14a839000bbc66dd:0x517edaab612d6d13",
  "ratings": [4, 5],
  "keywords": ["great", "amazing", "excellent"],
  "language": ["en", "fr"],
  "recentDays": 30,
  "maxReviews": 500,
  "sortBy": "newest"
}
```

#### Search for Specific Terms

```json
{
  "placeIdOrUrl": "0x14a839000bbc66dd:0x517edaab612d6d13",
  "searchQuery": "food quality",
  "pagesToScrape": 5,
  "sortBy": "mostRelevant"
}
```

#### Place ID Only

```json
{
  "placeIdOrUrl": "0x14a839000bbc66dd:0x517edaab612d6d13",
  "pagesToScrape": 3,
  "sortBy": "highestRating"
}
```

### How to Get Place ID

You can provide either:

1. **Full Google Maps URL**:
   ```
   https://www.google.com/maps/place/Google/@59.326069,-95.989235,3z/data=!3m1!4b1!4m6!3m5!1s0xfdeda002b05abf3:0x30dd244877e2a5bc!8m2!3d59.326069!4d-95.989235!16s%2Fg%2F11vf0j1l59?entry=ttu&g_ep=EgoyMDI1MDUyMS4wIKXMDSoJLDEwMjExNDUzSAFQAw%3D%3D
   ```

2. **Place ID only**:
   ```
   0x89c25a316e5b7c5d:0x1234567890abcdef
   ```

The place ID is the hexadecimal string in the format `0xHEX:0xHEX` found in Google Maps URLs.

### Supported Languages

The scraper supports all languages available on Google Maps. Common language codes include:

- `en` - English
- `es` - Spanish
- `fr` - French
- `de` - German
- `it` - Italian
- `pt` - Portuguese
- `ru` - Russian
- `ja` - Japanese
- `ko` - Korean
- `zh` - Chinese
- `el` - Greek

### Rate Limiting & Best Practices

- The scraper includes built-in delays between requests to respect Google's servers
- Proxy rotation is handled automatically
- Use reasonable limits for `maxReviews` and `pagesToScrape` to avoid timeouts
- Consider using filters to get more targeted results

### Common Use Cases

- **Business Intelligence**: Analyze customer sentiment and feedback
- **Competitive Analysis**: Compare reviews across similar businesses
- **Market Research**: Understand customer preferences and pain points
- **Reputation Management**: Monitor reviews for specific keywords or issues
- **Trend Analysis**: Track review patterns and sentiment over time
- **Location Analysis**: Compare performance across multiple locations

### Error Handling

The actor includes comprehensive error handling:

- Invalid place IDs or URLs are detected and reported
- Network timeouts are handled with automatic retries
- Parsing errors are logged with detailed information
- Empty responses and rate limiting are gracefully handled
- Cookie management for authentication

### Performance Notes

- Processing speed depends on the number of reviews and applied filters
- Memory usage scales with the number of reviews being processed
- Larger `reviewsPerPage` values may be faster but use more memory
- Use filters to reduce processing time for large datasets

### Data Quality

- Reviews include original text and translated text when available
- Photos are extracted with full URLs
- Owner responses are captured when present
- Timestamps are provided in both Unix format and ISO date strings
- Duplicate reviews are automatically filtered when `uniqueOnly` is enabled

### Support

For issues, feature requests, or questions:

1. Check the actor run logs for detailed error messages
2. Verify the place ID or URL is correct and the place has reviews
3. Try with smaller batch sizes if encountering timeouts
4. Ensure your filters are not too restrictive
5. Contact support through the Apify platform

### Result limits and billing

`maxReviews` limits the number of dataset items after filtering. `startPage` skips earlier pages; those pages still have to be read. Filters, including `searchQuery`, apply to collected reviews. `pagesToScrape: -1` continues until the list ends, the result limit or charge limit is reached, or the source stops supplying reviews.

A failed first page fails the run. If later pages remain unavailable after retries, the actor saves collected results and sets `partial: true` in the `RUN_SUMMARY` key-value record.

This build supports Pay-Per-Event; live pricing remains the pricing shown in the Apify Store until the owner changes it. Under PPE, each saved review is automatically billed through the dataset-item event. Successful runs returning fewer than 10 reviews receive a `review` event top-up to a minimum of 10 billable reviews, including a successfully read list whose filters match nothing. A run that fails outright receives no minimum charge. Output and the minimum respect your maximum charge.

# Actor input Schema

## `placeIdOrUrl` (type: `string`):

Google Maps place ID (e.g., '0x14a839000bbc66dd:0x517edaab612d6d13') or full Google Maps URL. Example prefill: the Eiffel Tower, Paris

## `startPage` (type: `integer`):

Page number to start scraping from

## `pagesToScrape` (type: `integer`):

Maximum number of pages to scrape (-1 for all available)

## `reviewsPerPage` (type: `string`):

Number of reviews per page to scrape

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

Maximum number of reviews to scrape (-1 for no limit)

## `sortBy` (type: `string`):

How to sort the reviews

## `ratings` (type: `array`):

Filter reviews by star ratings (1-5)

## `language` (type: `array`):

Filter reviews by language (e.g. 'en', 'fr', 'de')

## `keywords` (type: `array`):

Filter reviews containing specific keywords

## `endDate` (type: `string`):

Only include reviews up to this date (YYYY-MM-DD)

## `recentDays` (type: `integer`):

Only include reviews from the last N days (0 = no limit)

## `uniqueOnly` (type: `boolean`):

Only include unique reviews (by reviewId)

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

Search for reviews containing specific terms (optional)

## Actor input object example

```json
{
  "placeIdOrUrl": "ChIJLU7jZClu5kcR4PcOOO6p3I0",
  "startPage": 1,
  "pagesToScrape": 2,
  "reviewsPerPage": "10",
  "maxReviews": 20,
  "sortBy": "mostRelevant",
  "ratings": [
    4,
    5
  ],
  "language": [
    "en",
    "fr",
    "de"
  ],
  "keywords": [
    "great",
    "bad"
  ],
  "endDate": "",
  "recentDays": 0,
  "uniqueOnly": true,
  "searchQuery": ""
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# 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 = {
    "placeIdOrUrl": "ChIJLU7jZClu5kcR4PcOOO6p3I0",
    "maxReviews": 20,
    "sortBy": "mostRelevant",
    "ratings": [
        1,
        2,
        3,
        4,
        5
    ],
    "keywords": [],
    "endDate": "",
    "searchQuery": ""
};

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

# Prepare the Actor input
run_input = {
    "placeIdOrUrl": "ChIJLU7jZClu5kcR4PcOOO6p3I0",
    "maxReviews": 20,
    "sortBy": "mostRelevant",
    "ratings": [
        1,
        2,
        3,
        4,
        5,
    ],
    "keywords": [],
    "endDate": "",
    "searchQuery": "",
}

# Run the Actor and wait for it to finish
run = client.actor("neatrat/google-maps-reviews-scraper").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 '{
  "placeIdOrUrl": "ChIJLU7jZClu5kcR4PcOOO6p3I0",
  "maxReviews": 20,
  "sortBy": "mostRelevant",
  "ratings": [
    1,
    2,
    3,
    4,
    5
  ],
  "keywords": [],
  "endDate": "",
  "searchQuery": ""
}' |
apify call neatrat/google-maps-reviews-scraper --silent --output-dataset

```

## MCP server setup

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

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/yoQ74pqptH5OG0EEs/builds/EdO7cWTsAov6gC3kq/openapi.json
