# Google Maps Scraper (`calm_builder/google-maps-scraper`) Actor

Scrape Google Maps business listings by search term and location. Extract names, addresses, phone numbers, websites, emails, opening hours, ratings, reviews, categories, coordinates and place IDs. Covers whole cities, states and countries. No API key needed. Results stream in live.

- **URL**: https://apify.com/calm\_builder/google-maps-scraper.md
- **Developed by:** [Coder](https://apify.com/calm_builder) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.75 / 1,000 places

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/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 Scraper

Get every business on Google Maps that matches what you are looking for, anywhere in the world.

Search `dentist` in Manhattan, `hotels` across Malta, or `coffee shop` in one postcode, and get back a clean table: names, addresses, phone numbers, websites, opening hours, ratings, review counts, categories, coordinates and place IDs. Add reviews, photos and website contact details when you need them.

Results appear while the run is still going, so you can start working with them before it finishes.

### What you get

Every place comes with:

- **Contact** — name, full address broken into street, city, state, postcode and country, phone number in both display and dialling form, website, plus code and coordinates
- **Ratings** — average rating, review count, and the star breakdown
- **Opening hours** — per day, including split hours and closures
- **Categories** — the main category and every other one Google lists
- **Identifiers** — place ID, CID and a direct Google Maps link
- **Status** — permanently or temporarily closed

Turn on **full place details** and each place also brings its description, price level, service options and amenities, review keywords, popular times, menu and booking links, and the extras that apply to its type — star rating, check-in and check-out times and room offers for hotels, current fuel prices for petrol stations.

Turn on **reviews** for the review text, star rating, date, reviewer, owner reply, photos and the per-category ratings such as food, service and atmosphere. Reviews arrive in their own table, one row per review, and are also included with each place.

Turn on **website contact details** to get the email addresses, extra phone numbers, social media profiles and postal addresses that are on a business's own website but not on Google Maps. This is what turns a list of places into a list you can actually contact.

Turn on **photos** to collect each place's gallery, at full resolution.

### How to use it

1. Enter one or more **search terms** — what you would type into Google Maps.
2. Enter a **location** — a city, region or country. Whole states and countries work; set a place limit so the run stays predictable.
3. Choose what to collect, and run it.

#### Narrowing the search

You rarely want everything a search returns. The **Only collect places that…** options let you keep only the places worth having:

- in one of the categories you name
- rated at or above a minimum
- with at least a minimum number of reviews, which is the quickest way to drop dormant and duplicate listings
- with a website, or without one — outreach lists usually want one or the other
- still open

**Filtering is free, and a place that gets filtered out is never charged.** Narrowing a run makes it cheaper and faster, not more expensive.

#### Being precise about where

For most runs, typing the location is enough. When a name is ambiguous, or you need an exact area, use **Precise area**:

- **City, state, county** — for when a place name repeats in several regions
- **Postcode** — one at a time, with the country set; only places inside it are kept
- **Custom area** — draw the area yourself as GeoJSON, for a delivery zone or a sales territory that no administrative boundary matches

#### Specific places

Already know which places you want? Paste **Google Maps links** or **place IDs** and skip the search. Useful for refreshing a list you collected earlier, since a place ID never changes.

### Output

Two tables.

**Places** — one row per place, with reviews and photos nested inside it.

```json
{
  "title": "Buena Vista",
  "categoryName": "Restaurant",
  "categories": ["Restaurant", "Bar", "Peruvian restaurant"],
  "address": "251 W 30th St, New York, NY 10001",
  "street": "251 W 30th St",
  "city": "New York",
  "state": "NY",
  "postalCode": "10001",
  "countryCode": "US",
  "phone": "(212) 555-0148",
  "phoneUnformatted": "+12125550148",
  "website": "https://example-restaurant.com",
  "totalScore": 4.6,
  "reviewsCount": 1512,
  "reviewsDistribution": {
    "oneStar": 34,
    "twoStar": 21,
    "threeStar": 68,
    "fourStar": 260,
    "fiveStar": 1129
  },
  "openingHours": [{ "day": "Monday", "hours": "11:30 AM–10 PM" }],
  "location": { "lat": 40.7484, "lng": -73.9967 },
  "placeId": "ChIJdw_prS5DIjkRim7FRjjIswU",
  "url": "https://www.google.com/maps/place/?q=place_id:ChIJdw_prS5DIjkRim7FRjjIswU"
}
```

**Reviews** — one row per review, carrying the place it belongs to, so you can sort, filter and export reviews on their own.

```json
{
  "placeTitle": "Buena Vista",
  "placeId": "ChIJdw_prS5DIjkRim7FRjjIswU",
  "stars": 5,
  "text": "A must try when visiting NYC. The staff is very friendly and attentive.",
  "publishedAtDate": "2026-04-18T12:37:31.859Z",
  "name": "Abigail Curran",
  "isLocalGuide": true,
  "reviewDetailedRating": { "Food": 5, "Service": 5, "Atmosphere": 5 },
  "responseFromOwnerText": "Thank you, Abigail — we're delighted you enjoyed it.",
  "responseFromOwnerDate": "2026-04-18T15:10:21.000Z"
}
```

Export either as JSON, CSV, Excel or XML, or pull them through the API.

### Good to know

- **Review privacy.** Reviewer names, photos and profile links can be left out with one switch, for when your data policy limits what personal information you may store.
- **Language and country.** Set the language to get place names, categories, hours and review translations in it. Set the country to see an area the way someone searching from there would — it changes address formats, currencies and which nearby places Google treats as relevant.
- **Large areas.** Set a per-search limit on a country or large region — results are taken from across the map up to that limit. For exhaustive coverage of a dense city, run it on its own.
- **Places without a website** are skipped by the contact lookup and are never charged for it.

### Common uses

- **Lead lists** — every plumber, dentist or agency in a region, with phone, website and email
- **Finding businesses with no website** — filter to places without one, and you have a prospect list
- **Market research** — how many competitors are in an area, how they are rated, when they are busy
- **Review analysis** — pull thousands of reviews for a place or a category and read what customers actually say
- **Store and franchise mapping** — every branch of a chain in a country, with coordinates
- **Keeping a database fresh** — re-run against your place IDs to pick up closures, moves and new phone numbers

### FAQ

**Do I need a Google API key?**
No. Nothing to set up and no quota to manage.

**Can I scrape a whole country?**
Yes. Set a limit and results are collected from across the whole country, not just one corner of it. For exhaustive coverage of a dense area, run it city by city.

**How many reviews can I get per place?**
As many as the place has. Sort by newest, most relevant, highest or lowest, cut off at a date, or keep only reviews mentioning a particular word.

**Will I be charged for places I filter out?**
No. Filters are applied before a place is collected, so anything ruled out costs you nothing.

**Can I get email addresses?**
Yes — turn on website contact details. Emails come from the business's own website, since Google Maps does not list them.

**Is scraping Google Maps legal?**
This Actor collects publicly available business information, the same data anyone can see on Google Maps without signing in. It does not access private data or bypass logins. You are responsible for how you use the results, including under GDPR and similar laws where personal data is involved — which is why reviewer details can be switched off.

# Actor input Schema

## `searchStringsArray` (type: `array`):

Enter one search term per row, exactly as you would type it into Google Maps — `dentist`, `coffee shop`, `plumber`, or a brand name like `Starbucks`.

Each term is searched across the whole location you set below.

## `locationQuery` (type: `string`):

A city, region or country — `Jersey City, New Jersey`, `Manhattan, New York`, `Malta`.

Keep it simple: `City, Country` reads better than `Neighbourhood, City, State, Country`. Large areas work — set a place limit and results are taken from across the whole area, not just one corner. For exhaustive coverage of a dense area, run it city by city.

This is all most runs need. If the name is ambiguous, or you want an exact boundary, use **Precise area** at the bottom instead.

## `countryCode` (type: `string`):

Google shows different results depending on where you are searching from. This sets that country — it decides the address format, the currency prices are quoted in, the spelling variant, and which nearby places Google treats as relevant.

**Set automatically** picks the country of the location you entered above, which is right for almost every run. Change it only when you want to see an area the way someone in a different country would.

## `maxCrawledPlacesPerSearch` (type: `integer`):

How many places to collect for each search term. Leave empty to collect everything in the area.

Larger areas hold more places than you might expect — a city can return thousands for a common term. On a large area such as a country, this is also what decides how much of the map gets searched.

## `searchMatching` (type: `string`):

Google decides for itself what is relevant to your term, which is usually what you want — but not when you are after one specific business.

- **Anything relevant** — everything Google returns, including similar businesses nearby.
- **Name contains the term** — searching `Starbucks` gives you Starbucks, not the café next door.
- **Name matches exactly** — strictest, for a single chain and nothing else.

Free.

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

The language Google answers in. Place names, categories, opening-hours text, service options and review translations all come back in this language.

Reviews keep their original text as well, so a review written in Spanish stays in Spanish and is also translated into the language you pick here.

## `categoryFilterWords` (type: `array`):

Every place on Google Maps carries a category — `Dentist`, `Coffee shop`, `Italian restaurant`, `Law firm`. This keeps only the places whose category matches one of the words you enter here.

It is the fix for a search that pulls in the wrong kind of business: searching `coffee` also returns bakeries, bookshops and restaurants, so adding `coffee shop` here removes them. Matching ignores case and matches part of the category, so `restaurant` keeps `Italian restaurant` and `Seafood restaurant` too.

Leave it empty to keep every category. This filter is free, and places it removes are never charged.

## `placeMinimumStars` (type: `string`):

Keep only places at or above this rating. Places with no rating yet are dropped once you set one.

Free.

## `minimumReviews` (type: `integer`):

Drop thin listings. A business with two reviews is often dormant, duplicated or somebody's spare room, and on a lead list those are the rows you delete by hand.

`10` is a good cut-off for an established business, `50` for a busy one. Leave at `0` to keep everything.

Places whose review count Google does not return are kept. Free.

## `website` (type: `string`):

Keep only places that have a website, or only those that do not.

Places **without** a website are the usual target for web design and marketing outreach; places **with** one pair well with **Website contact details** below.

This filter is free.

## `skipClosedPlaces` (type: `boolean`):

Leave out anything Google marks as permanently or temporarily closed.

On by default — closed businesses are rarely what anyone is after. Free.

## `scrapePlaceDetails` (type: `boolean`):

Open every place to collect everything Google holds about it: description, price level, service options and amenities, review keywords, rating breakdown, popular times, plus code, menu and booking links, and hotel or fuel details where they apply.

With this off you still get the core fields — name, address, phone, website, opening hours, rating, review count, categories and coordinates.

## `scrapeContacts` (type: `boolean`):

Visit each place's website and pull the contact details that are not on Google Maps: email addresses, extra phone numbers, social media profiles and postal addresses.

Useful for building outreach lists, since most listings show a website but no email. Places without a website are skipped and never charged.

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

How many reviews to collect for each place. Leave at `0` to skip reviews entirely.

Each review comes with its text, star rating, date, reviewer name and profile, owner reply, photos and the per-category ratings such as food, service and atmosphere.

Reviews are saved to their own **Reviews** table, one row per review, and are also included inside each place record.

## `reviewsSort` (type: `string`):

Which reviews you get when you ask for fewer than a place has.

## `reviewsStartDate` (type: `string`):

Skip anything older. Use a date such as `2026-01-31`, or a period counted back from now such as `7 days`, `3 months` or `1 year`.

Works best with **Newest first**, where collecting stops as soon as the reviews get too old.

## `reviewsFilterString` (type: `string`):

Keep only reviews containing this word or phrase — `parking`, `gluten free`, `rude staff`.

Leave empty to keep them all. This filter is free.

## `scrapeReviewsPersonalData` (type: `boolean`):

Keep the reviewer's name, photo and profile link on each review.

Turn this off to get the review text, rating and date with the reviewer anonymised — useful when your data policy limits what personal information you may store.

This option is free.

## `maxImages` (type: `integer`):

How many photos to collect for each place, from its Google Maps gallery. Leave at `0` to skip photos.

You always get the main listing photo for free, with or without this.

## `startUrls` (type: `array`):

Collect specific places instead of searching. Paste Google Maps links to individual places, or search and directions links copied from your browser.

Can be combined with a search above, or used on its own.

## `placeIds` (type: `array`):

Google place IDs, one per row — for example `ChIJdw_prS5DIjkRim7FRjjIswU`.

Handy for refreshing a list you collected earlier, since a place ID never changes.

## `city` (type: `string`):

Used instead of **Where to search**. Enter the city on its own — for example `Pittsburgh`, not `Pittsburgh, PA, USA`.

## `state` (type: `string`):

Used instead of **Where to search**, together with the city. For example `Massachusetts` — worth setting where city names repeat across regions.

## `county` (type: `string`):

Used instead of **Where to search**. For example `New York County`. The equivalent area is used elsewhere, such as a district or département.

## `postalCode` (type: `string`):

One postcode at a time — for example `10001`. Set the country above; do not combine it with a city.

Only places inside the postcode are kept. Neighbouring ones are dropped before they are collected, so they cost you nothing.

## `postalCodeRadiusKm` (type: `integer`):

Used with **Postcode** only. How far around the centre of the postcode to look, in kilometres.

Raise it for a rural postcode that covers a lot of ground, lower it for a dense city one.

## `customGeolocation` (type: `object`):

Draw the area yourself as GeoJSON, when no city, county or postcode matches the shape you need — a delivery zone, a sales territory, a stretch of coastline.

Takes a `Polygon` or `MultiPolygon`. Coordinates are `[longitude, latitude]`, in that order. Overrides every other location field.

## Actor input object example

```json
{
  "searchStringsArray": [
    "coffee shop"
  ],
  "locationQuery": "Jersey City, New Jersey",
  "countryCode": "",
  "maxCrawledPlacesPerSearch": 100,
  "searchMatching": "all",
  "language": "en",
  "placeMinimumStars": "",
  "minimumReviews": 0,
  "website": "",
  "skipClosedPlaces": true,
  "scrapePlaceDetails": true,
  "scrapeContacts": false,
  "maxReviews": 0,
  "reviewsSort": "newest",
  "scrapeReviewsPersonalData": true,
  "maxImages": 0,
  "postalCodeRadiusKm": 3,
  "customGeolocation": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          -74.05,
          40.7
        ],
        [
          -73.95,
          40.7
        ],
        [
          -73.95,
          40.78
        ],
        [
          -74.05,
          40.78
        ],
        [
          -74.05,
          40.7
        ]
      ]
    ]
  }
}
```

# Actor output Schema

## `places` (type: `string`):

No description

## `reviews` (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 = {
    "searchStringsArray": [
        "coffee shop"
    ],
    "locationQuery": "Jersey City, New Jersey",
    "maxCrawledPlacesPerSearch": 100,
    "customGeolocation": {
        "type": "Polygon",
        "coordinates": [
            [
                [
                    -74.05,
                    40.7
                ],
                [
                    -73.95,
                    40.7
                ],
                [
                    -73.95,
                    40.78
                ],
                [
                    -74.05,
                    40.78
                ],
                [
                    -74.05,
                    40.7
                ]
            ]
        ]
    }
};

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

# Prepare the Actor input
run_input = {
    "searchStringsArray": ["coffee shop"],
    "locationQuery": "Jersey City, New Jersey",
    "maxCrawledPlacesPerSearch": 100,
    "customGeolocation": {
        "type": "Polygon",
        "coordinates": [[
                [
                    -74.05,
                    40.7,
                ],
                [
                    -73.95,
                    40.7,
                ],
                [
                    -73.95,
                    40.78,
                ],
                [
                    -74.05,
                    40.78,
                ],
                [
                    -74.05,
                    40.7,
                ],
            ]],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("calm_builder/google-maps-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 '{
  "searchStringsArray": [
    "coffee shop"
  ],
  "locationQuery": "Jersey City, New Jersey",
  "maxCrawledPlacesPerSearch": 100,
  "customGeolocation": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          -74.05,
          40.7
        ],
        [
          -73.95,
          40.7
        ],
        [
          -73.95,
          40.78
        ],
        [
          -74.05,
          40.78
        ],
        [
          -74.05,
          40.7
        ]
      ]
    ]
  }
}' |
apify call calm_builder/google-maps-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,calm_builder/google-maps-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/EJJEtTw4b5gPpdohv/builds/FrLwUNhIZ2B4lLS8F/openapi.json