shopping-expert

Shopping Expert

Find and compare products online and locally with smart recommendations.

Quick Start

Find products online:

uv run {baseDir}/scripts/shop.py "coffee maker" \
  --budget medium \
  --max-results 5

Search with budget constraint:

uv run {baseDir}/scripts/shop.py "running shoes" \
  --budget "$100" \
  --preferences "Nike, cushioned, waterproof"

Find local stores:

uv run {baseDir}/scripts/shop.py "Bio Gemüse" \
  --mode local \
  --location "Hamburg, Germany"

Hybrid search (online + local):

uv run {baseDir}/scripts/shop.py "Spiegelreflexkamera" \
  --mode hybrid \
  --location "München, Germany" \
  --budget high \
  --preferences "Canon, 4K Video"

Search US stores:

uv run {baseDir}/scripts/shop.py "running shoes" \
  --country us \
  --budget "$100"

Search Modes

• online: E-commerce sites (Amazon, Walmart, etc.) via Google Shopping
• local: Nearby stores via Google Places API
• hybrid: Both online and local results merged and ranked
• auto: Intelligent mode selection based on query (default)

Parameters

• query: Product search query (required)
• --mode: Search mode (online|local|hybrid|auto, default: auto)
• --budget: "low/medium/high" or "€X"/"$X" amount (default: medium)
• --location: Location for local/hybrid searches
• --preferences: Comma-separated (e.g., "brand:Sony, wireless, black")
• --max-results: Maximum products to return (default: 5, max: 20)
• --sort-by: Sort order (relevance|price-low|price-high|rating)
• --output: text|json (default: text)
• --country: Country code for search (default: de). Use "us" for US, "uk" for UK, etc.

Budget Levels

• low: Under €50
• medium: €50-€150
• high: Over €150
• exact: "€75", "€250" (or "$X" for US searches)

Output Format

Default (text): Markdown table with product details, ratings, availability, and buy links

JSON: Structured data with all product metadata, scores, and links

Scoring Algorithm

Products are ranked using weighted scoring:

• Price match (30%): Within budget range gets full points
• Rating (25%): Higher ratings score better
• Availability (20%): In stock > limited > out of stock
• Review count (15%): More reviews = more trustworthy
• Shipping/Distance (10%): Free shipping or nearby stores score higher
• Preference match (bonus): Keywords in product description

API Keys Required

• SERPAPI_API_KEY: Required for online shopping (all modes except local-only)
• GOOGLE_PLACES_API_KEY: Only required for local and hybrid modes

Limitations

• API limits: SerpAPI and Google Places have usage quotas
• Real-time data: Prices and availability may change
• Stock accuracy: Online availability reflects last API update
• Local inventory: Store stock not guaranteed via Places API

Error Handling

• Invalid query → Returns error with suggestions
• No results found → Relaxes filters and retries
• API failures → Retry with exponential backoff (3 attempts)
• Missing API keys → Clear error message with setup instructions