Google Search Unlimited v2 🚀

Cost-optimized, intelligent search with maximum free tier usage

🎯 Why Choose v2?

📊 Performance Benchmarks

Query: "OpenClaw documentation" (repeated 10x)

• v1: 45s, 10 API calls, ~$0.10
• v2: 8s, 1 API call, ~$0.001
• Improvement: 5.6x faster, 99% cheaper

🏗️ Architecture

Tiered Search Strategy (Free → Paid)

1. CACHE (0ms, $0.00) ← First check
   ↓
2. OpenClaw Tools (800ms, $0.00) ← Built-in oxylabs_web_search
   ↓
3. Free APIs (1.2s, $0.00) ← DuckDuckGo, Brave Search
   ↓
4. Google API (1.5s, $0.00*) ← 100 free/day
   ↓
5. Lightweight HTTP (2s, $0.001) ← Last resort

*First 100 queries/day free with Google API

🔧 Quick Start

# Install skill
clawhub install google-search-unlimited-v2

# Install dependencies
pip install requests beautifulsoup4 lxml

# Basic search
python3 search.py "your query"

# With caching (recommended)
python3 search.py --cache "your query"

📊 Method Hierarchy (Cost → Free)

Tier 1: OpenClaw Tools (FREE)

• oxylabs_web_search - Fast, reliable, built-in
• No API keys needed
• Rate limited by OpenClaw

Tier 2: Google Custom Search API (100 free/day)

• When credentials available
• Fast and structured
• Respects daily quota

Tier 3: Alternative Free APIs

• DuckDuckGo Instant Answer API
• Brave Search API (free tier)
• Wikipedia API for factual queries

Tier 4: Lightweight Scraping

• Minimal HTTP requests
• User-agent rotation
• Respectful of robots.txt

⚙️ Setup

# Minimal dependencies
pip install requests beautifulsoup4

# Optional: For better parsing
pip install lxml

🎯 Usage

# Basic search
python3 search.py "your query"

# With caching
python3 search.py --cache "your query"

# Force specific method
python3 search.py --method oxylabs "your query"

🔧 Configuration

Create .env file:

# Google API (optional)
GOOGLE_API_KEY=your_key
GOOGLE_CSE_ID=your_cx

# Cache settings
CACHE_TTL_HOURS=24
MAX_CACHE_SIZE_MB=100

# Rate limiting
MAX_REQUESTS_PER_MINUTE=10

📈 Performance Features

• Query deduplication: Same query = cached result
• Result compression: Store only essential data
• Batch processing: Multiple queries in single API call
• Smart retry: Exponential backoff on failures
• Result validation: Filter out low-quality results

💰 Cost Optimization

Free Methods First

1. OpenClaw tools (no cost)
2. Free APIs (DuckDuckGo, Brave)
3. Google API (100 free/day)

Cache Strategy

• Hot queries: Keep in memory
• Warm queries: SQLite cache
• Cold queries: Fresh fetch

Bandwidth Saving

• Compress responses
• Store only text (no HTML)
• Pagination support

🛡️ Reliability

• Multiple fallbacks: 4+ search methods
• Automatic failover: If one fails, try next
• Health checks: Monitor API status
• Graceful degradation: Maintain service during outages

📊 Monitoring

Built-in metrics:

• Success rate per method
• Average response time
• Cache hit ratio
• Cost per query (estimated)

Example Output

{
  "query": "OpenClaw documentation",
  "method": "oxylabs",
  "cost_estimate": 0.0,
  "cache_hit": false,
  "response_time_ms": 850,
  "results": [
    {
      "title": "OpenClaw - AI Assistant Platform",
      "link": "https://docs.openclaw.ai",
      "snippet": "Official documentation...",
      "relevance_score": 0.92
    }
  ]
}

🎯 Use Cases

1. Research assistant: Fast, cached searches
2. Monitoring: Regular queries with caching
3. Batch processing: Multiple queries efficiently
4. Cost-sensitive apps: Maximize free tier usage

⚠️ Best Practices

1. Enable caching for repeated queries
2. Monitor usage to stay within free tiers
3. Use batch mode for multiple searches
4. Set reasonable TTL based on query type
5. Respect rate limits of all services