serp-research-cli

Analyze and compare Google SERP (Search Engine Results Page) titles to reveal search intent and market positioning differences.

What is this?

serp-research-cli collects Google's top 10 organic search results and analyzes their titles using morphological analysis and structural pattern detection. It's useful for:

• Understanding what titles actually appear on Google (not HTML <title> tags, but SERP display text)
• Finding patterns in successful title formats for your market
• Comparing multiple keywords to discover how search intent differs

Features

• Single Keyword Analysis: Detailed title structure analysis (patterns, keywords, symbols)
• Multi-Keyword Comparison: Compare multiple SERPs side-by-side to find differences
• Morphological Analysis: Extract frequent nouns and co-occurring keywords from titles
• Pattern Detection: Identify 6 structural patterns (method-type, procedure-type, definition-type, numbers, years, questions)
• Symbol Usage: Visualize which symbols are common in top results
• Mock Mode: Test without a DataForSEO API account

Installation

npm install -g serp-research-cli

Quick Start (3 minutes)

1. Run with mock data (no setup needed)

serp analyze "Python 入門" --mock
serp compare "ChatGPT 活用法" "Gemini 活用法" --mock

2. Using real SERP data

To use actual Google search data:

1. Create a DataForSEO account at dataforseo.com
2. Create a .env file in your project:

   DATAFORSEO_LOGIN=your_login
   DATAFORSEO_PASSWORD=your_password

3. Run commands without --mock:

   serp analyze "Python 入門"
   serp compare "ChatGPT 活用法" "Gemini 活用法" "Claude 活用法"

Examples

Single Keyword Analysis

serp analyze "Python 入門"

Outputs:

• Console display of top 10 titles and analysis
• JSON file: output/json/20260728-1234567_Python_入門.json
• Markdown file: output/markdown/20260728-1234567_Python_入門.md

Multi-Keyword Comparison

serp compare "ChatGPT 活用法" "Gemini 活用法" "Claude 活用法"

Shows side-by-side analysis of:

• Common Keywords: Keywords appearing across multiple SERPs
• Keyword Differences: Keywords unique to each SERP
• Pattern Comparison: How title patterns differ
• Comparison Summary: Factual differences at a glance

Configuration

Environment Variables

Create a .env file in your working directory:

DATAFORSEO_LOGIN=your_login_here
DATAFORSEO_PASSWORD=your_password_here

To get credentials:

1. Sign up at dataforseo.com
2. Go to Dashboard → API Credentials
3. Copy your login and password

Output Directories

Results are saved in:

• API results: output/json/ and output/markdown/
• Mock results: test/output/json/ and test/output/markdown/

Files are timestamped in JST (UTC+9) and named after sanitized keywords.

Documentation

• Usage Guide - Detailed command reference
• Examples - Real output samples
• Configuration - API setup and options

Commands Reference

# Single keyword analysis
serp analyze "<keyword>"
serp analyze "<keyword>" --mock          # with mock data

# Multi-keyword comparison
serp compare "<keyword1>" "<keyword2>" [<keyword3>...]
serp compare "<keyword1>" "<keyword2>" --mock

# Development
npm run typecheck                         # TypeScript check
npm test                                  # Run tests
npm run build                             # Build dist/
npm run clean:test                        # Clear test/output/
npm run clean:output                      # Clear output/

Philosophy

This tool observes and structures search results without interpretation. It:

• ✅ Collects data objectively
• ✅ Detects structural patterns
• ✅ Presents facts clearly
• ✅ Lets you make decisions

It does NOT:

• ❌ Generate title suggestions
• ❌ Score titles or patterns
• ❌ Fetch article text
• ❌ Make recommendations

Use the output as input to AI systems if you need higher-level analysis.

Requirements

• Node.js: 20 or later
• DataForSEO Account: For real data (optional, mock mode works without)
• npm: For installation

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Note: This tool analyzes SERP display text as shown to users, which may differ from HTML <title> tags. This is intentional and reflects real search results.