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 5Search 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