🔍 Visual Query Fan-out for Screaming Frog

AI-Powered Image Analysis for SEO Query Generation

A custom JavaScript extraction for Screaming Frog SEO Spider that leverages OpenAI's Vision API to analyze website images and generate comprehensive search queries based on visual content. Perfect for e-commerce SEO, visual search optimization, and content discovery.

✨ Features

• 🖼️ Intelligent Image Selection: Automatically identifies and prioritizes main content images (products, articles, galleries; if you have different needs, please play with selectors)
• 🤖 AI-Powered Analysis: Uses OpenAI's GPT-4 Vision models to understand image content
• 🔎 Query Generation: Creates relevant search queries users might use to find similar items
• 📊 Object Detection: Identifies products, attributes, brands, and text within images
• 🎯 E-commerce Optimized: Specially tuned for product images and e-commerce sites
• 📝 Comprehensive Reporting: Detailed analysis output with summaries and insights

🚀 Quick Start

Prerequisites

1. Screaming Frog SEO Spider (v16.0 or higher)
2. OpenAI API Key with Vision API access
3. JavaScript rendering enabled in Screaming Frog

Installation

1. Copy the entire JavaScript code from visual-query-fanout-lite.js or full
2. In Screaming Frog:
   • Go to Configuration > Custom > Custom JavaScript
   • Create a new extraction
   • Paste the script
   • Name it (e.g., "Visual Query Fan-out")
3. Replace the API key placeholder:

   const OPENAI_API_KEY = 'sk-proj-xxxx'; // Replace with your OpenAI API key

⚙️ Configuration

Customize the analysis by modifying the CONFIG object:

const CONFIG = {
    maxImages: 5,           // Maximum images to analyze per page
    minImageSize: 200,      // Minimum image dimension (pixels)
    maxTokens: 1000,        // Max response tokens per image
    mainContentSelectors: [ // CSS selectors for finding main content images
        'main img',
        'article img',
        '.product-image img',
        // ... add your custom selectors
    ]
};

Model Selection

Choose your OpenAI model based on needs and budget:

const MODEL = 'gpt-4o-mini'; // Options: 'gpt-4o', 'gpt-4o-mini'

• gpt-4o: Best quality, highest cost
• gpt-4o-mini: Good balance of quality and cost (recommended)
• gpt-4-turbo: Legacy option, good quality

📖 Usage

1. Configure the extraction in Screaming Frog's Custom JavaScript settings
2. Start your crawl with JavaScript rendering enabled
3. Review results in the Custom JavaScript tab

Sample Output

=== OPENAI VISION QUERY FAN-OUT ANALYSIS ===

URL: https://example.com/product/blue-jacket
Model: gpt-4o-mini
Processing Time: 2341ms

=== SUMMARY ===
• Images Found: 3
• Images Processed: 3
• Total Objects Detected: 7
• Unique Queries Generated: 21

=== DETECTED OBJECTS ===
Image 1: product-hero.jpg
  Alt: "Men's Denim Jacket"
  • Men's blue denim jacket [Apparel]
    Attributes: color: blue, material: denim, style: casual

=== TOP VISUAL FAN-OUT QUERIES ===
1. "men's blue denim jacket"
2. "casual denim jacket for men"
3. "vintage style jean jacket"

🎯 Use Cases

E-commerce SEO

• Discover missing alt text opportunities
• Generate product-specific long-tail keywords
• Identify visual search optimization gaps
• Analyze competitor product imagery

Content Marketing

• Extract topics from infographics
• Generate related content ideas
• Identify visual content gaps
• Optimize image-based content

Technical SEO Audits

• Verify image relevance to page content
• Identify duplicate or similar images
• Assess image context alignment
• Evaluate visual content quality

🔧 Advanced Features

Smart Image Filtering

The script intelligently filters images by:

• Checking parent containers (main, article, product divs)
• Analyzing CSS classes and URLs for product indicators
• Excluding UI elements (logos, icons, tracking pixels)
• Validating minimum size requirements

Comprehensive Analysis Output

Each image analysis includes:

• Objects: Detailed item identification with attributes
• Text Detection: Brands, labels, and visible text
• Scene Analysis: Image type, composition, and purpose
• Search Queries: Multiple relevant search terms per object
• Fan-out Queries: Top-level queries for the entire image

📊 Performance Considerations

• Rate Limits: OpenAI API has rate limits; adjust maxImages accordingly
• Costs: Each image analysis consumes API tokens (check OpenAI pricing)
• Crawl Speed: Enable JavaScript rendering; expect slower crawls
• Timeout: Large images may take longer to process

🐛 Troubleshooting

Common Issues

Issue	Solution
No images found	Check CSS selectors match your site structure
API errors	Verify API key and check rate limits
Partial results	Increase timeout in Screaming Frog settings
Missing images	Ensure JavaScript rendering is enabled

📈 Best Practices

1. Start Small: Test on a few URLs before full site crawls
2. Customize Selectors: Adapt selectors to your site structure
3. Review Output: Manually verify AI-generated queries for relevance
4. Batch Processing: Use URL lists for targeted analysis

🔄 Updates & Compatibility

• Screaming Frog: v22.0+
• OpenAI API: Compatible with GPT 4o mini Vision API

📝 License

MIT License - Feel free to modify and distribute

🤝 Contributing

Contributions welcome! Please feel free to submit a Pull Request.

Ideas for Contribution

• Add support for other vision APIs (Claude, Gemini)
• Implement caching to reduce API calls

💬 Support

• Issues: Please use GitHub Issues for bug reports
• Discussions: Use GitHub Discussions for questions and ideas
• Updates: Watch this repo for new features

🏆 Credits

Developed for the SEO community to bridge the gap between visual content and search optimization.

---

⚡ Pro Tip: Combine this with Screaming Frog's other custom JavaScript snippets for comprehensive visual SEO audits!

📊 Example Metrics You Can Extract

• Visual diversity score per page
• Brand mention frequency in images
• Product attribute coverage
• Search query relevance scores
• Image-to-content alignment metrics

---

Made with ❤️ for SEO / AI professionals and digital marketers