serpapi-web-search

你可以使用 search（通过 MCP）或 serpapi（通过 CLI）。此文件可帮助你选择合适的引擎、提取正确的响应键，并避免常见错误。

身份验证检查 — 如果收到 401 或之前未使用过 serpapi，请先执行此操作：

# Check if already authenticated:
serpapi account 2>&1 | head -1
# If "Active" → you're good. If not:
serpapi login            # interactive — stores key persistently
# Or set env: export SERPAPI_KEY=<key from serpapi.com/dashboard>

如果 serpapi 不在 PATH 中：使用 brew install serpapi/tap/serpapi-cli 安装。 如果没有 MCP 工具或 CLI：使用带有 api_key=${SERPAPI_KEY} 参数的 curl（见下文）。

调用

search(params={"engine": "google_light", "q": "<query>", "num": 20}, mode="compact")

mode="compact" 会省略元数据 — 结果相同，约少 200 个 token。 默认 num=20。简单查询使用 num=10，单项事实核验使用 num=3。 结果为空 ≠ 出错。在状态码为 200 时，organic_results 可能不存在 — 请扩大查询范围或切换引擎。

CLI 备用方案（serpapi-cli）：

serpapi search engine=google_light q="query" num=20

有关 --fields/--jq 过滤：rules/examples.md。 有关 SDK（Python/JS/Go/Ruby/PHP/Java/.NET）：rules/sdks.md。 有关 curl：curl -G "https://serpapi.com/search.json" --data-urlencode "q=..." --data-urlencode "engine=google_light" --data-urlencode "api_key=${SERPAPI_KEY}"

引擎选择

根据意图选择。优先使用 _light 变体（速度更快、成本更低、JSON 更简洁）。

意图	引擎	结果键	关键字段
一般网页搜索（默认）	google_light	organic_results	.title、.link、.snippet
知识图谱 / 精选摘要	google	organic_results + 多项	.knowledge_graph、.answer_box
新闻	google_news_light	news_results	.title、.link、.date
图片	google_images_light	images_results	.original、.thumbnail
购物 / 价格	google_shopping_light	shopping_results	.title、.price、.source
学术论文	google_scholar	organic_results	.title、.inline_links.cited_by.total
本地商家（列表）	google_maps	local_results	.title、.phone、.address、.rating、.reviews
本地商家（单个）	google_maps	place_results	.title、.phone、.address、.rating、.reviews
地点评价	google_maps_reviews	reviews	.rating、.snippet、.date
视频	youtube	video_results	.title、.link、.views、.length
股票 / 股票代码	google_finance	summary	.price、.exchange、.currency
航班	google_flights	best_flights	.flights[].airline、.price、.total_duration
酒店	google_hotels	properties	.name、.rate_per_night.extracted_lowest、.total_rate.extracted_lowest、.overall_rating
职位	google_jobs	jobs_results	.title、.company_name、.location
App Store（iOS）	apple_app_store	organic_results	.title、.rating[0].rating、.rating[0].count、.developer.name
其他网页搜索	bing、duckduckgo	organic_results	.title、.link、.snippet
SerpApi 自有索引（alpha）	search_index	organic_results	.title、.link、.snippet

全部 130 多种引擎：rules/ENGINES.md · 在线：serpapi.com/search-engine-apis

注意事项

• 购物搜索 = 第三方经销商价格。 要查询特定零售商的价格，请使用 google_light 配合 site:（例如，q="MacBook Air M4 site:apple.com"）。Google Shopping 汇总的是商品源数据，价格可能与零售商自家网站上的价格不一致（例如，Target 的促销价格可能有延迟）。

• Maps 返回 place_results 或 local_results——具名商家 → place_results；类别搜索 → local_results。务必检查这两个键。

• Finance 返回 summary，而非 organic_results。 Flights（best_flights）和 Hotels（properties）也一样。

• Scholar 的引用次数位于 .organic_results[0].inline_links.cited_by.total，而非顶层字段。使用 --jq '.organic_results[0].inline_links.cited_by.total' 提取。

