nod-serp-analysis

SERP Analysis

You analyze Google search results using NodesHub SERPdata API to provide actionable SEO intelligence.

Quick Start

# Single keyword analysis
python3 .claude/skills/nod-nodeshub-api/scripts/serpdata.py "keyword" --gl us --hl en

# Raw JSON for deeper analysis
python3 .claude/skills/nod-nodeshub-api/scripts/serpdata.py "keyword" --gl us --hl en --raw

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

Setup

Requires NODESHUB_API_KEY in environment. Run:

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

If missing, see nod-nodeshub-api setup.

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: Single Keyword SERP Analysis

1. Fetch SERP data — run serpdata.py with --raw flag
2. Analyze organic results — who ranks, what content types dominate
3. Map SERP features — which features appear, what they reveal about intent
4. Assess competition — domain authority signals, content depth
5. Identify opportunities — gaps in existing results, underserved angles
6. Deliver report — structured analysis with actionable recommendations

Workflow: Multi-Keyword SERP Comparison

1. Fetch SERP for each keyword (batch — mind token budget)
2. Cross-reference domains — who ranks across multiple keywords
3. Compare SERP features — how feature presence varies by keyword
4. Identify keyword clusters — keywords with overlapping SERPs = same intent
5. Prioritize targets — rank keywords by opportunity score

Analysis Framework

Organic Results Analysis

For each result in top 10, extract:

• Domain — who's ranking (brand vs. niche vs. aggregator)
• Title patterns — what title structures Google prefers
• URL structure — subfolder vs. subdomain, URL depth
• Content type — blog, product page, listicle, guide, tool, forum

SERP Features Mapping

Feature	What it reveals
People Also Ask	Related questions users have — content expansion opportunities
AI Overview	Google's AI summary — what content gets cited
Knowledge Panel	Entity recognition — brand/topic authority signals
Local Pack	Local intent — needs local SEO strategy
Videos	Video intent — YouTube/video content opportunity
Top Stories	News intent — freshness matters
Related Searches	Semantic connections — keyword expansion ideas
Featured Snippet	Direct answer opportunity — structure content for position 0

Intent Classification (from SERP signals)

Classify based on what you see:

• Informational — PAA, Knowledge Panel, long-form content dominate
• Commercial — Product comparisons, reviews, "best X" in titles
• Transactional — Shopping results, product pages, pricing in titles
• Navigational — Brand dominates, official site in #1

Competition Assessment

Rate difficulty based on:

• Domain types — all big brands = hard; niche sites ranking = opportunity
• Content quality — thin results = easy to outrank; deep guides = harder
• SERP volatility — many SERP features = more entry points
• Content freshness — old dates = opportunity for fresh content

Output Format

## SERP Analysis: [keyword]

**Settings:** gl=[country], hl=[language], device=[device]
**Total results:** [count]

### Dominant Intent
[informational/commercial/transactional/navigational] — [evidence]

### SERP Features Present
- [Feature]: [insight]

### Top 10 Organic Results
| # | Domain | Title | Type | Notes |
|---|--------|-------|------|-------|
| 1 | ... | ... | ... | ... |

### Domain Distribution
- [domain.com]: positions [X, Y] — [pattern]

### Content Patterns
- Dominant format: [listicle/guide/tool/...]
- Average title length: [X chars]
- Title patterns: [common structures]

### Opportunities
1. [Gap or angle not covered by current results]
2. [SERP feature not being targeted]
3. [Content type missing from results]

### Recommendations
1. [Specific, actionable recommendation]
2. [...]

Parameters Reference

Param	Values	Notes
--gl	us, pl, de, uk, fr, es...	Country — affects local results
--hl	en, pl, de, fr, es...	Language — affects interface/results language
--device	desktop, mobile	Different SERP layouts and features

For full country/language list: python3 .claude/skills/nod-nodeshub-api/scripts/params.py countries

Tips

• Always use --raw for full analysis — the pretty output is just a preview
• Compare desktop vs mobile — SERP features differ significantly
• Check different countries — local competition varies
• Mind token budget — each call = 1 token. For 20 keywords = 20 tokens
• Parse snippets_data carefully — SERP features are the richest insight source

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

To generate, use the render_report_section(data) function from this skill's script, then create_report() or append_section() from report.py:

from report import create_report, append_section
section_html = render_report_section(analysis_data)
# New report:
path = create_report("SERP Analysis", sections=[section_html])
# Or append to existing:
path = append_section("reports/existing.html", section_html)

Related Skills

• nod-keyword-research — expand keywords before analyzing SERPs

• nod-content-brief — turn SERP analysis into content brief

• API response quirks or undocumented fields

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

1. Merge duplicate/overlapping entries into single proven patterns
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 - if obvious, cut it