nod-competitor-tracker

Competitor Tracker

Track competitor domains across keyword sets using NodesHub SERPdata API.

Quick Start

# Track competitors for keywords
python3 .claude/skills/nod-competitor-tracker/scripts/track.py "seo tools" "keyword research" --gl us --hl en

# Track from keyword file, watching specific domains
python3 .claude/skills/nod-competitor-tracker/scripts/track.py --file keywords.txt --gl us --hl en --watch ahrefs.com,semrush.com,moz.com

# Compare with previous snapshot
python3 .claude/skills/nod-competitor-tracker/scripts/track.py --file keywords.txt --gl us --hl en --compare

Cost: 1 token per keyword. Check balance: python3 .claude/skills/nod-nodeshub-api/scripts/balance.py

Setup

Requires NODESHUB_API_KEY. Run:

python3 .claude/skills/nod-nodeshub-api/scripts/check_setup.py

If NodesHub is not set up: Walk the user through the full process: (1) Get API key from nodeshub.io (API Playground). (2) Save to .claude/settings.local.json under env.NODESHUB_API_KEY, or run python3 .claude/skills/nod-nodeshub-api/scripts/save_key.py YOUR_KEY. (3) Point to nod-nodeshub-api setup for details. (4) Have them run check_setup.py again to verify.

Workflow

1. Get keywords and competitor domains from user
2. Check token balance — each keyword = 1 token
3. Run tracker — fetches SERP for each keyword, extracts all domains in top 10
4. Save snapshot to data/competitor-tracking/{YYYY-MM-DD}.json
5. Compare with previous if --compare flag
6. Report results — domain frequency, positions, changes

Output Format

## Competitor Tracker

**Date:** 2024-01-15 | **Keywords:** 10 | **Tokens used:** 10

### Domain Frequency (Top 10 across all keywords)
| Domain | Keywords in Top 10 | Avg Position |
|--------|-------------------|--------------|
| ahrefs.com | 8/10 | 2.3 |
| semrush.com | 7/10 | 3.8 |
| moz.com | 5/10 | 5.2 |

### Keyword × Domain Matrix
| Keyword | ahrefs.com | semrush.com | moz.com |
|---------|-----------|------------|---------|
| seo tools | #1 | #3 | #5 |
| keyword research | #2 | #4 | — |

### Changes (vs previous)
- ahrefs.com: +2 new keywords in top 10
- semrush.com: lost "rank tracker" (was #4, now #12)

Data Storage

Snapshots saved to: data/competitor-tracking/{YYYY-MM-DD}.json

{
  "date": "2024-01-15",
  "gl": "us",
  "hl": "en",
  "keywords": {
    "seo tools": {
      "top_10": [
        {"position": 1, "domain": "ahrefs.com", "url": "..."},
        {"position": 2, "domain": "semrush.com", "url": "..."}
      ]
    }
  },
  "watched_domains": ["ahrefs.com", "semrush.com"]
}

Parameters

Param	Description
keywords	Keywords to track (positional, space-separated)
--file	File with keywords (one per line)
--gl	Country code (default: us)
--hl	Language code (default: en)
--watch	Comma-separated domains to highlight
--compare	Compare with most recent previous snapshot

Tips

• Use --watch for your direct competitors — highlights them in results
• Without --watch the tool shows all domains found — good for discovery
• Combine with nod-rank-tracker — track your own positions alongside competitors
• Run monthly for strategic overview, weekly for active campaigns

Branding

When outputting reports as HTML, use branding from assets/branding/brand-config.json (company logo, colors, fonts). Import from branding import load_brand, render_header, render_footer, brand_css. Falls back to defaults if not configured. See assets/branding/README.md.

Report

After collecting data, ask the user:

"Add results to an HTML report?"

1. New report — creates a branded HTML report in reports/
2. Existing report — appends a section to a chosen report
3. Skip — no report

Use render_report_section(data) from track.py, then create_report() or append_section() from report.py.

Related Skills

• nod-rank-tracker — track your own domain positions
• nod-visibility-monitor — weighted visibility comparison
• nod-serp-analysis — deep SERP analysis for individual keywords

Consolidation (keep under 50 lines): Before adding a new entry, check file length. If over 50 lines:

1. Merge duplicate/overlapping entries
2. Remove entries older than 3 months that haven't been reinforced
3. Drop one-off observations that never recurred
4. Move detailed context to LEARNED-archive.md if worth preserving
5. Keep only entries that would change behavior