# CLAUDE.md

## Overview

SERP analysis tool for understanding search result landscapes. Detects Google SERP features (featured snippets, PAA, knowledge panels, local pack, video, ads), analyzes Naver SERP composition (blog, cafe, knowledge iN, Smart Store, brand zone, shortform, influencer), maps competitor positions, and scores SERP feature opportunities.

## Quick Start

```bash
pip install -r scripts/requirements.txt

# Google SERP analysis
python scripts/serp_analyzer.py --keyword "치과 임플란트" --country kr --json

# Naver SERP analysis
python scripts/naver_serp_analyzer.py --keyword "치과 임플란트" --json
```

## Scripts

| Script | Purpose | Key Output |
|--------|---------|------------|
| `serp_analyzer.py` | Google SERP feature detection and competitor mapping | SERP features, competitor positions, opportunity scores |
| `naver_serp_analyzer.py` | Naver SERP composition analysis | Section distribution, content type mapping |
| `base_client.py` | Shared utilities | RateLimiter, ConfigManager, BaseAsyncClient |

## SERP Analyzer (Google)

```bash
# Single keyword analysis
python scripts/serp_analyzer.py --keyword "dental implant cost" --json

# Korean market
python scripts/serp_analyzer.py --keyword "치과 임플란트 가격" --country kr --json

# Multiple keywords from file
python scripts/serp_analyzer.py --keywords-file keywords.txt --country kr --json

# Output to file
python scripts/serp_analyzer.py --keyword "dental implant" --output serp_report.json
```

**Capabilities**:
- SERP feature detection (featured snippet, PAA, knowledge panel, local pack, video carousel, ads, image pack, site links)
- Competitor position mapping per keyword
- Content type distribution analysis (blog, product, service, news, video)
- SERP feature opportunity scoring
- Search intent validation from SERP composition
- SERP volatility assessment

## Naver SERP Analyzer

```bash
# Analyze Naver search results
python scripts/naver_serp_analyzer.py --keyword "치과 임플란트" --json

# Analyze multiple keywords
python scripts/naver_serp_analyzer.py --keywords-file keywords.txt --json
```

**Capabilities**:
- Naver section detection (블로그, 카페, 지식iN, 스마트스토어, 브랜드존, 도서, 숏폼, 인플루언서)
- Section priority mapping (which sections appear above fold)
- Content type distribution per section
- Brand zone presence detection
- Shortform/influencer content analysis

## Data Sources

| Source | Purpose |
|--------|---------|
| `our-seo-agent` CLI | Primary data source (future); use `--input` for pre-fetched JSON |
| WebSearch / WebFetch | Live SERP data and Naver section analysis |
| Notion MCP | Save analysis report to SEO Audit Log database |

## Output Format

```json
{
  "keyword": "치과 임플란트",
  "country": "kr",
  "serp_features": {
    "featured_snippet": true,
    "people_also_ask": true,
    "local_pack": true,
    "knowledge_panel": false,
    "video_carousel": false,
    "ads_top": 3,
    "ads_bottom": 2
  },
  "competitors": [
    {
      "position": 1,
      "url": "https://example.com/page",
      "domain": "example.com",
      "title": "...",
      "content_type": "service_page"
    }
  ],
  "opportunity_score": 72,
  "intent_signals": "commercial",
  "timestamp": "2025-01-01T00:00:00"
}
```

## Notion Output (Required)

**IMPORTANT**: All audit reports MUST be saved to the OurDigital SEO Audit Log database.

### Database Configuration

| Field | Value |
|-------|-------|
| Database ID | `2c8581e5-8a1e-8035-880b-e38cefc2f3ef` |
| URL | https://www.notion.so/dintelligence/2c8581e58a1e8035880be38cefc2f3ef |

### Required Properties

| Property | Type | Description |
|----------|------|-------------|
| Issue | Title | Report title (Korean + date) |
| Site | URL | Audited website URL |
| Category | Select | SERP Analysis |
| Priority | Select | Based on opportunity score |
| Found Date | Date | Analysis date (YYYY-MM-DD) |
| Audit ID | Rich Text | Format: SERP-YYYYMMDD-NNN |

### Language Guidelines

- Report content in Korean (한국어)
- Keep technical English terms as-is (e.g., SERP, Featured Snippet, PAA)
- URLs and code remain unchanged