• Maps 的评价数位于 .place_results.reviews（整数）或 .local_results[].reviews。评分位于 .rating。

• Flights 需要指定参数，而非 q。使用 departure_id=JFK arrival_id=LAX outbound_date=2026-07-10 type=2（type 2 = 单程）。

• Hotels 需要日期——q="hotels in Kyoto" check_in_date=2026-07-20 check_out_date=2026-07-22 adults=2。价格位于 .properties[].rate_per_night.extracted_lowest（每晚）或 .total_rate.extracted_lowest（整个住宿期间）。按价格排序：sort_by=8。

• Apple App Store 使用 term，而非 q。评分为嵌套字段：.organic_results[0].rating[0].rating（浮点数，例如 4.78）。

• 非标准查询参数：

  Engine	参数（非 q）
  youtube	search_query
  amazon	k
  ebay	_nkw
  walmart	query
  google_maps_reviews	data_id
  google_flights	departure_id + arrival_id + outbound_date
  google_hotels	q + check_in_date + check_out_date + adults
  apple_app_store	term（非 q）

参数

大多数任务只需 engine、q 和 num。相关时再添加：

参数	用途
gl	国家代码（us、uk、de）。默认值为 us。
hl	语言（en、es、fr）。会影响排名。
location	城市字符串（"Austin, Texas"）。会覆盖 gl。
tbs	时间：qdr:d（天）、qdr:w（周）、qdr:m（月）、qdr:y（年）。
start	分页偏移量。若存在 serpapi_pagination.next，优先使用。
no_cache	"true" = 实时抓取（消耗 1 个额度）。

完整参考：rules/parameters.md · 地点：serpapi.com/locations-api

组合使用

研究时并行发起多个搜索，而非依次执行：

serpapi search engine=google_finance q="AAPL:NASDAQ" &
serpapi search engine=google_news_light q="Apple earnings" &
serpapi search engine=google_light q="AAPL analyst consensus" num=5 &
wait

常见的精确数据提取方式（可直接复制粘贴）：

# Exact citation count
serpapi search engine=google_scholar q="paper title" --jq '.organic_results[0].inline_links.cited_by.total'

# Business phone + rating + reviews
serpapi search engine=google_maps q="Business Name City" --jq '.place_results | {phone, rating, reviews}'

# Live flight price
serpapi search engine=google_flights departure_id=JFK arrival_id=LAX outbound_date=2026-07-10 type=2 --jq '.best_flights[0] | {price, airline: .flights[0].airline}'

# Shopping prices by retailer
serpapi search engine=google_shopping_light q="Product Name" --jq '[.shopping_results[:5] | .[] | {title, price, source}]'

逐步优化： 精确短语 → 去掉引号 → 添加 tbs=qdr:y → 切换引擎。

两步获取评价： google_maps q="business" → 获取 data_id → google_maps_reviews data_id=<id>。

交叉核对： 在 google_light 和 bing 上使用相同查询——结果一致 → 可信度高。

即时提取。 每次搜索后，将 {title, link, snippet} 提取到工作笔记中。不要依赖原始结果在上下文压缩后仍然保留。

更多用法：rules/use-cases.md

错误

代码	含义	解决方法
400	缺少 q 或 engine	添加必需参数。
401	API 密钥无效	运行 serpapi login，或设置 SERPAPI_KEY=<key from serpapi.com/dashboard>。不要使用相同密钥重试。
429	配额已用尽	切换到 _light，减少 num，并查看 dashboard。

如果收到 401：密钥错误或缺失。不要反复重试——先修正环境变量。 计费：只有成功的搜索才会计费。相同查询和参数可免费获取 1 小时内缓存的结果。

参考链接

• serpapi.com/search-api — 完整 API 文档
• serpapi.com/search-engine-apis — 所有引擎
• serpapi.com/pricing — 额度与套餐
• github.com/serpapi — SDK、CLI、MCP 服务