Keyword-research-analysis/README.md

🚀 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
  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
  • 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
• 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