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)

• Go to https://www.yelp.com/developers

• Create an account or sign in

• Click "Create App" and fill out the form

• 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:

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)

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:

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

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

uv run python tools/yelp-search/scripts/phone_search.py "+14155551234"

get_reviews.py - Extract Review Text (Slow)

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)

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.):

• Search with --sort-by rating to get best options

• Get details on top candidates to check hours

• Filter for businesses open when you need them

• 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