# Google Maps Business Leads Scraper — Phone, Email & Socials (`foxlabs/google-maps-scraper`) Actor

Scrape Google Maps local businesses by keyword, category, city/ZIP, coordinates, or Maps URL. Extracts Place ID, ratings, review counts, phone numbers, street addresses, opening hours, attributes, websites, and enriched business emails & social profiles. No API key required.

- **URL**: https://apify.com/foxlabs/google-maps-scraper.md
- **Developed by:** [Berkan Kaplan](https://apify.com/foxlabs) (community)
- **Categories:** Lead generation, Business, AI
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.50 / 1,000 google maps place leads

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

<p align="center">
  <img src="https://img.shields.io/badge/Pay--Per--Event-Places_%2B_Optional_Emails-00C853?style=for-the-badge" alt="Pay-Per-Event" />&nbsp;
  <img src="https://img.shields.io/badge/53_Lead_Columns-Place_ID_%C2%B7_Phone_%C2%B7_Socials-2962FF?style=for-the-badge" alt="53 Lead Columns" />&nbsp;
  <img src="https://img.shields.io/badge/AI_Agent_Ready-MCP_%26_x402-7C4DFF?style=for-the-badge" alt="MCP &amp; x402 Ready" />&nbsp;
  <img src="https://img.shields.io/badge/Dual_Runtime-Batch_%2B_Standby_API-FF6D00?style=for-the-badge" alt="Batch + Standby API" />
</p>

## Google Maps Business Leads Scraper — Phone, Email, Website & Socials 📍

**foXLabs Local SMB, Industrial & Lead Generation Series:** [Yelp Business Leads](https://apify.com/foxlabs/yelp-business-scraper) · [Thomasnet US Manufacturers](https://apify.com/foxlabs/thomasnet-suppliers-scraper) · [Tripadvisor Reviews](https://apify.com/foxlabs/tripadvisor-reviews-scraper) · [Booking.com Hotels](https://apify.com/foxlabs/booking-hotels-scraper) · [Trustpilot Reviews](https://apify.com/foxlabs/trustpilot-reviews-scraper)

Extract verified local business leads from Google Maps by search query, category + city/ZIP, geographic viewport coordinates, or direct Google Maps URLs — without providing a Google Places API key, cookies, or external proxy credentials. Every extracted place includes **53 structured columns** out of the box: canonical `placeId`, `cid`, `fid`, `googleBusinessId`, Knowledge Graph `kgmid`, ratings, **1-to-5 star review count breakdown (`reviewsDistribution`)**, categories, E.164 & local phone numbers, street/neighborhood/city/state/ZIP/country address components, exact GPS coordinates, 7-day `openingHours`, `isClaimed` ownership status, accessibility/service `attributes`, high-resolution photos, and official `websiteUrl` — plus optional **external website contact enrichment (`enrichContacts`)** for verified business emails and 6 social media networks.

***

### 🤖 Quick Start for AI Agents, MCP & x402 Pipelines

- **Actor Slug:** `foxlabs/google-maps-scraper`
- **Execution Modes:** Standard Asynchronous **Batch** (`Actor.call`) and Real-Time HTTP **Standby** (`POST /scrape` + `GET /` readiness probe, documented in `.actor/openapi.json`).
- **Zero-Config Start:** Start with: `{"searchQueries":["Dentist in Austin, TX"],"maxPlacesPerQuery":20}`
- **Enriched B2B Cold-Outreach Start:** `{"searchQueries":["HVAC contractor in Dallas, TX"],"maxPlacesPerQuery":25,"enrichContacts":true,"onlyWithWebsite":true}`
- **MCP / LangChain / CrewAI / x402 Ready:** Every dataset record uses deterministic types (`number | null` for metrics, never `0` for unknown values), stable deduplication keys (`rowKey: "gmaps:<placeId>"`), and `$0.00` diagnostic rows (`rowType: "status"`) separated cleanly from billable `rowType: "place"` items.

***

### ✨ Why Choose This Google Maps Scraper?

1. **53 Structured Lead Columns in One Pass:** Unlike basic scrapers that only return name, rating, and raw address string, this actor extracts `placeId`, `cid` (`https://maps.google.com/?cid=...`), `fid`, `googleBusinessId`, `kgmid`, `reviewsDistribution` (`oneStar` through `fiveStar`), `isClaimed` (unclaimed GBP detection for marketing agencies!), `phoneE164`, parsed `streetAddress` / `neighborhood` / `city` / `state` / `postalCode` / `countryCode`, `timezone`, 7-day `openingHours`, `attributes`, and `photoUrls`.
2. **Optional Website Email & Social Media Enrichment (`enrichContacts`):** Crawls each business's official homepage and `/contact` or `/about` page to extract verified company emails (`emails[]`), secondary web phone numbers (`phonesFromWeb[]`), and social profiles (`instagram`, `facebook`, `linkedin`, `twitter`, `tiktok`, `youtube`) while filtering out Sentry, Wix, and image-asset false positives.
3. **Pre-Billing Lead Qualification Filters:** Filter by `minRating`, `minReviews`, `onlyWithWebsite`, and `onlyWithPhone` *before* dataset emission — disqualified places are skipped at **$0.00** event cost.
4. **Global Coverage (`language` + `countryCode` + Custom Coordinates):** Works across 200+ countries and ISO languages (`en`, `de`, `es`, `fr`, `pt`, `it`, `nl`, `tr`, `ja`, `ar`) using either natural-language location queries or explicit `latitude`, `longitude`, and `zoomMeters` viewport targeting.
5. **No Google Cloud API Bills:** Standard Google Places API charges `$32–$40+ per 1,000` Place Details requests and does **not** return business emails, social profiles, `isClaimed` flags, or 1–5 star distribution. This actor delivers richer lead intelligence starting at **$1.50 per 1,000 places**.

***

### 📊 Extracted Data Fields (53 Columns)

| Field | Type | Description |
|---|---|---|
| `rowType` | `string` | `"place"` for billable business records; `"status"` for free diagnostic notices |
| `rowKey` | `string` | Deterministic deduplication key (`gmaps:<placeId>`) |
| `placeId` | `string` | Canonical Google Maps Place ID (`ChIJ...`) |
| `cid` | `string \| null` | Numeric Google Maps Customer ID (`cid`) |
| `fid` | `string \| null` | Google Feature ID (`0x...:0x...`) |
| `googleBusinessId` | `string \| null` | Google Business Profile account/listing identifier |
| `kgmid` | `string \| null` | Google Knowledge Graph entity ID (`/g/...` or `/m/...`) |
| `name` | `string` | Official business title on Google Maps |
| `primaryCategory` | `string \| null` | Primary Google Business Profile category |
| `categories` | `string[]` | Full array of assigned GBP categories |
| `googleTypeId` | `string \| null` | Internal Google Maps classification token (e.g., `SearchResult.TYPE_DENTIST`) |
| `rating` | `number \| null` | Average star rating (`1.0`–`5.0`), or `null` if unrated |
| `reviewCount` | `number \| null` | Total Google review count, or `null` if unreviewed |
| `reviewsDistribution` | `object \| null` | Exact star breakdown: `{ oneStar, twoStar, threeStar, fourStar, fiveStar }` |
| `priceRange` | `string \| null` | Price tier symbol or spend bracket (`$`, `$$`, `$10–20`), or `null` |
| `businessStatus` | `string` | `"OPERATIONAL"`, `"CLOSED_TEMPORARILY"`, or `"CLOSED_PERMANENTLY"` |
| `isClaimed` | `boolean` | `true` when claimed by a verified Google Business Profile owner; `false` = high-intent agency prospect |
| `ownerTitle` | `string \| null` | Verified owner label from GBP |
| `phone` | `string \| null` | Local formatted telephone number (e.g., `(512) 961-6200`) |
| `phoneE164` | `string \| null` | International E.164 dialable phone number (`+15129616200`) for CRM/auto-dialers |
| `websiteUrl` | `string \| null` | Unwrapped external company website URL |
| `websiteDomain` | `string \| null` | Normalized root domain (`emergencydentistofaustin.com`) |
| `emails` | `string[]` | Verified business email addresses extracted when `enrichContacts: true` |
| `phonesFromWeb` | `string[]` | Additional `tel:` phone numbers discovered on the company website |
| `socialProfiles` | `object` | `{ instagram, facebook, linkedin, twitter, tiktok, youtube }` URLs |
| `contactPageUrl` | `string \| null` | Discovered `/contact` or `/about` URL crawled during enrichment |
| `contactsEnriched` | `boolean` | `true` when external website contact enrichment ran and succeeded |
| `formattedAddress` | `string \| null` | Complete street address string |
| `streetAddress` | `string \| null` | Street number and thoroughfare |
| `neighborhood` | `string \| null` | Local neighborhood or district name |
| `city` | `string \| null` | City / municipality |
| `state` | `string \| null` | State, province, or region |
| `postalCode` | `string \| null` | ZIP or postal code |
| `countryCode` | `string \| null` | Two-letter ISO country code (`US`, `GB`, `DE`, etc.) |
| `latitude` | `number \| null` | WGS84 latitude |
| `longitude` | `number \| null` | WGS84 longitude |
| `timezone` | `string \| null` | IANA timezone identifier (e.g., `America/Chicago`) |
| `shortDescription` | `string \| null` | Concise place tagline |
| `editorialSummary` | `string \| null` | Full Google editorial summary |
| `openingHours` | `object[] \| null` | 7-day schedule array (`[{ day: "Monday", hours: "7 AM–7 PM" }, ...]`) |
| `isOpen24Hours` | `boolean \| null` | `true` if open 24 hours across all listed days |
| `highlights` | `string[] \| null` | Ownership/identity badges (e.g., `Women-owned`, `Veteran-owned`, `LGBTQ+ friendly`) |
| `attributes` | `object \| null` | Grouped GBP attributes (`Accessibility`, `Service options`, `Amenities`, `Payments`, `Planning`) |
| `thumbnailUrl` | `string \| null` | Primary high-resolution cover photo URL |
| `logoUrl` | `string \| null` | Merchant GBP avatar/logo URL |
| `photoUrls` | `string[]` | Up to 10 high-resolution place photo URLs (`800x600`) |
| `photosCount` | `number` | Number of extracted photo URLs |
| `googleMapsUrl` | `string \| null` | Direct link to the listing on Google Maps (`query_place_id`) |
| `googleMapsCidUrl` | `string \| null` | Direct CID link (`https://maps.google.com/?cid=...`) |
| `reviewsUrl` | `string \| null` | Google Local Reviews panel URL |
| `searchQuery` | `string \| null` | Originating search query |
| `rank` | `number \| null` | Search result position (`1`-indexed) |
| `scrapedAt` | `string` | ISO-8601 extraction timestamp |

***

### 💰 Transparent Pay-Per-Event Pricing

You only pay for unique, deduplicated places that pass all active filters (`minRating`, `minReviews`, `onlyWithWebsite`, `onlyWithPhone`):

| Event Name | Price | What Triggers It |
|---|---|---|
| **`place`** *(Primary)* | **$0.0015 / place** (`$1.50 / 1,000`) | Emitted once per unique deduplicated Google Maps business record (all 47 native Google Maps fields included). |
| **`contact-enrichment`** *(Optional Add-On)* | **$0.0010 / enriched place** (`$1.00 / 1,000`) | Only charged when `enrichContacts: true` **and** the business's external website was successfully fetched to extract emails & social links (total `$2.50 / 1,000` enriched leads). |
| **Diagnostic Status Rows** | **FREE (`$0.00`)** | `rowType: "status"` rows (`empty_input`, `invalid_url`, `no_results`, `filtered_empty`) are never billed. |

#### Cost Examples

- **500 local dentists across 5 Texas cities (`enrichContacts: false`):** `500 × $0.0015` = **$0.75 total**.
- **1,000 B2B roofing contractors with verified website emails & socials (`enrichContacts: true`):** `1,000 × ($0.0015 + $0.0010)` = **$2.50 total**.
- **Empty or filtered-out test query:** **$0.00**.

***

### 🛠️ Input Parameters Reference

| Parameter | Type | Default | Description |
|---|---|---|---|
| `searchQueries` | `string[]` | `["Dentist in Austin, TX"]` | Full queries (`"Roofing contractor in Miami, FL"`) or plain categories (`"Plumber"`) paired with `locations`. |
| `locations` | `string[]` | `[]` | Optional cities, states, or ZIP codes paired automatically with plain categories in `searchQueries`. |
| `googleMapsUrls` | `string[]` | `[]` | Direct `google.com/maps/search/...` or `google.com/maps/place/...` URLs. |
| `maxPlacesPerQuery` | `integer` | `20` | Max unique places extracted per query/URL (`1`–`500`). |
| `maxTotalPlaces` | `integer` | `100` | Global run cap across all queries (`1`–`50000`). |
| `enrichContacts` | `boolean` | `false` | Crawl each business's external website for `emails[]`, `phonesFromWeb[]`, and `socialProfiles`. |
| `minRating` | `number` | — | Minimum Google star rating (`0`–`5`, e.g., `4.2`). |
| `minReviews` | `integer` | — | Minimum review count (e.g., `15`). |
| `onlyWithWebsite` | `boolean` | `false` | Skip listings without an external website. |
| `onlyWithPhone` | `boolean` | `false` | Skip listings without a phone number. |
| `language` | `string` | `"en"` | ISO language code (`hl`, e.g., `"en"`, `"de"`, `"es"`, `"fr"`, `"tr"`). |
| `countryCode` | `string` | `"us"` | ISO country bias (`gl`, e.g., `"us"`, `"gb"`, `"de"`, `"ca"`, `"au"`). |
| `latitude` / `longitude` | `number` | — | Optional viewport center coordinates. |
| `zoomMeters` | `integer` | `25000` | Viewport altitude/radius in meters (`500`–`1000000`). |
| `proxyConfiguration` | `object` | `{"useApifyProxy": true}` | Standard Apify Proxy configuration. |

***

### 📥 Input Examples

#### 1. Multi-City B2B Lead Generation with Email & Social Enrichment

```json
{
  "searchQueries": ["Med Spa", "Cosmetic Dentist"],
  "locations": ["Austin, TX", "Scottsdale, AZ", "Miami, FL"],
  "maxPlacesPerQuery": 40,
  "maxTotalPlaces": 240,
  "enrichContacts": true,
  "onlyWithWebsite": true,
  "minRating": 4.0
}
```

#### 2. Unclaimed / Low-Rated GBP Prospecting for SEO & Reputation Agencies

```json
{
  "searchQueries": [
    "Plumber in Phoenix, AZ",
    "HVAC repair in Tampa, FL",
    "Roofing company in Charlotte, NC"
  ],
  "maxPlacesPerQuery": 60,
  "maxTotalPlaces": 180,
  "onlyWithPhone": true,
  "enrichContacts": true
}
```

#### 3. International Hyper-Local Coordinate Search (Europe)

```json
{
  "searchQueries": ["Zahnarzt", "Kieferorthopäde"],
  "latitude": 52.52,
  "longitude": 13.405,
  "zoomMeters": 12000,
  "language": "de",
  "countryCode": "de",
  "maxPlacesPerQuery": 50
}
```

***

### 📤 Sample Output Record

```json
{
  "rowType": "place",
  "rowKey": "gmaps:ChIJpXb4FgrJRIYRyRpdhSsCHHk",
  "placeId": "ChIJpXb4FgrJRIYRyRpdhSsCHHk",
  "cid": "13243667843430391418",
  "fid": "0x8644c90a16f876a5:0x791c022b855d1ac9",
  "googleBusinessId": "108487143740181764377",
  "kgmid": "/g/11synpwv5g",
  "name": "Emergency Dentist of Austin",
  "primaryCategory": "Dentist",
  "categories": [
    "Dentist",
    "Cosmetic dentist",
    "Dental clinic",
    "Emergency dental service",
    "Oral surgeon"
  ],
  "googleTypeId": "SearchResult.TYPE_DENTIST",
  "rating": 4.8,
  "reviewCount": 1598,
  "reviewsDistribution": {
    "oneStar": 64,
    "twoStar": 7,
    "threeStar": 8,
    "fourStar": 36,
    "fiveStar": 1483
  },
  "priceRange": null,
  "businessStatus": "OPERATIONAL",
  "isClaimed": true,
  "ownerTitle": "Emergency Dentist of Austin (Owner)",
  "phone": "(512) 961-6200",
  "phoneE164": "+15129616200",
  "websiteUrl": "https://emergencydentistofaustin.com/",
  "websiteDomain": "emergencydentistofaustin.com",
  "formattedAddress": "2716 S Lamar Blvd, Austin, TX 78704",
  "streetAddress": "2716 S Lamar Blvd",
  "neighborhood": "Zilker",
  "city": "Austin",
  "state": "Texas",
  "postalCode": "78704",
  "countryCode": "US",
  "latitude": 30.244128,
  "longitude": -97.781042,
  "timezone": "America/Chicago",
  "openingHours": [
    { "day": "Monday", "hours": "8 AM–9 PM" },
    { "day": "Tuesday", "hours": "8 AM–9 PM" },
    { "day": "Wednesday", "hours": "8 AM–9 PM" },
    { "day": "Thursday", "hours": "8 AM–9 PM" },
    { "day": "Friday", "hours": "8 AM–9 PM" },
    { "day": "Saturday", "hours": "9 AM–9 PM" },
    { "day": "Sunday", "hours": "9 AM–9 PM" }
  ],
  "isOpen24Hours": false,
  "highlights": ["LGBTQ+ friendly"],
  "attributes": {
    "Accessibility": ["Wheelchair accessible entrance", "Wheelchair accessible parking lot"],
    "Planning": ["Accepts new patients", "Appointments recommended"]
  },
  "emails": ["info@emergencydentistofaustin.com"],
  "phonesFromWeb": ["512-961-6200"],
  "socialProfiles": {
    "instagram": "https://www.instagram.com/emergencydentistofaustin/",
    "facebook": "https://www.facebook.com/emergencydentistofaustin",
    "linkedin": null,
    "twitter": null,
    "tiktok": null,
    "youtube": null
  },
  "contactPageUrl": "https://emergencydentistofaustin.com/contact/",
  "contactsEnriched": true,
  "googleMapsUrl": "https://www.google.com/maps/search/?api=1&query=Emergency%20Dentist%20of%20Austin&query_place_id=ChIJpXb4FgrJRIYRyRpdhSsCHHk",
  "googleMapsCidUrl": "https://maps.google.com/?cid=13243667843430391418",
  "searchQuery": "Dentist in Austin, TX",
  "rank": 1,
  "scrapedAt": "2026-11-15T00:38:40.000Z"
}
```

***

### 💻 Code Integration Examples

#### Python (`apify-client` v3+)

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")

run = client.actor("foxlabs/google-maps-scraper").call(run_input={"searchQueries": ["Dentist in Austin, TX"], "maxPlacesPerQuery": 20, "enrichContacts": True})

for item in client.dataset(run.default_dataset_id).iterate_items():
    if item.get("rowType") == "place":
        print(item["name"], item["phoneE164"], item["emails"], item["socialProfiles"]["instagram"])
```

#### Node.js / TypeScript (`apify-client`)

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });

const run = await client.actor('foxlabs/google-maps-scraper').call({"searchQueries":["Dentist in Austin, TX"],"maxPlacesPerQuery":20,"enrichContacts":true});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items.filter((r) => r.rowType === 'place'));
```

#### Real-Time HTTP Standby (`curl`)

```bash
curl -X POST "https://foxlabs--google-maps-scraper.apify.actor/scrape?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"searchQueries":["Specialty coffee in Seattle, WA"],"maxPlacesPerQuery":10,"enrichContacts":true}'
```

***

### 🎯 High-ROI Use Cases

- **Outbound B2B Sales & Cold Email Pipelines:** Combine `phoneE164`, verified website `emails[]`, and `socialProfiles` (`linkedin`, `instagram`, `facebook`) to feed Clay, Instantly, Smartlead, HubSpot, or Salesforce without paying separate enrichment vendors.
- **Digital Marketing & Local SEO Agency Prospecting:** Filter businesses where `isClaimed === false`, `websiteUrl === null`, or `rating < 4.0` with high `oneStar` counts in `reviewsDistribution` to pitch GBP management, web design, or reputation repair.
- **Franchise, Retail & Healthcare Site Selection:** Map competitor density, operating hours (`openingHours`), accessibility `attributes`, and review velocity across ZIP codes (`locations`) or coordinate grids (`latitude` / `longitude` / `zoomMeters`).
- **Directory & AI Agent Grounding (MCP / RAG):** Give AI assistants live local business intelligence via Standby HTTP in ~2–4 seconds per query.

***

### ⚡ Performance, Memory & Deduplication

- **Lightweight `256 MB` Footprint:** Pure HTTP RPC streaming (`undici`) with zero browser overhead — runs cleanly in `256 MB` RAM and processes 20 places per page in ~1.5 seconds.
- **Cross-Query & Resume Deduplication:** Every place is keyed by `gmaps:<placeId>`. Overlapping multi-ZIP or multi-category searches in the same run (or across resurrected runs) never emit or bill duplicate businesses (`duplicateSkipped` tracked in `SOURCE_REPORT`).
- **Run Telemetry (`SOURCE_REPORT`):** Every run writes structured request, retry, filter, and event counters to the default Key-Value Store under `SOURCE_REPORT`.

***

### 🔗 Composable foXLabs Lead-Gen Stack

Pair `foxlabs/google-maps-scraper` with other specialized actors in our catalog:

- **`foxlabs/yelp-business-scraper`** — Cross-match local US businesses with Yelp health inspection scores, `yearEstablished`, and Yelp owner bios.
- **`foxlabs/trustpilot-reviews-scraper`** — Pull full customer review histories and sentiment trends for discovered `websiteDomain` targets.
- **`foxlabs/thomasnet-suppliers-scraper`** — Expand from local commercial businesses into ISO/ITAR/AS9100-certified North American industrial manufacturers.

***

### ❓ Frequently Asked Questions

#### Does Google Maps Business Leads Scraper require a Google Places API key?

No. You do not need a Google Cloud billing account, Places API key, cookies, or third-party proxy credentials. Everything runs turnkey on Apify out of the box.

#### How does website email and social media enrichment (`enrichContacts`) work?

When `enrichContacts: true` is enabled, the actor visits each place's external `websiteUrl` (homepage plus automatically detected `/contact`, `/about`, or `/impressum` page) with strict 9-second timeouts. It extracts `mailto:` and text emails, de-obfuscates `[at]`/`&#64;` encodings, strips false-positive domains (`sentry.io`, `wixpress.com`, image filenames), and captures Instagram, Facebook, LinkedIn, X/Twitter, TikTok, and YouTube profile links.

#### Am I charged `contact-enrichment` if a business has no website?

No. If a Google Maps listing has no `websiteUrl` (or its website is offline/unreachable), `contactsEnriched` remains `false` and **only** the base `place` event (`$0.0015`) is charged. If you set `onlyWithWebsite: true`, places without websites are skipped completely at `$0.00`.

#### How do I scrape more than 120–200 businesses in a dense metropolitan area?

Google Maps caps any single query viewport at roughly 120–200 ranked places. To capture thousands of businesses across a major metro (such as Los Angeles, London, or New York), pass neighborhood or ZIP-code granularity inside `locations` — for example `searchQueries: ["Dentist"]` with `locations: ["78701", "78702", "78704", "78745", "78758"]`. Built-in `placeId` deduplication guarantees zero duplicate charges across overlapping ZIP codes.

#### What is the difference between `placeId`, `cid`, and `fid`?

`placeId` (`ChIJ...`) is Google's standard string identifier used in Maps URLs and Places APIs. `cid` is the 64-bit unsigned integer Customer ID (`https://maps.google.com/?cid=...`) widely used by local SEO rank trackers and citation builders. `fid` (`0x...:0x...`) is the underlying hexadecimal map feature pair. This actor extracts all three simultaneously.

#### How can agencies find unclaimed Google Business Profiles?

Check the boolean `isClaimed` column in the output dataset. When `isClaimed` is `false`, the listing shows no verified GBP owner attribution (`ownerTitle: null`), making it a high-converting lead for local SEO and GBP setup agencies.

#### Are places filtered out by `minRating` or `minReviews` billed?

Never. Qualification filters (`minRating`, `minReviews`, `onlyWithWebsite`, `onlyWithPhone`) execute before `Actor.pushData`. Excluded listings increment `filteredOut` in `SOURCE_REPORT` at `$0.00` event cost.

#### How are missing ratings or review counts represented in the JSON output?

Strict null-safety is enforced across all 53 fields: if a newly opened business has no reviews yet, `rating` and `reviewCount` are `null` (never `0`), preventing downstream averages or CRM scoring formulas from being corrupted.

#### Can I scrape non-English countries and local scripts?

Yes. Set `language` (e.g., `"de"`, `"ja"`, `"ar"`, `"tr"`, `"es"`, `"pt"`) and `countryCode` (e.g., `"de"`, `"jp"`, `"ae"`, `"tr"`, `"mx"`, `"br"`). Category names, address formatting, and opening-hour labels adapt automatically.

#### Does this actor support Apify Standby HTTP mode for AI agents?

Yes. When invoked via Apify Standby, the container exposes `GET /` (health probe) and `POST /scrape` (synchronous JSON extraction) documented by `.actor/openapi.json`, making it plug-and-play for MCP servers, n8n HTTP nodes, Make, and LangGraph tool calls.

#### What happens if my query matches zero businesses or I pass an invalid URL?

Following Policy C error handling, user-input edge cases (`empty_input`, `invalid_url`, `no_results`, `filtered_empty`) finish cleanly with `SUCCEEDED` and emit a free explanatory `rowType: "status"` row (`$0.00`). Only genuine upstream network failures across all targets mark the run `FAILED`.

#### How fast is extraction and how much RAM should I allocate?

Keep the default **256 MB** memory setting. Typical runs extract 20 places in 2–4 seconds (`enrichContacts: false`) or 6–12 seconds (`enrichContacts: true` with 5x parallel website crawling), minimizing platform compute usage.

***

### 📋 Changelog

#### `0.1.0` (2026-11-15)

- Initial release of `foxlabs/google-maps-scraper` with 53 structured columns (`placeId`, `cid`, `fid`, `kgmid`, `reviewsDistribution`, `isClaimed`, `phoneE164`, 7-day `openingHours`, `attributes`, `highlights`), optional external website email & social enrichment (`enrichContacts`), qualification filters, and dual Batch + Standby HTTP support.

# Changelog

This Actor's version history is a separate document: https://apify.com/foxlabs/google-maps-scraper/changelog.md

# Actor input Schema

## `searchQueries` (type: `array`):

Full Google Maps search queries (e.g., 'dentist in Austin, TX', 'specialty coffee shop in Berlin', 'HVAC contractor 78701') or plain business categories combined with the Locations list.

## `locations` (type: `array`):

Optional list of cities, states, countries, or postal codes (e.g., \['Austin, TX', 'Dallas, TX']). When provided, any query in Search Queries that does not already contain ' in ' or a comma is paired with each location.

## `googleMapsUrls` (type: `array`):

Direct Google Maps search URLs (https://www.google.com/maps/search/...) or place URLs (https://www.google.com/maps/place/...).

## `maxPlacesPerQuery` (type: `integer`):

Maximum number of unique deduplicated Google Maps places to extract per search query or URL (up to 200 per query).

## `maxTotalPlaces` (type: `integer`):

Hard ceiling on total paid place records emitted across the entire run.

## `enrichContacts` (type: `boolean`):

When enabled, crawls each business's official external website (homepage + contact/about page) to extract verified business emails and social media profiles (Instagram, Facebook, LinkedIn, X/Twitter, TikTok, YouTube). Adds one 'contact-enrichment' event per website-enriched place.

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

Optional minimum Google Maps star rating (e.g., 4.0 or 4.5). Places below this rating are skipped without charge.

## `minReviews` (type: `integer`):

Optional minimum number of Google reviews (e.g., 10 or 50). Places with fewer reviews are skipped without charge.

## `onlyWithWebsite` (type: `boolean`):

When true, skips places that have no external website listed on Google Maps.

## `onlyWithPhone` (type: `boolean`):

When true, skips places that have no phone number listed on Google Maps.

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

Two-letter ISO language code for Google Maps labels, categories, and opening hours (e.g., 'en', 'de', 'es', 'fr', 'tr').

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

Two-letter ISO country code for Google Maps region bias (e.g., 'us', 'gb', 'de', 'ca', 'au', 'tr').

## `latitude` (type: `number`):

Optional center latitude (-90 to 90) when targeting a specific coordinate viewport.

## `longitude` (type: `number`):

Optional center longitude (-180 to 180) when targeting a specific coordinate viewport.

## `zoomMeters` (type: `integer`):

Viewport altitude parameter in meters for coordinate-centered searches (smaller = tighter neighborhood zoom; default 25000 covers a metro area).

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

Apify Proxy configuration. Works out of the box with standard Apify Proxy.

## Actor input object example

```json
{
  "searchQueries": [
    "Dentist in Austin, TX"
  ],
  "maxPlacesPerQuery": 20,
  "maxTotalPlaces": 100,
  "enrichContacts": false,
  "onlyWithWebsite": false,
  "onlyWithPhone": false,
  "language": "en",
  "countryCode": "us",
  "zoomMeters": 25000,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

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

No description

## `sourceReport` (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 = {
    "searchQueries": [
        "Dentist in Austin, TX"
    ],
    "maxPlacesPerQuery": 20,
    "maxTotalPlaces": 100
};

// Run the Actor and wait for it to finish
const run = await client.actor("foxlabs/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 = {
    "searchQueries": ["Dentist in Austin, TX"],
    "maxPlacesPerQuery": 20,
    "maxTotalPlaces": 100,
}

# Run the Actor and wait for it to finish
run = client.actor("foxlabs/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 '{
  "searchQueries": [
    "Dentist in Austin, TX"
  ],
  "maxPlacesPerQuery": 20,
  "maxTotalPlaces": 100
}' |
apify call foxlabs/google-maps-scraper --silent --output-dataset

```

## MCP server setup

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