google-map-scrapping

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #cli #claude-code #codex #developer-tools #react #windows

google-map-scrapping

★ 84 Open GitHub ↗

A robust, session-based Chrome Extension built to autonomously extract business information from Google Maps search results. Engineered with a modern React stack, this tool automates the process of scrolling, clicking, and extracting structured data points directly from the Google Maps DOM into a manageable, exportable format.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 🗺️ Google Maps Data Scraper

A robust, session-based Chrome Extension built to autonomously extract business information from Google Maps search results. Engineered with a modern React stack, this tool automates the process of scrolling, clicking, and extracting structured data points directly from the Google Maps DOM into a manageable, exportable format.

## ✨ Key Features

*   **Automated Extraction:** Automatically scrolls through the Google Maps feed and clicks each result to parse deep information from the active detail pane.
*   **Real-time Progress Tracking:** A dedicated Chrome Side Panel provides live updates (e.g., `245 / 500 items found`) so you always know the scraper's status.
*   **Session Management:** Data is grouped by individual scraping sessions (e.g., `Session: Coffee Shops Bali (4/19/2026)`), making it easy to track, delete, or manage historical data.
*   **Advanced Dashboard:** A full-page Options Dashboard built with Shadcn UI to view all scraped data.
    *   **Search:** Instantly filter businesses by name or address.
    *   **Sort:** Order results by Highest/Lowest Rating or Most Reviews.
    *   **Filter:** One-click toggles to hide records missing a Website or Phone Number (high-quality lead filtering).
*   **One-Click CSV Export:** Download your cleaned, structured data into a standard `.csv` file for use in Excel, Google Sheets, or CRM software.

## 📦 Data Extracted

For every successfully parsed business, the extension captures:
*   **Title** (Business Name)
*   **Rating Score** (e.g., 4.5)
*   **Review Count** (e.g., 1,200)
*   **Address**
*   **Phone Number**
*   **Website URL**
*   **Coordinates** (Parsed from the active map URL)

---

## 🛠️ Technology Stack

This extension is built on top of the **Plasmo Framework**, utilizing a modern web development stack:
*   **Framework:** [Plasmo](https://docs.plasmo.com/) (React-based Chrome Extension Framework)
*   **UI Library:** React 19
*   **Styling:** Tailwind CSS
*   **Components:** [Shadcn UI](https://ui.shadcn.com/) (Radix Primitives)
*   **Icons:** Lucide React
*   **Storage:** `chrome.storage.local`

---

## 📦 Quick Installation (Pre-built)

If you don't want to build the extension from source, you can use the pre-built version:

1.  **Download the Extension**: Go to the **Releases** section of this repository and download the latest `google-maps-scraper-vX.X.X.zip`.
2.  **Extract the Files**: Unzip the downloaded file into a dedicated folder on your computer.
3.  **Load into Chrome**:
    *   Open Google Chrome and navigate to `chrome://extensions/`.
    *   Enable **Developer mode** (toggle switch in the top right corner).
    *   Click **Load unpacked** in the top left corner.
    *   Select the folder where you extracted the ZIP file.

---

## 🚀 Getting Started (Development)

### Prerequisites
*   Node.js (v18+)
*   npm, yarn, or pnpm

### Installation

1.  **Clone the repository:**
    ```bash
    git clone <repository-url>
    cd google-maps-scrapping
    ```

2.  **Install dependencies:**
    ```bash
    npm install
    ```

3.  **Start the development server:**
    ```bash
    npm run dev
    ```
    *This will spin up a local Plasmo dev server and generate a `build/chrome-mv3-dev` directory.*

### Loading into Chrome

1. Open Google Chrome and navigate to `chrome://extensions/`.
2. Enable **Developer mode** (toggle switch in the top right corner).
3. Click **Load unpacked** in the top left corner.
4. Select the `build/chrome-mv3-dev` directory generated by the `npm run dev` command.

---

## 📖 How to Use

1.  **Open Google Maps** (`https://www.google.com/maps`).
2.  **Open the Side Panel**: Click the Chrome Side Panel icon (usually next to your profile picture in the toolbar) and select the **Google Maps Scraper** extension from the dropdown.
3.  **Configure**: Enter a **Business Context** (e.g., "Plumbers") and a **Location** (e.g., "Seattle"), then set your desired extraction limit.
4.  **Start**: Click "Start Scraping". The extension will automatically inject the search query, press Enter, and begin iterating through the results feed on the left side of the screen.
5.  **Stop/Reset**: You can halt the process at any time by clicking "STOP & RESET" in the Side Panel. All data extracted up to that point is safely stored.
6.  **Manage Data**: Click "View Results Database" to open the Options page. Here you can filter your leads, view star ratings, and export the session to CSV.

---

## 📁 Project Structure

*   `src/sidepanel.tsx`: The UI for configuring and monitoring active scraping tasks.
*   `src/options.tsx`: The comprehensive data dashboard for viewing, filtering, and exporting.
*   `src/contents/scraper.ts`: The core injected script containing the XPath evaluation logic, DOM traversal loop, and human-like delay timing.
*   `src/background.ts`: The service worker managing the state and communication between the Side Panel and Content Script.
*   `src/components/ui/`: Reusable, accessible components generated via Shadcn UI.

---

## ⚠️ Disclaimer

This tool is designed for educational and personal data management purposes. Web scraping can be a violation of the Terms of Service of the targeted website. Please ensure you are compliant with Google's Terms of Service and local data privacy laws (such as GDPR or CCPA) before using this tool in a production or commercial environment. The developers assume no liability for misuse.

google-map-scrapping

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README