EhsanShahbazii/Neshan-Maps-Scraper

📍 A powerful, colourful, and stealthy scraper for Neshan Maps
Search for businesses, extract detailed info, and export to CSV, JSON, SQLite & more.

███╗   ██╗███████╗███████╗██╗  ██╗ █████╗ ███╗   ██╗

████╗  ██║██╔════╝██╔════╝██║  ██║██╔══██╗████╗  ██║

██╔██╗ ██║█████╗  ███████╗███████║███████║██╔██╗ ██║

██║╚██╗██║██╔══╝  ╚════██║██╔══██║██╔══██║██║╚██╗██║

██║ ╚████║███████╗███████║██║  ██║██║  ██║██║ ╚████║

╚═╝  ╚═══╝╚══════╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═══╝



## ✨ Features

- 🔍 **Search any query** on [Neshan Maps](https://neshan.org/maps) (restaurants, shops, services...)
- 📋 **Extract rich data**: name, category, address, phone, website, opening hours, rating, reviews
- 🎨 **Beautiful coloured console output** with progress bars
- 🥷 **Anti-detection** measures: random user-agents, configurable delays, stealthy scrolling
- 📁 **Multiple export formats** – CSV, JSON, Parquet, SQLite
- ⚙️ **Fully configurable** via CLI arguments



## 🚀 Installation

# Clone the repository

git clone https://github.com/your-username/neshan-scraper.git

cd neshan-scraper



# Install Python dependencies

pip install -r requirements.txt



# Install Playwright browsers (Chromium)

playwright install chromium





## 🖥️ Usage

Run the scraper with a simple command:

python neshan_scraper.py -s "فست فود تهران" -t 20 -f csv

This will search for "fast food in Tehran", scrape **20** listings, and save them to a timestamped CSV file.

### ⚡ All Options

| Argument | Short | Description | Default |

|----------|-------|-------------|---------|

| `--search` | `-s` | Search query (UTF-8 supported) | `فست فود تهران` |

| `--total` | `-t` | Number of places to scrape | `5` |

| `--output` | `-o` | Base name for the export file | `neshan_export` |

| `--format` | `-f` | Output format: `csv`, `json`, `parquet`, `sqlite` | `csv` |

| `--headless` | | Run browser in background (no GUI) | `False` |

| `--delay` | | Delay profile: `low`, `medium`, `high` | `medium` |

| `--log` | | Logging level: `DEBUG`, `INFO`, `WARNING`, `ERROR` | `INFO` |



## 📸 Terminal Preview

This is how the scraper looks in action:

(venv) ➜  neshan-scraper python neshan.py -s "cafe tehran" -t 10 -f csv --delay medium



  ███╗   ██╗███████╗███████╗██╗  ██╗ █████╗ ███╗   ██╗

  ████╗  ██║██╔════╝██╔════╝██║  ██║██╔══██╗████╗  ██║

  ██╔██╗ ██║█████╗  ███████╗███████║███████║██╔██╗ ██║

  ██║╚██╗██║██╔══╝  ╚════██║██╔══██║██╔══██║██║╚██╗██║

  ██║ ╚████║███████╗███████║██║  ██║██║  ██║██║ ╚████║

  ╚═╝  ╚═══╝╚══════╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═══╝



======================================================



14:08:21 - INFO - Starting Scraper... Options: Format=csv, Headless=False, Delay=medium

14:08:22 - INFO - Navigating to Neshan to search: cafe tehran

14:08:24 - INFO - Scrolling to find 10 listings...

Scraping: 100%|██████████████████████████████| 10/10 [00:26<00:00]

14:08:50 - INFO - Data successfully saved to neshan_export_20260527_140850.csv

## 📦 Example Output (CSV)

| name | category | address | phone_number | website | opening_hours_today | rating | reviews_count |

|------|----------|---------|--------------|---------|---------------------|--------|---------------|

| برگرلند | فست فود | تهران، خیابان ولیعصر... | ۰۲۱-۸۸۸۸۸۸۸۸ | https://... | ۱۱:۰۰ - ۲۳:۰۰ | 4.5 | (124) |



## ⚠️ Disclaimer

This tool is intended for **educational purposes** and **personal research** only.  

Please respect the website’s `robots.txt` and terms of service. Do not overload the server with aggressive scraping.



## 📄 License

MIT ©EhsanShahbazi





  Made with ❤️ and lots of ☕