# 🎯 YouTube Keyword Optimizer

A Node.js package that takes your **video title** and returns the most **optimized, ranked, and grouped keywords** using real-time data from:

- 📡 **YouTube Data API v3** — Extracts keywords from top-ranked videos, titles, descriptions, and tags
- 📈 **Google Trends** — Scores each keyword by real-time trend popularity (0–100)

---

## ✨ Features

| Feature | Description |
|---|---|
| 🔍 YouTube-powered | Pulls keyword signals from top 50 real YouTube results |
| 📈 Real-time trends | Scores each keyword with Google Trends data (last 90 days) |
| 🏆 Smart ranking | Composite score: 40% relevance + 60% trend popularity |
| 📂 Auto-grouping | Groups keywords into: Tutorial, Comparison, Tips, Beginner, Advanced, Tools, Trending |
| ⚡ Competition level | Flags each keyword as Low / Medium / High competition |
| 🖥️ CLI included | Run directly from terminal with beautiful table output |

---

## 🚀 Installation

```bash
npm install youtube-keyword-optimizer
```

Or clone and use locally:

```bash
git clone <repo>
cd youtube-keyword-optimizer
npm install
cp .env.example .env
# Add your YOUTUBE_API_KEY to .env
```

---

## 🔑 Setup: Get YouTube API Key

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a project → Enable **YouTube Data API v3**
3. Go to **Credentials** → Create **API Key**
4. Add to `.env`:

```env
YOUTUBE_API_KEY=AIzaSy...your_key_here
```

---

## 📦 Usage (as a package)

```javascript
const { optimizeKeywords } = require('youtube-keyword-optimizer');

const result = await optimizeKeywords(
  "How to Learn Python for Beginners 2024",  // Your video title
  process.env.YOUTUBE_API_KEY,
  {
    maxKeywords: 30,     // How many keywords to return
    includeTrends: true, // Fetch Google Trends scores
    grouped: true,       // Group into categories
  }
);

// Top keywords
console.log(result.keywords);
// [
//   { keyword: "python for beginners", score: 87, trendScore: 91, competition: "High" },
//   { keyword: "learn python", score: 82, trendScore: 85, competition: "High" },
//   ...
// ]

// Grouped keywords
console.log(result.groups);
// {
//   "🎯 Primary Keywords": [...],
//   "📚 Tutorial & How-To": [...],
//   "🚀 Beginner & Getting Started": [...],
//   ...
// }

// Meta info
console.log(result.meta);
// { title, totalKeywords, topKeyword, avgScore, generatedAt }
```

---

## 🖥️ CLI Usage

```bash
# Set your API key
export YOUTUBE_API_KEY=your_key_here

# Run for any video title
node cli.js "How to Make Money on YouTube in 2024"
```

**Output:**

```
🔍 Analyzing: "How to Make Money on YouTube in 2024"
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🎯 Primary Keywords
┌──────┬───────────────────────────────────┬───────┬───────┬──────────────┐
│ Rank │ Keyword                           │ Score │ Trend │ Competition  │
├──────┼───────────────────────────────────┼───────┼───────┼──────────────┤
│  #1  │ make money youtube                │  89   │  92   │ High         │
│  #2  │ youtube monetization              │  84   │  88   │ High         │
│  #3  │ youtube channel growth            │  76   │  79   │ Medium       │
└──────┴───────────────────────────────────┴───────┴───────┴──────────────┘

📈 Trending
   youtube shorts monetization, youtube ad revenue...

📚 Tutorial & How-To
   how to monetize, youtube tutorial, grow channel...
```

---

## 📊 Output Format

### `result.keywords[]`

| Field | Type | Description |
|---|---|---|
| `keyword` | string | The keyword phrase |
| `score` | number | Composite score 0–100 |
| `trendScore` | number \| null | Google Trends score (0–100), null if unavailable |
| `frequencyScore` | number | How often it appeared in YouTube results |
| `competition` | string | `"Low"` / `"Medium"` / `"High"` |

### `result.groups`

Keywords organized into categories:
- 🎯 Primary Keywords (top 10)
- 📚 Tutorial & How-To
- 🔍 Comparison & Review
- 💡 Tips & Tricks
- 🚀 Beginner & Getting Started
- ⚡ Advanced & Pro
- 🛠️ Tools & Resources
- 📈 Trending (score ≥ 70)
- 🏷️ General

---

## 🔧 Options

| Option | Type | Default | Description |
|---|---|---|---|
| `maxKeywords` | number | `50` | Maximum keywords to return |
| `includeTrends` | boolean | `true` | Fetch Google Trends scores |
| `grouped` | boolean | `true` | Return grouped keyword categories |

---

## 📜 License

MIT