287 lines
7.6 KiB
Markdown
287 lines
7.6 KiB
Markdown
# 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/](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
|
|
```javascript
|
|
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/](https://www.semrush.com/api-units/) and check API Query Log
|
|
|
|
### 3. Calibrate
|
|
```javascript
|
|
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
|
|
```javascript
|
|
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
|
|
```javascript
|
|
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
|
|
```javascript
|
|
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)
|
|
```javascript
|
|
// ✅ 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
|
|
```javascript
|
|
// ❌ 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
|
|
```javascript
|
|
// 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](https://www.semrush.com/api-units/)
|
|
- [Check Balance](https://www.semrush.com/api-units/)
|
|
- [API Documentation](https://developer.semrush.com/)
|
|
- [Support](https://www.semrush.com/kb/5-api)
|
|
|
|
---
|
|
|
|
**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
|
|
|