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

shopping-expert