352 lines
11 KiB
Markdown
352 lines
11 KiB
Markdown
# 🚀 SEO Keyword Gap Analyzer
|
||
|
||
A simple tool that helps you find keyword opportunities by comparing your website with your competitors. Think of it as a "spy tool" that shows you which keywords your competitors are ranking for, but you're not!
|
||
|
||
---
|
||
|
||
## 🎯 What Does This Tool Do?
|
||
|
||
Imagine you run a website and want to know:
|
||
- **What keywords are my competitors ranking for that I'm missing?**
|
||
- **How much traffic could I get from those keywords?**
|
||
- **Which keywords are easiest to rank for?**
|
||
|
||
This tool answers all these questions automatically! It:
|
||
|
||
1. ✅ Analyzes your website and up to 5 competitor websites
|
||
2. ✅ Finds "gap keywords" (keywords competitors rank for, but you don't)
|
||
3. ✅ Shows you important metrics like search volume, keyword difficulty, and more
|
||
4. ✅ Filters for "informational" keywords (educational content like guides, how-tos, etc.)
|
||
5. ✅ Displays domain metrics (authority score, traffic, backlinks)
|
||
6. ✅ Can send results directly to Hookpilot for content planning
|
||
|
||
---
|
||
|
||
## 📋 What You Need Before Starting
|
||
|
||
### 1. **A Computer**
|
||
- Works on Windows, Mac, or Linux
|
||
|
||
### 2. **Internet Connection**
|
||
- You'll need internet to download the tool and fetch data from SEMrush
|
||
|
||
### 3. **SEMrush API Key** 🔑
|
||
- This is like a "password" that lets you access SEMrush data
|
||
- **How to get it:**
|
||
1. Go to [SEMrush](https://www.semrush.com/)
|
||
2. Sign up for an account (you'll need a paid Business plan)
|
||
3. Go to your account settings
|
||
4. Find "API" section and copy your API key
|
||
- **Cost:** SEMrush Business plan costs around 499.95 per month
|
||
|
||
### 4. **Node.js Installed on Your Computer**
|
||
- Node.js is a program that lets you run this tool
|
||
- **How to check if you have it:**
|
||
- Open "Terminal" (Mac) or "Command Prompt" (Windows)
|
||
- Type: `node --version`
|
||
- If you see a version number (like v18.0.0), you're good!
|
||
- **If you don't have it:**
|
||
- Go to [nodejs.org](https://nodejs.org/)
|
||
- Download and install the "LTS" version (it's the recommended one)
|
||
|
||
---
|
||
|
||
## 🛠️ How to Install and Run the Tool
|
||
|
||
Follow these simple steps:
|
||
|
||
### Step 1: Download the Project
|
||
1. Open "Terminal" (Mac) or "Command Prompt" (Windows)
|
||
2. Navigate to where you want to save the project (for example, your Documents folder)
|
||
3. If you have the project as a zip file, unzip it
|
||
4. If you received it from GitHub, type:
|
||
```
|
||
git clone [project-url]
|
||
```
|
||
|
||
### Step 2: Open the Project Folder
|
||
1. In Terminal/Command Prompt, type:
|
||
```
|
||
cd semrush-vinita
|
||
```
|
||
(This moves you into the project folder)
|
||
|
||
### Step 3: Install Required Components
|
||
1. Type this command and press Enter:
|
||
```
|
||
npm install
|
||
```
|
||
2. Wait for it to finish (it might take 2-3 minutes)
|
||
3. This downloads all the necessary "helpers" the tool needs to work
|
||
|
||
### Step 4: Start the Tool
|
||
1. Type this command:
|
||
```
|
||
npm run dev
|
||
```
|
||
2. You should see a message like:
|
||
```
|
||
Local: http://localhost:3000/
|
||
```
|
||
3. Open your web browser (Chrome, Firefox, Safari, etc.)
|
||
4. Go to: `http://localhost:3000/`
|
||
5. You should see the tool's homepage! 🎉
|
||
|
||
---
|
||
|
||
## 📖 How to Use the Tool
|
||
|
||
### Step 1: Fill Out the Form
|
||
|
||
You'll see a form with several fields:
|
||
|
||
#### **Client Website URL** (Required)
|
||
- Type your website address here
|
||
- Example: `mywebsite.com` or `www.mywebsite.com`
|
||
- Don't include `http://` or `https://`
|
||
|
||
#### **Competitor Websites** (At least 1 required)
|
||
- Type your competitors' website addresses
|
||
- You can add up to 5 competitors
|
||
- Example: `competitor1.com`, `competitor2.com`
|
||
|
||
#### **Search Database**
|
||
- Choose your country/region
|
||
- Most people use `us` for United States
|
||
- Other options: `uk`, `ca`, `in`, etc.
|
||
|
||
#### **Display Limit**
|
||
- How many keywords do you want to analyze?
|
||
- **Default: 10** (recommended for beginners)
|
||
- Higher numbers = more keywords but costs more API units
|
||
- Range: 1 to 10,000
|
||
|
||
#### **SEMrush API Key** 🔑
|
||
- Paste your SEMrush API key here
|
||
- This is the "password" you got from SEMrush
|
||
|
||
### Step 2: Click "Start Analysis"
|
||
|
||
1. Click the big blue button
|
||
2. The tool will show a progress bar
|
||
3. Wait for the analysis to complete (usually 10-30 seconds)
|
||
|
||
### Step 3: Review the Results
|
||
|
||
The tool shows you several sections:
|
||
|
||
#### **📊 API Usage Report** (Top)
|
||
- **Total Units:** How many SEMrush API units were used
|
||
- **Duration:** How long the analysis took
|
||
- This helps you track your SEMrush usage
|
||
|
||
#### **📈 Domain Metrics** (Cards)
|
||
Shows information about each website analyzed:
|
||
- **Authority Score:** How "trustworthy" the website is (0-100, higher is better)
|
||
- **Organic Traffic:** How many visitors from Google
|
||
- **Organic Keywords:** How many keywords the site ranks for
|
||
- **Total Backlinks:** How many other websites link to this site
|
||
- **Referring Domains:** How many unique websites link to this site
|
||
|
||
**💡 Tip:** Click on any domain card to see detailed information:
|
||
- Top 10 Organic Keywords
|
||
- Top 10 Referring Domains
|
||
|
||
#### **🎯 Informational Gap Keywords** (Main Results)
|
||
This is the most important section! It shows keywords that:
|
||
- ✅ Your competitors rank for
|
||
- ❌ You don't rank for yet
|
||
- ✅ Are "informational" (educational content)
|
||
|
||
For each keyword, you see:
|
||
- **Keyword:** The actual search term
|
||
- **Intent:** Should always be "Informational"
|
||
- **Search Volume:** How many people search for this per month (higher = more potential traffic)
|
||
- **Keyword Difficulty:** How hard it is to rank (0-100, lower = easier)
|
||
- **Competitors Found In:** Which competitors rank for this keyword
|
||
|
||
#### **Actions You Can Take:**
|
||
1. **Sort:** Click column headers to sort by volume, difficulty, etc.
|
||
2. **Export:** Download results as CSV file for Excel/Google Sheets
|
||
3. **Send to Hookpilot:** Send the data to Hookpilot for content planning
|
||
|
||
---
|
||
|
||
## 💰 Understanding API Costs
|
||
|
||
SEMrush charges based on "API units." Here's what the tool uses:
|
||
|
||
| Action | Cost per Item |
|
||
|--------|---------------|
|
||
| Keyword gap analysis | 80 units per keyword |
|
||
| Domain metrics | 10 units per domain |
|
||
| Keyword validation | 10 units per keyword |
|
||
| Backlink overview | 40 units per domain |
|
||
| Referring domains | 40 units per domain (×10) |
|
||
| Organic keywords | 10 units per domain (×10) |
|
||
|
||
**Example Cost (with 10 keywords, 2 competitors):**
|
||
- Keyword gap: 10 × 80 = 800 units
|
||
- Keyword validation: 10 × 10 = 100 units
|
||
- Domain metrics: 3 × 10 = 30 units
|
||
- Backlinks: 3 × 40 = 120 units
|
||
- Referring domains: 3 × 10 × 40 = 1,200 units
|
||
- Organic keywords: 3 × 10 × 10 = 300 units
|
||
- **Total: ~2,550 units** (about 0.13 from your monthly SEMrush allowance)
|
||
|
||
**💡 Tip:** Start with a small display limit (10-20) to test the tool before running large analyses.
|
||
|
||
---
|
||
|
||
## ⚠️ Troubleshooting
|
||
|
||
### Problem: "Cannot find module" error
|
||
**Solution:**
|
||
1. Make sure you ran `npm install` first
|
||
2. Try running it again
|
||
|
||
### Problem: "Port already in use" error
|
||
**Solution:**
|
||
1. Another program is using the same port
|
||
2. Close the other program or change the port in `vite.config.js`
|
||
|
||
### Problem: "ERROR 50 :: NOTHING FOUND"
|
||
**Possible causes:**
|
||
1. **Empty Client URL:** Make sure you entered your website address
|
||
2. **Invalid domain:** Check that website addresses are correct (no http://, no trailing slashes)
|
||
3. **No keywords found:** Try increasing the display limit
|
||
4. **Wrong API key:** Make sure your SEMrush API key is correct
|
||
|
||
### Problem: "Network Error" or "Failed to fetch"
|
||
**Solution:**
|
||
1. Check your internet connection
|
||
2. Make sure your SEMrush API key is valid
|
||
3. Verify your SEMrush subscription is active
|
||
|
||
### Problem: Tool is running slow
|
||
**Solution:**
|
||
1. Reduce the display limit (try 10-20 instead of 100+)
|
||
2. Analyze fewer competitors
|
||
3. Close other browser tabs
|
||
|
||
---
|
||
|
||
## 🎓 Tips for Best Results
|
||
|
||
### For Beginners:
|
||
1. **Start small:** Use display limit of 10-20 for your first analysis
|
||
2. **Test with 1-2 competitors:** Don't analyze 5 competitors right away
|
||
3. **Check your API usage:** The tool shows how many units you used
|
||
|
||
### For Advanced Users:
|
||
1. **Higher display limits:** Use 50-100 for comprehensive analysis
|
||
2. **Multiple competitors:** Compare against 3-5 competitors for better insights
|
||
3. **Export data:** Download CSV files for deeper analysis in Excel
|
||
|
||
### Interpreting Results:
|
||
- **High Volume + Low Difficulty = Great Opportunity!** 🎯
|
||
- These keywords are searched a lot but easier to rank for
|
||
|
||
- **Low Volume + High Difficulty = Skip for now** ⚠️
|
||
- Not worth the effort for beginners
|
||
|
||
- **Focus on Informational Keywords:** 📚
|
||
- These are perfect for blog posts, guides, and tutorials
|
||
- Usually easier to rank than commercial keywords
|
||
|
||
---
|
||
|
||
## 🤝 Need Help?
|
||
|
||
If you're stuck or confused:
|
||
|
||
1. **Check the Console Logs:**
|
||
- In your browser, press F12 (Windows) or Cmd+Option+I (Mac)
|
||
- Click on "Console" tab
|
||
- You'll see detailed logs of what's happening
|
||
|
||
2. **Common Questions:**
|
||
- **Q: How do I stop the tool?**
|
||
- A: Press `Ctrl+C` in the Terminal/Command Prompt window
|
||
|
||
- **Q: Can I run multiple analyses at once?**
|
||
- A: No, wait for one to finish before starting another
|
||
|
||
- **Q: Where are my results saved?**
|
||
- A: Results are shown on screen. Use "Export CSV" to save them
|
||
|
||
- **Q: How often can I use this?**
|
||
- A: As much as you want, but watch your SEMrush API unit balance
|
||
|
||
---
|
||
|
||
## 📁 Project Structure
|
||
|
||
```
|
||
semrush-vinita/
|
||
├── src/
|
||
│ ├── components/ # Visual components (forms, results display)
|
||
│ ├── services/ # Logic for talking to SEMrush API
|
||
│ ├── App.jsx # Main application
|
||
│ └── main.jsx # Entry point
|
||
├── package.json # List of required components
|
||
├── vite.config.js # Configuration file
|
||
└── README.md # This file!
|
||
```
|
||
|
||
---
|
||
|
||
## 🔒 Privacy & Security
|
||
|
||
- Your SEMrush API key is stored only in your browser (not on any server)
|
||
- All data analysis happens in your browser
|
||
- No data is collected or stored by this tool
|
||
- Only sent to Hookpilot if you click "Send to Hookpilot" button
|
||
|
||
---
|
||
|
||
## 📝 Quick Start Checklist
|
||
|
||
Before your first analysis, make sure you have:
|
||
|
||
- [ ] Node.js installed on your computer
|
||
- [ ] Downloaded/cloned this project
|
||
- [ ] Ran `npm install` successfully
|
||
- [ ] Started the tool with `npm run dev`
|
||
- [ ] Opened `http://localhost:5173/` in your browser
|
||
- [ ] Have your SEMrush API key ready
|
||
- [ ] Know your website URL and competitor URLs
|
||
|
||
---
|
||
|
||
## 🎉 You're All Set!
|
||
|
||
Start analyzing keywords and finding content opportunities! Remember:
|
||
|
||
1. **Start small** (10 keywords, 1-2 competitors)
|
||
2. **Watch your API usage** (shown in the results)
|
||
3. **Export valuable data** (CSV download button)
|
||
4. **Focus on high-volume, low-difficulty keywords** for quick wins
|
||
|
||
Happy keyword hunting! 🔍✨
|
||
|
||
---
|
||
|
||
## 📞 Technical Support
|
||
|
||
For SEMrush API issues:
|
||
- Visit: [SEMrush API Documentation](https://developer.semrush.com/api)
|
||
- Email: mail@semrush.com
|
||
- Phone: +1 (800) 815-9959 (12:00 PM - 5:00 PM EST/EDT, Monday - Friday)
|
||
|
||
For tool-specific issues:
|
||
- Check the troubleshooting section above
|
||
- Review console logs in your browser (F12)
|
||
- Make sure all prerequisites are installed correctly
|
||
|
||
---
|
||
|
||
**Version:** 1.0
|
||
**Last Updated:** November 2025
|
||
**Made with ❤️ for SEO professionals and content creators**
|