yelp-search

What this skill does

# Yelp Search Integration

Search for local businesses on Yelp to find services, get contact information, check ratings, and retrieve hours of operation.

## Setup

### 1. Yelp API Key (Required)

1. Go to https://www.yelp.com/developers
2. Create an account or sign in
3. Click "Create App" and fill out the form
4. Copy your API Key

Add to your `.env` file:
```
YELP_API_KEY=your_api_key_here
```

### 2. Browser-Use for Reviews (Optional)

Only needed if you want to extract review text (slow, ~30-60s per request).

**Install dependencies:**
```bash
uv add browser-use playwright langchain-openai
uv run playwright install chromium
```

**Add to `.env`:**
```
OPENAI_API_KEY=your_openai_key_here
```

Note: Review extraction uses browser-use to search DuckDuckGo (since Yelp blocks direct scraping). For most use cases, the rating + review_count from the API is sufficient.

## Scripts

All scripts are in `tools/yelp-search/scripts/` and should be run with `uv run python`.

### search.py - Find Businesses (Primary Tool)
```bash
uv run python tools/yelp-search/scripts/search.py "search term" --location "City, State"
```

**Options:**
| Flag | Description | Example |
|------|-------------|---------|
| `--location`, `-l` | City, address, or zip | `"San Francisco"` or `"94123"` |
| `--latitude/--longitude` | GPS coordinates | `--latitude 37.78 --longitude -122.41` |
| `--limit`, `-n` | Number of results (default: 5) | `-n 10` |
| `--sort-by` | Sort order | `rating`, `distance`, `review_count`, `best_match` |
| `--price` | Price filter (1-4) | `--price 1,2` for $ and $$ only |
| `--json` | Output raw JSON | |

**Examples:**
```bash
# Find top-rated dog groomers
uv run python tools/yelp-search/scripts/search.py "dog groomer" -l "San Francisco" --sort-by rating

# Find cheap restaurants nearby
uv run python tools/yelp-search/scripts/search.py "restaurants" -l "94123" --price 1,2 --sort-by distance

# Search near a specific address
uv run python tools/yelp-search/scripts/search.py "laundry pickup" -l "123 Main St, San Francisco"
```

### details.py - Get Business Hours & Info
```bash
uv run python tools/yelp-search/scripts/details.py "business-alias"
```

The business alias is in the Yelp URL (e.g., `the-laundry-corner-san-francisco`).

### phone_search.py - Reverse Lookup
```bash
uv run python tools/yelp-search/scripts/phone_search.py "+14155551234"
```

### get_reviews.py - Extract Review Text (Slow)
```bash
uv run python tools/yelp-search/scripts/get_reviews.py "Business Name" -l "City" -n 3
```

**Note:** Uses browser-use which is slow (~30-60s). Yelp blocks direct scraping, so it searches DuckDuckGo for cached reviews as a workaround.

### scrape_reviews.py - Direct Yelp Scraping (Alternative)
```bash
uv run python tools/yelp-search/scripts/scrape_reviews.py "https://www.yelp.com/biz/business-alias" -n 5
```

**Requires Browserbase credentials:**
```
BROWSERBASE_API_KEY=your_key_here
BROWSERBASE_PROJECT_ID=your_project_id
```

**Note:** Uses Browserbase with proxies to bypass Yelp's CAPTCHA. More reliable than `get_reviews.py` but requires a Browserbase account.

## Best Practices

### Evaluating Quality Without Review Text
The API provides rating + review_count which is usually sufficient:

| Rating | Review Count | Interpretation |
|--------|--------------|----------------|
| 4.5+ | 50+ | Excellent, reliable data |
| 4.5+ | <20 | Promising but limited data |
| 4.0-4.4 | 100+ | Good, well-established |
| <4.0 | any | Proceed with caution |

### Finding Services with Specific Needs
When looking for services with specific requirements (weekend hours, pickup/delivery, etc.):

1. **Search** with `--sort-by rating` to get best options
2. **Get details** on top candidates to check hours
3. **Filter** for businesses open when you need them
4. **Contact directly** to confirm specific services (pickup, delivery, etc.) since Yelp doesn't always have this info

### Search Tips
- Use specific terms: `"laundry pickup"` not just `"laundry"`
- Search near an address for accurate distance: `-l "123 Main St, City"`
- Sort by `rating` first, then check `distance` on results
- Check `review_count` - high ratings with few reviews may be unreliable

## Response Data

Each business result includes:
- **name** - Business name
- **phone** - Phone number (use for texting/calling)
- **rating** - Yelp rating (1-5 stars)
- **review_count** - Number of reviews
- **price** - Price level ($ to $$$$)
- **location** - Full address
- **hours** - Operating hours by day (in details)
- **distance** - Distance from search location
- **categories** - Business categories
- **is_open_now** - Current open/closed status

## Limitations

| Feature | Status | Notes |
|---------|--------|-------|
| Business search | ✅ Works | Fast, reliable |
| Business details | ✅ Works | Includes hours |
| Phone lookup | ✅ Works | Reverse search |
| Review text (API) | ❌ Paid only | Requires enterprise tier |
| Review text (scraping) | ⚠️ Slow | browser-use workaround via DuckDuckGo |

- Free API tier: 500 calls/day
- Results limited to 50 per request
- Some business info (pickup/delivery) not in API - contact directly