Metadata-Version: 2.4
Name: advanced-keyword-scraper
Version: 0.5.1
Summary: Ultimate Async SEO Scraper with SERP Extraction, FAQ Scraper, N-Gram analysis, and Topic Clustering.
Author-email: LORD SRIJWN <dassrijan60@gmail.com>
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: rich>=13.0.0
Requires-Dist: fake-useragent>=1.1.0
Requires-Dist: beautifulsoup4>=4.12.0

# 🚀 Advanced Keyword & SERP Scraper v0.5.0

A lightning-fast, `asyncio`-powered dual-mode CLI tool designed for SEO professionals, digital marketers, and e-commerce sellers. 

Not only can it extract thousands of long-tail search suggestions, analyze SEO potential, and group them into topic clusters—but it now features a **SERP & FAQ Extractor** to scrape organic Google search results and "People Also Ask" questions.

**Developed with 🔥 by LORD SRIJWN**

---

## ✨ Key Features

### 🔍 Mode 1: Keyword Research (`--mode keyword`)
* **⚡ Ultra-Fast Async Engine:** Fetches thousands of keywords in mere seconds without lag.
* **🌍 Multi-Platform Support:** Scrape keywords from **Google, YouTube, Amazon, and Bing**.
* **📊 SEO Opportunity Score:** Grades each keyword (1-100) based on length, intent, and ranking difficulty.
* **📈 Keyword Trend Status:** Identifies if a keyword is a *🔥 Breakout Trend*, *📈 Rising*, *💡 Emerging*, or *➖ Stable*.
* **🧠 Topic Clustering:** Automatically groups keywords into relevant topic clusters (e.g., "Cotton", "Silk").
* **📝 N-Gram Analysis:** Generates frequency counts for Unigrams, Bigrams, and Trigrams.
* **🕵️‍♂️ Recursive Deep Search (Level 2):** Digs deep to find hidden, ultra-low competition long-tail keywords.

### 🌐 Mode 2: SERP & FAQ Extractor (`--mode serp`)
* **🏆 Top Ranking Sites Extraction:** Scrape the exact Title, URL, and Description of the top 10, 20, or 50 organic Google results.
* **💡 People Also Ask (FAQ) Scraper:** Automatically extracts user questions from Google's PAA section to help you build highly optimized FAQ schemas.

---

## ⚙️ Installation

Install or upgrade the package globally using pip:

    pip install --upgrade advanced-keyword-scraper

*(Note: Requires Python 3.8 or higher. Uses `beautifulsoup4`, `aiohttp`, and `pandas`)*

---

## 📖 User Manual & Usage Guide

Run the tool from anywhere in your terminal using the `keyword-scraper` command.

### Basic Syntax
    keyword-scraper [KEYWORDS] [OPTIONS]

### Command Line Arguments

| Argument | Default | Description |
| :--- | :--- | :--- |
| `keywords` | **Required** | One or more base keywords (use quotes for multiple words). |
| `--mode` | `keyword` | **NEW:** Choose `keyword` (for suggestions) or `serp` (for Google results & FAQs). |
| `--engine` | `google` | Target platform (`google`, `youtube`, `bing`, `amazon`). *Note: SERP mode is Google-only.* |
| `--results`| `10` | **NEW:** Number of top organic results to scrape (only applies to `--mode serp`). |
| `--country`| `in` | 2-letter country code (e.g., `in` for India, `us` for USA). |
| `--lang` | `en` | Language code (e.g., `en`, `bn`, `hi`). |
| `--depth` | `1` | Search depth (`1` = Normal, `2` = Deep recursive search). |
| `--exclude`| `None` | Comma-separated list of words to ignore (e.g., `free,crack`). |
| `--format` | `excel` | Output format. Choices: `excel`, `sqlite`, `all`. |
| `--threads`| `20` | Max concurrent async connections. Higher = faster. |

---

## 💡 Practical Examples

### 1. 🌟 NEW: Scrape Google SERP & Extract FAQs
Find out exactly who is ranking for a keyword and what FAQs Google shows:
    keyword-scraper "ssc cgl syllabus" --mode serp --results 20

### 2. Deep YouTube Search with SQLite Export
Extract thousands of hidden YouTube keywords, ignore outdated years, and save to a database:
    keyword-scraper "ssc cgl strategy" "maths tricks" --engine youtube --depth 2 --exclude "2023,2024" --format sqlite

### 3. Regional Local SEO (Bengali)
Find out what local customers are searching for in their native language:
    keyword-scraper "annapurna bhandar" "অন্নপূর্ণা ভান্ডার" --engine google --lang bn

### 4. E-commerce Keyword Research (Amazon)
Find high-intent buying keywords for product listings:
    keyword-scraper "cotton kurti" "party wear saree" --engine amazon --format excel

### 5. Massive Topic Clustering
Let the tool automatically cluster keywords by topics and generate N-Grams:
    keyword-scraper "digital marketing" "seo course" --engine google --depth 2 --threads 30

---

## 📁 Output Structure

The tool creates a folder named `SEO_Keywords` in your current directory. 

**If running in `--mode keyword` (Excel format):**
1. **All Keywords:** Master dataset (Intent, SEO Score, Trend Status).
2. **Top Words / Bigrams / Trigrams:** N-Gram frequency analysis.
3. **Topic Clusters:** Keywords grouped automatically by category into multiple sheets.

**If running in `--mode serp` (Excel format):**
1. **SERP & FAQ Data:** The complete list of Organic Results and FAQs mixed by rank.
2. **Extracted FAQs:** A dedicated sheet containing ONLY the "People Also Ask" questions for easy copying.

---

## 🤝 Contributing
Found a bug or want to add a new engine? Feel free to fork the repository, make your changes, and submit a pull request!

## 📜 License
This project is licensed under the MIT License.

*Crafted by LORD SRIJWN*
