Metadata-Version: 2.4
Name: advanced-keyword-scraper
Version: 0.4.0
Summary: Lightning-fast async keyword scraper with Trend Status, N-Gram analysis, and SEO scoring.
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

# 🚀 Advanced Keyword Scraper

A lightning-fast, `asyncio`-powered CLI tool designed for SEO professionals, digital marketers, and e-commerce sellers. It extracts thousands of long-tail search suggestions from multiple search engines in seconds, analyzes their SEO potential, identifies keyword trends, and groups them into intelligent topic clusters.

**Developed with 🔥 by LORD SRIJWN**

---

## ✨ Key Features
* **⚡ Ultra-Fast Async Engine:** Powered by `asyncio` and `aiohttp` to fetch thousands of keywords in mere seconds without lag.
* **🌍 Multi-Platform Support:** Scrape keywords from **Google, YouTube, Amazon, and Bing**.
* **📊 SEO Opportunity Score:** Automatically grades each keyword (1-100) based on length, search intent, and ranking difficulty.
* **📈 Keyword Trend Status:** Identifies if a keyword is a *🔥 Breakout Trend*, *📈 Rising*, *💡 Emerging*, or *➖ Stable*.
* **🧠 Topic Clustering:** Automatically groups thousands of keywords into relevant topic clusters (e.g., "Cotton", "Silk", "Party") and saves them in separate Excel sheets.
* **📝 N-Gram Analysis:** Generates frequency counts for Unigrams (Top Words), Bigrams, and Trigrams to help optimize titles and backend search terms.
* **🌐 Regional Language Support:** Perform local SEO by extracting keywords in Bengali (`bn`), Hindi (`hi`), or any other language.
* **🕵️‍♂️ Recursive Deep Search (Level 2):** Digs deep into initial results to find hidden, ultra-low competition long-tail keywords.
* **🗃️ Multi-Format Export:** Save your reports in beautiful `Excel (.xlsx)`, `CSV`, `JSON`, or even `SQLite (.db)` databases for massive datasets.

---

## ⚙️ Installation

Install or upgrade the package globally using pip:

    pip install --upgrade advanced-keyword-scraper

*(Note: Requires Python 3.8 or higher)*

---

## 📖 User Manual & Usage Guide

Once installed, you can run the tool from anywhere in your terminal using the `keyword-scraper` command.

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

### Command Line Arguments (Options)

| Argument | Default | Description |
| :--- | :--- | :--- |
| `keywords` | **Required** | One or more base keywords (use quotes for multiple words). |
| `--engine` | `google` | Target platform. Choices: `google`, `youtube`, `bing`, `amazon`. |
| `--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 search, `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 (Default: 20). |
| `--output` | `SEO_Keywords` | Directory name where the reports will be saved. |

---

## 💡 Practical Examples

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

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

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

### 4. Massive Google Topic Clustering
Perform a massive search and 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 you choose the `excel` format, you get an incredibly detailed, ready-to-use file:
1. **All Keywords:** The master dataset containing the Keyword, Search Intent, SEO Opportunity Score, and Trend Status.
2. **Top Words (Unigram):** Frequency of single words used across all queries.
3. **Top Bigrams:** 2-word combinations for long-tail title optimization.
4. **Top Trigrams:** 3-word combinations for backend search terms.
5. **Topic Clusters (Multiple Sheets):** Keywords automatically grouped by their core topic (e.g., a dedicated sheet just for "Strategy" or "Syllabus").

---

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

*Crafted by LORD SRIJWN*
