# Google Maps Grid-Based Market Saturation Scanner (`dataspryva/google-maps-grid-based-market-saturation-scanner`) Actor

Cover a bounding box, circle, or custom polygon with a search grid to collect every business Google Maps exposes for a query, well beyond the usual 120-result cap on a single search.

- **URL**: https://apify.com/dataspryva/google-maps-grid-based-market-saturation-scanner.md
- **Developed by:** [Dataspryva](https://apify.com/dataspryva) (community)
- **Categories:** Lead generation, SEO tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 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?

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 Grid-Based Market Saturation Scanner

A single Google Maps search typically stops at around 120 listings no matter how large the area. This actor covers your target area with a grid of small search zones, reads each zone's full ranked result window, and deduplicates everything by Place ID — so a city-wide or region-wide query returns the complete set of businesses Google exposes, not just the first screen.

### What this actor does

- Covers a bounding box, circle, GeoJSON polygon, or named location with a grid of search zones.
- Reads each zone's complete result window (up to ~260 places across pages), not just the first 20.
- Collects rich listing data — category, address, rating, reviews, phone, website, hours, coordinates — without opening individual place pages.
- Streams accepted businesses into the dataset as the grid is covered, deduplicating overlapping zones by Place ID.
- Optionally opens each place page for extras: price level, Plus Code, photo sample, rating histogram, open/closed status.
- Empty fields are omitted.

### Output per business

With `enrichDetails=false` (the scalable default), each record contains everything Google's listing window exposes:

| Field | Description |
|---|---|
| `recordType` | Always `"business"`. |
| `name` | Business name. |
| `categories[]` / `categoryName` | All observed categories; the first is the primary one. |
| `address` | Full formatted address, when Google exposes one. |
| `totalScore` / `reviewsCount` | Displayed star rating and review total, when present. |
| `phone` / `website` | Public contact fields, when present. |
| `hours` | Weekly opening hours (`monday`…`sunday`), when Google exposes them; closed days read `Closed`, around-the-clock days read `Open 24 hours`. |
| `location` | Place centroid `lat`/`lng` — always the business location, never the map viewport. |
| `placeId` / `featureId` / `kgmid` | Canonical Place ID (`ChIJ…`), legacy feature ID, and Knowledge Graph ID. |
| `timezone` / `countryCode` | IANA timezone and ISO country of the place. |
| `rankInCell` | Position in the ranked window of the grid cell that found it (1 = top). |
| `googleMapsUrl` / `sourceUrl` | Stable Google Maps place URL. |
| `scrapedAt` | UTC extraction timestamp. |

With `enrichDetails=true`, records can additionally contain `plusCode`, `photoCount`, `photosSample` (up to ten public gallery images), `ratingHistogram` (1–5★ counts), `hoursStatus`, `isOpenNow`, `isPermanentlyClosed`, and `isTemporarilyClosed` — each only when Google publishes it. `priceLevel` is kept for compatibility but is almost never shown by Google Maps today.

### Input

You must provide **one** way to define the geographic area to scan:

- **Bounding box** (recommended) — `boundingBox` with `north`/`south`/`east`/`west`. Requires `south < north` and `west < east`; inverted or out-of-range coordinates are rejected.
- **Circle** — `circleCenter` (`lat`/`lng`) plus `radiusKm` (`0 < radiusKm ≤ 50`). The grid covers the circle's box; records are then checked against the exact great-circle radius.
- **GeoJSON polygon** — `customGeolocation`, a GeoJSON Polygon. Cells touching the outer ring are searched; records are checked against the exact boundary, with interior rings treated as holes.
- **Named location** — `locationName` (e.g. `"Brooklyn, NY"`). Google resolves the location's real center, then the actor scans `radiusKm` around it; use a bounding box or polygon when an exact boundary matters.

| Field | Type | Default | Description |
|---|---|---|---|
| `searchQuery` | String | – | **Required.** What to search for, e.g. `pharmacy`, `restaurant`, `hotel`. |
| `locationName` | String | – | Named public location to center the scan on (one of the four area options). |
| `boundingBox` | Object | – | Rectangular scan area (one of the four area options). |
| `circleCenter` | Object | – | Center point (`lat`/`lng`) for a circular scan area (one of the four area options). |
| `radiusKm` | Number | `5` | Radius in kilometers, used with `circleCenter` or `locationName` (0.1–50). |
| `customGeolocation` | Object | – | GeoJSON Polygon defining the scan boundary (one of the four area options). |
| `zoomLevel` | Integer | `15` | Grid cell granularity (12–18); higher means smaller cells and more thorough coverage. |
| `maxPlacesPerCell` | Integer | `120` | Maximum businesses collected from each cell (1–260). |
| `maxPagesPerCell` | Integer | `13` | Result pages read per cell (1–13). More pages surface more businesses — page one finds around 20% of a cell's places; all pages find all of them. |
| `maxTotalResults` | Integer | `10000` | Maximum businesses across all cells (1–100000). |
| `deduplicateResults` | Boolean | `true` | Remove duplicates that appear across adjacent cells. |
| `enrichDetails` | Boolean | `false` | Open each place page for the extra detail fields listed above. Slower. |
| `minRating` | Number | – | Only include businesses rated at or above this value (1.0–5.0); works in fast mode. |
| `language` | String (select) | `"en"` | Results language: English, Spanish, French, German, Italian, Portuguese, Japanese, Korean, Chinese, Arabic, or Russian. |

#### Zoom level guide

| Zoom | Cell size | Best for |
|---|---|---|
| 12 | ~5 km | Large rural areas, quick overview |
| 13 | ~2.5 km | Suburban regions |
| 14 | ~1.25 km | Mixed urban/suburban |
| 15 (default) | ~625 m | Balanced coverage for most use cases |
| 16 | ~312 m | Dense urban areas |
| 17 | ~156 m | Very dense areas |
| 18 | ~78 m | Maximum detail |

#### Example: bounding-box scan

```json
{
    "searchQuery": "coffee shops",
    "boundingBox": {"north": 40.76, "south": 40.73, "east": -73.97, "west": -74.02},
    "maxTotalResults": 1000,
    "enrichDetails": false
}
```

#### Example: circle scan with detail enrichment

```json
{
    "searchQuery": "pharmacies",
    "circleCenter": {"lat": 40.7128, "lng": -74.0060},
    "radiusKm": 5,
    "enrichDetails": true
}
```

#### Example: polygon scan

```json
{
    "searchQuery": "restaurants",
    "customGeolocation": {
        "type": "Polygon",
        "coordinates": [[[-74.02, 40.73], [-73.97, 40.73], [-73.97, 40.76], [-74.02, 40.76], [-74.02, 40.73]]]
    },
    "maxTotalResults": 5000
}
```

#### Example: named location with a high rating filter

```json
{
    "searchQuery": "dentists",
    "locationName": "Austin, TX",
    "radiusKm": 10,
    "minRating": 4.5,
    "maxTotalResults": 500
}
```

### Use cases

- **Market mapping** — find every business of a given type across a whole city district or region.
- **Competitor density analysis** — map all restaurants, gyms, or clinics in a neighborhood to gauge saturation.
- **Site selection** — analyze business density and category mix before choosing a new location.
- **Lead generation** — collect contact details for every matching business across a target area.
- **Franchise/territory planning** — compare how many competing locations exist across candidate regions.
- **Local SEO research** — use `rankInCell` to see which businesses dominate each block of a search area.

### Tips for best results

- Start with a small test area to confirm your `searchQuery` returns the results you expect before scanning a large region.
- Zoom level 15 is a good balance of coverage and speed for most areas.
- Keep `deduplicateResults` on to avoid counting the same business twice across adjacent cells.
- Records appear in the dataset progressively as the scan runs, not only once the whole area finishes.
- Different phrasings of the same idea surface different businesses — run a synonym (e.g. `coffee` and `cafe`) and merge the datasets when you need maximum recall.

### Limitations

- Coverage per zone is limited by Google's ranked window: one zone query exposes roughly 140–210 distinct places at most, and a dense 625 m cell typically contributes around 10 new businesses. A 10,000-place export therefore needs many cells and can take a while.
- Very dense categories (e.g. every restaurant in Manhattan) need a finer zoom level: halving the cell size roughly doubled the unique places found in a dense 1 km² test (51 → 98), and a 4× finer grid with every page read found 179 (about 12× the zoom-15 requests). For a quick sweep stay at zoom 15; for maximum saturation use zoom 16–17 and keep all pages.
- Bounding-box, circle, and polygon scans require an observed place coordinate; a listing without one is omitted rather than assigned a guessed point.
- Fast mode has no Plus Code, photo gallery, photo count, rating histogram, or open/closed status — enable `enrichDetails` for those.
- `rankInCell` is the position in that scan's ranked window; Google's ordering shifts slightly between runs (about 60% of places stay within two positions on a repeat scan), so treat it as approximate rather than a stable rank metric.
- Coverage depends on what Google exposes for each zone at run time and can vary slightly between runs.

You are responsible for using the collected data lawfully and in line with Google's terms.

### FAQ

**Does this guarantee every business in an area?**
No. Coverage depends on what Google exposes for each zone, the chosen language, and run-time variation — but grid scanning recovers far more than a single capped search would.

**How should I scan a large area quickly?**
Leave `enrichDetails` off and leave `minRating` empty. Fast mode collects the full listing field set without opening any place page.

**Why do more pages mean more results?**
Google ranks each zone's results; a business deep in the ranking only appears on a later page. Page one holds about 20% of a cell's places, and the full window is reached around page nine, which is why the default reads every page. Finer cells also help, but only when every page is read: in a dense 1 km² test, zoom 15 found 51 unique places, zoom 16 found 98, and zoom 17 with all pages found 179 — at progressively higher request counts.

**Can it return more than 10,000 places?**
Yes — `maxTotalResults` accepts up to 100,000 and the scan continues across cells as long as Google keeps exposing real places. The practical limits are cell count and time.

**What happens when a grid cell is blocked or empty?**
The actor records only businesses actually observed in that cell and reports a truthful partial or complete result rather than padding the dataset with guesses.

**What's the difference between `placeId`, `featureId`, and `kgmid`?**
`placeId` is Google's canonical place token (`ChIJ…`). `featureId` is a legacy token (`0x…:0x…`) and is never relabeled as a Place ID. `kgmid` is the Knowledge Graph identifier (`/g/…`), when exposed.

**Do I need cookies or a login?**
No. The actor reads public Google Maps surfaces without any login session.

**Do I need to set up a proxy?**
No. The actor chooses a working connection to Google Maps automatically. Just fill in the input and run it.

**Is this affiliated with Google?**
No. This actor reads publicly available Google Maps pages and is not affiliated with or endorsed by Google.

# Actor input Schema

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

Type of business to search for (e.g., 'pharmacy', 'restaurant', 'dentist').

## `locationName` (type: `string`):

Name of a public Google Maps location (e.g., 'Brooklyn, NY'). Google resolves its real center anonymously, then the actor scans the user-controlled radiusKm around it. Use boundingBox or GeoJSON for exact boundaries.

## `boundingBox` (type: `object`):

Geographic bounding box defining the scan area. Provide north/south/east/west coordinates.

## `circleCenter` (type: `object`):

Center point for a circular scan area. Use with radiusKm.

## `radiusKm` (type: `number`):

Radius in kilometers for circular scan area (used with circleCenter or locationName).

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

Custom GeoJSON Polygon defining the scan boundary.

## `zoomLevel` (type: `integer`):

Controls grid cell granularity. Higher = smaller cells, more thorough coverage.

## `maxPlacesPerCell` (type: `integer`):

Maximum businesses to collect from each grid cell (1–260; Google's ranked window for one cell reaches roughly 136–213 places).

## `maxPagesPerCell` (type: `integer`):

How many 20-result pages to read per cell. Deeper pages surface more businesses — page 1 finds about 20% of a cell's places, page 9 finds all of them.

## `maxTotalResults` (type: `integer`):

Maximum total businesses to extract across all cells. Stops scanning when reached.

## `deduplicateResults` (type: `boolean`):

Remove duplicate businesses that appear in multiple adjacent grid cells.

## `enrichDetails` (type: `boolean`):

Open each place's page for extra fields (price level, Plus Code, photo sample, rating histogram, open/closed status). Slower; leave off for large exports since listing fields are always collected.

## `minRating` (type: `number`):

Only include businesses with a rating at or above this value (1.0–5.0). Leave empty to include all.

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

Language for Google Maps interface and results.

## Actor input object example

```json
{
  "searchQuery": "coffee shops",
  "boundingBox": {
    "north": 40.77,
    "south": 40.73,
    "east": -73.97,
    "west": -74.01
  },
  "radiusKm": 5,
  "zoomLevel": 15,
  "maxPlacesPerCell": 5,
  "maxPagesPerCell": 13,
  "maxTotalResults": 5,
  "deduplicateResults": true,
  "enrichDetails": false,
  "language": "en"
}
```

# Actor output Schema

## `businesses` (type: `string`):

Dataset of public Google Maps businesses collected across the requested geographic grid. Listing mode includes name, categories, address, rating, review count, phone, website, weekly hours, timezone, country, coordinates, place identifiers, and the in-cell rank; detail enrichment adds Plus Code, photo count, photo sample, rating histogram, and observed open/closed status.

# 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 = {
    "searchQuery": "coffee shops",
    "boundingBox": {
        "north": 40.77,
        "south": 40.73,
        "east": -73.97,
        "west": -74.01
    },
    "zoomLevel": 15,
    "maxPlacesPerCell": 5,
    "maxPagesPerCell": 13,
    "maxTotalResults": 5,
    "deduplicateResults": true,
    "enrichDetails": false
};

// Run the Actor and wait for it to finish
const run = await client.actor("dataspryva/google-maps-grid-based-market-saturation-scanner").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 = {
    "searchQuery": "coffee shops",
    "boundingBox": {
        "north": 40.77,
        "south": 40.73,
        "east": -73.97,
        "west": -74.01,
    },
    "zoomLevel": 15,
    "maxPlacesPerCell": 5,
    "maxPagesPerCell": 13,
    "maxTotalResults": 5,
    "deduplicateResults": True,
    "enrichDetails": False,
}

# Run the Actor and wait for it to finish
run = client.actor("dataspryva/google-maps-grid-based-market-saturation-scanner").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 '{
  "searchQuery": "coffee shops",
  "boundingBox": {
    "north": 40.77,
    "south": 40.73,
    "east": -73.97,
    "west": -74.01
  },
  "zoomLevel": 15,
  "maxPlacesPerCell": 5,
  "maxPagesPerCell": 13,
  "maxTotalResults": 5,
  "deduplicateResults": true,
  "enrichDetails": false
}' |
apify call dataspryva/google-maps-grid-based-market-saturation-scanner --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,dataspryva/google-maps-grid-based-market-saturation-scanner"
        }
    }
}
```

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/lEvpsUsigS536O8Wg/builds/qAmn3PoCcJy3rIf24/openapi.json