Keyword-research-analysis/API_QUICK_REFERENCE.md

SEMrush API Quick Reference

⚠️ IMPORTANT: Costs Are ESTIMATED

All costs below are ESTIMATES. Verify against your actual usage:

• Check actual consumption: https://www.semrush.com/api-units/
• Run calibration after first analysis (see below)
• Update API_UNIT_COSTS in semrushApi.js if needed

✅ Verified from Documentation:

• phrase_this (Keyword Overview): 10 units/line
• Batch Keyword Overview: 10 units/line
• Keyword Difficulty (phrase_kdi): 50 units/line
• domain_organic: 10 units/line

⚠️ Estimated (needs verification):

• domain_domains, domain_ranks, backlinks_* endpoints

---

🚀 Quick Start

Single Analysis Cost (ESTIMATED)

1 client + 3 competitors + 1000 keyword limit = ~$0.37 per analysis
(Verify with actual usage after first run!)

API Unit Costs Cheat Sheet

✅ VERIFIED:
phrase_this:          10 units/line  (Keyword Overview)
domain_organic:       10 units/line  (Organic keywords)
phrase_kdi:           50 units/line  (Keyword Difficulty)

⚠️ ESTIMATED (verify with actual usage):
domain_domains:       10 units/line
domain_ranks:         10 units/domain
backlinks_overview:   10 units/domain
backlinks_refdomains: 10 units/line

📊 Cost Calculator

By Display Limit

Limit	Cost/Analysis
100	$0.04
500	$0.20
1,000	$0.37
2,000	$0.72
5,000	$1.77

By Number of Analyses

Analyses	API Cost	Total w/ Plan
1	$0.37	$500.32
10	$3.74	$503.69
100	$37.40	$537.35
1,000	$374.00	$873.95

🎯 First-Time Setup: Calibrate Costs

1. Run Small Test Analysis

const result = await fetchUnifiedAnalysis({
  clientUrl: 'mysite.com',
  competitors: ['competitor1.com'],
  database: 'us',
  apiKey: process.env.SEMRUSH_API_KEY,
  displayLimit: 100  // Keep it small for testing
})

console.log('Estimated units:', result.apiUsage.totalUnits)

2. Check Actual Usage

Go to https://www.semrush.com/api-units/ and check API Query Log

3. Calibrate

import { calibrateApiCosts } from './services/semrushApi'

const actualUnits = 856  // From SEMrush dashboard
const calibration = calibrateApiCosts(actualUnits, {
  linesReturned: 85
})

console.log(`Accuracy: ${calibration.accuracyPercent}%`)

4. Update if Needed

If accuracy < 90%, update API_UNIT_COSTS in semrushApi.js

---

🔧 Usage Examples

Basic Analysis

import { fetchUnifiedAnalysis, getApiUnitReport } from './services/semrushApi'

const result = await fetchUnifiedAnalysis({
  clientUrl: 'mysite.com',
  competitors: ['competitor1.com', 'competitor2.com'],
  database: 'us',
  apiKey: process.env.SEMRUSH_API_KEY,
  displayLimit: 1000
})

// Check API usage
console.log('Units used:', result.apiUsage.totalUnits)
console.log('Cost:', result.apiUsage.totalCost)

Estimate Before Running

import { estimateApiUnits } from './services/semrushApi'

const estimate = estimateApiUnits({
  clientUrl: 'mysite.com',
  competitors: ['comp1.com', 'comp2.com', 'comp3.com'],
  displayLimit: 1000
})

console.log(`Estimated cost: ${estimate.total.cost}`)
console.log(`Cost per 100 analyses: ${estimate.total.per100Analyses}`)

Check Single Keyword Intent

import { fetchPhraseIntent } from './services/semrushApi'

const intent = await fetchPhraseIntent('cloud security tips', 'us', apiKey)
console.log(intent.intentLabel) // "Informational"
console.log('Cost: $0.005 (100 units)')

⚠️ Common Pitfalls

1. Use Built-in Intent Filter (More Efficient)

// ✅ BEST - Intent filter built into domain_domains (no extra cost)
const result = await fetchDomainVsDomain(...) // Intent=1 filter included

// ⚠️ WORKS BUT REDUNDANT - phrase_this costs 10 units/keyword ($0.50 for 1000)
const keywords = await filterInformationalKeywords(keywords, 'us', apiKey)
// Only use if you need to double-validate Intent values

2. Don't Set Display Limit Too High

// ❌ BAD - Costs $1.77 per analysis
displayLimit: 5000

// ✅ GOOD - Costs $0.37 per analysis, usually sufficient
displayLimit: 1000

3. Don't Forget Business Plan Cost

API units alone: $0.37 per analysis
But monthly cost: $499.95 + API units
First analysis: $500.32 total

📈 Optimization Tips

1. Use Intent Filter (Built-in)

Reduces results by ~30% = saves 3,000 units per analysis

2. Batch Multiple Clients

Run 100 analyses together instead of one-off

3. Cache Results

Store results for 24-48 hours to avoid re-analysis

4. Optimize Display Limit

Start with 500, increase only if needed

5. Monitor Monthly Usage

Set alerts at 80% of purchased units

🎯 Break-Even Analysis

Monthly Business Plan: $499.95

If you run:

• 1 analysis/month: $500.32 total
• 100 analyses/month: $537.35 total ($5.37 per analysis)
• 1,000 analyses/month: $873.95 total ($0.87 per analysis)

Per-Analysis Cost Breakdown

Fixed: $499.95 / analyses_per_month
Variable: ~$0.37 per analysis

1 analysis:    $500.32 per analysis
10 analyses:   $50.37 per analysis
100 analyses:  $5.37 per analysis
1,000 analyses: $0.87 per analysis

💰 Budget Planning

Conservative Budget (100 analyses/month)

Business Plan:  $499.95
API Units:      $37.40
─────────────────────────
Monthly Total:  $537.35
Per Analysis:   $5.37

Aggressive Budget (1,000 analyses/month)

Business Plan:  $499.95
API Units:      $374.00
─────────────────────────
Monthly Total:  $873.95
Per Analysis:   $0.87

🔍 Monitoring Commands

In Your Code

// Get detailed report
const report = getApiUnitReport()
console.log(report.summary)

// Check specific API
console.log(report.breakdown.domain_domains)

Console Output

Look for these log messages:

[API UNITS] domain_domains: 7000 units (~$0.3500)
[API UNIT TRACKER] Session started
============================================================
API UNIT USAGE REPORT
============================================================

📋 Checklist Before Production

• Business Plan subscription active ($499.95/month)
• API units purchased (recommend 400,000+ units)
• Display limit optimized (test with 100, use 1000 in prod)
• API usage tracking enabled (automatic in fetchUnifiedAnalysis)
• Monthly usage alerts configured
• Caching strategy implemented
• Error handling for "insufficient units" errors
• Budget approved for scale (see break-even analysis)

🆘 Emergency Actions

Running Out of Units

1. Purchase more units immediately ($1 = 20,000 units)
2. Reduce display_limit temporarily
3. Cache results more aggressively
4. Pause non-critical analyses

Unexpected High Usage

1. Check getApiUnitReport() output
2. Look for phrase_this calls (100 units each!)
3. Verify display_limit settings
4. Review number of competitors per analysis

📞 Quick Links

• Buy API Units
• Check Balance
• API Documentation
• Support

---

TL;DR:

• Need Business Plan ($499.95/month)
• Each analysis costs ~$0.37 in API units
• Built-in tracking shows exact usage
• Avoid phrase_this for bulk operations
• 100+ analyses/month = cost-effective