📩📍 Google Maps Email Extractor

A production-oriented Apify Actor designed to discover places on Google Maps, open each place page, and automatically extract contact details from the business's public website. It is highly optimized, reliable, and provides structured data including email addresses, phone numbers, and social media links.

🌟 Key Features

• Comprehensive Extraction: Gathers place name, Google Maps URL, category, rating, review count, full address, exact coordinates, phone number, website link, main image, and operational status.
• Deep Contact Enrichment: Follows the business website to discover public email addresses and telephone numbers.
• Social Media Links: Automatically finds links to LinkedIn, Facebook, Instagram, YouTube, TikTok, X (Twitter), Pinterest, and Discord.
• Team & Lead Information: Performs best-effort extraction of public Person/team information using JSON-LD and contact pages.
• Social Profile Metadata: Collects follower counts and other social profile metadata if publicly available in the fetched HTML.
• Smart Filtering: Supports filtering by category, rating, open status, and more.
• Visual Results: Generates an interactive Leaflet/OpenStreetMap visualization of all extracted places.

🚀 How It Works

The Actor accepts search strings, location queries, or direct Google Maps URLs. It searches for places, extracts their basic information from Google Maps, and then visits the associated websites to scrape public contact and social media information.

The Actor uses smart deduplication, request timeouts, retries, and limited website traversal to ensure speed and reliability without overloading target servers.

📝 Input Options

The input UI is designed to be intuitive and powerful. You can provide inputs in three primary ways:

1. searchStringsArray + locationQuery (e.g., "dentist" in "London, UK")
2. searchStringsArray + custom structured geolocation (Polygon/Grid)
3. startUrls directly pointing to Google Maps search or place URLs (Highest priority).

Minimal Example Input

{
  "searchStringsArray": ["dentist"],
  "locationQuery": "Kadıköy, Istanbul, Turkey",
  "maxCrawledPlacesPerSearch": 20,
  "language": "tr",
  "website": "withWebsite",
  "skipClosedPlaces": true
}

📊 Outputs

Upon successful completion, the Actor provides:

• Default Dataset: A rich JSON/CSV dataset containing one detailed object per accepted place.
• Run Summary: A summary record in the Key-Value Store detailing counters and processing metrics.
• Interactive Map: A results-map record (HTML) in the Key-Value Store for a visual overview.

💰 Pay-Per-Event (Monetization)

This Actor supports Apify's Pay-Per-Event (PPE) pricing model. When running under PPE, it emits billable events incrementally and stops gracefully once the user's defined maximum charge is reached. If run as a free or unmonetized Actor during development, it extracts the same results without attempting to log billable events. Please refer to MONETIZATION.md for a full breakdown of billable events.

⚙️ Operational Environment Variables

Variable	Default	Purpose
MAX_CONCURRENCY	4	Maximum concurrent Google Maps pages processed.
MAX_WEBSITE_PAGES	5	Maximum number of sub-pages fetched from each business site.
HARD_MAX_CANDIDATES_PER_SEARCH	1000	Safety cap when the result limit is empty.
CRAWLEE_BROWSER_EXECUTABLE_PATH	image default	Local Chromium/Brave executable path for debugging.

🛡️ Reliability and Responsible Use

• Respectful Crawling: The crawler implements retries, strict per-search caps, deduplication, request timeouts, and limits website traversal depths. It does NOT bypass CAPTCHAs or unauthorized access controls.
• Data Privacy: Ensure you only collect public business contact data for legitimate purposes and follow applicable privacy laws, marketing guidelines, and platform terms.
• Validation: Email validation checks the domain's mail capability (DNS/MX records), not the exact existence of a particular mailbox. Lead and social enrichment is strictly best-effort based on publicly available HTML.

💻 Local Development

Requirements: Node.js 22+ and a Chromium-family browser for live smoke tests.

npm ci
npm test
npm run lint

For a live Google Maps smoke test (Windows example):

$env:CRAWLEE_BROWSER_EXECUTABLE_PATH='C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe'
npm run test:smoke

To run the complete Actor locally, create storage/key_value_stores/default/INPUT.json and run npm start.

📄 License

MIT. See LICENSE.