yelp-search

Yelp 搜索集成

在 Yelp 上搜索本地商家，查找服务、获取联系信息、查看评分并查询营业时间。

设置

1. Yelp API 密钥（必需）

1. 前往 https://www.yelp.com/developers
2. 创建账户或登录
3. 点击“Create App”并填写表单
4. 复制 API Key

添加到你的 .env 文件中：

YELP_API_KEY=your_api_key_here

2. 用于评论的 Browser-Use（可选）

仅当你想提取评论文本时才需要（速度较慢，每次请求约需 30-60 秒）。

安装依赖：

uv add browser-use playwright langchain-openai
uv run playwright install chromium

添加到 .env：

OPENAI_API_KEY=your_openai_key_here

注意：评论提取使用 browser-use 搜索 DuckDuckGo（因为 Yelp 会阻止直接抓取）。大多数情况下，API 返回的评分和 review_count 已足够。

脚本

所有脚本都位于 tools/yelp-search/scripts/，应使用 uv run python 运行。

search.py - 查找商家（主要工具）

uv run python tools/yelp-search/scripts/search.py "search term" --location "City, State"

选项：

标志	描述	示例
--location, -l	城市、地址或邮政编码	"San Francisco" 或 "94123"
--latitude/--longitude	GPS 坐标	--latitude 37.78 --longitude -122.41
--limit, -n	结果数量（默认：5）	-n 10
--sort-by	排序方式	rating、distance、review_count、best_match
--price	价格筛选（1-4）	--price 1,2，仅显示 $ 和 $$
--json	输出原始 JSON

示例：

# 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 - 获取营业时间和商家信息

uv run python tools/yelp-search/scripts/details.py "business-alias"

商家别名位于 Yelp URL 中（例如，the-laundry-corner-san-francisco）。

phone_search.py - 反向查询

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

get_reviews.py - 提取评论文本（速度较慢）

uv run python tools/yelp-search/scripts/get_reviews.py "Business Name" -l "City" -n 3

注意： 此脚本使用 browser-use，速度较慢（约需 30-60 秒）。Yelp 会阻止直接抓取，因此脚本会搜索 DuckDuckGo 上缓存的评论作为替代方案。

scrape_reviews.py - 直接抓取 Yelp 评论（替代方案）

uv run python tools/yelp-search/scripts/scrape_reviews.py "https://www.yelp.com/biz/business-alias" -n 5

需要 Browserbase 凭据：

BROWSERBASE_API_KEY=your_key_here
BROWSERBASE_PROJECT_ID=your_project_id

注意： 此脚本使用带代理的 Browserbase 绕过 Yelp 的 CAPTCHA。它比 get_reviews.py 更可靠，但需要 Browserbase 账户。

最佳实践

不查看评论文本时评估服务质量

API 提供的评分和 review_count 通常已足够：

评分	评论数量	解读
4.5+	50+	优秀，数据可靠
4.5+	<20	值得考虑，但数据有限
4.0-4.4	100+	良好，经营成熟
<4.0	任意	请谨慎选择

查找满足特定需求的服务

寻找有特定要求的服务（周末营业、取件/配送等）时：

1. 使用 --sort-by rating 搜索，获取最佳选项
2. 查看首选商家的详情，确认营业时间
3. 筛选出在你需要的时段营业的商家
4. 直接联系商家确认具体服务（取件、配送等），因为 Yelp 不一定会提供这些信息

搜索技巧

• 使用具体词语："laundry pickup"，而不只是 "laundry"
• 在某个地址附近搜索以获得准确距离：-l "123 Main St, City"
• 先按 rating 排序，再查看结果中的 distance
• 查看 review_count——评论很少但评分很高的商家可能不太可靠

响应数据

每条商家结果都包括：

• name - 商家名称
• phone - 电话号码（可用于发短信或拨打电话）
• rating - Yelp 评分（1-5 星）
• review_count - 评论数量
• price - 价格等级（$ 到 $$$$）
• location - 完整地址
• hours - 每天的营业时间（详见详情）
• distance - 与搜索地点的距离
• categories - 商家类别
• is_open_now - 当前营业/休息状态

限制

功能	状态	说明
商家搜索	✅ 可用	快速、可靠
商家详情	✅ 可用	包含营业时间
电话查询	✅ 可用	反向搜索
评论文本（API）	❌ 仅付费	需要企业版套餐
评论文本（抓取）	⚠️ 较慢	通过 DuckDuckGo 使用 browser-use 作为替代方案

• 免费 API 套餐：每天 500 次调用
• 每次请求最多返回 50 条结果
• API 不提供部分商家信息（自取／配送）——请直接联系商家