用途
SerpApi Search 用于通过 SerpApi 的搜索接口执行网络搜索,可调用 100 多个搜索引擎,包括 Google、Bing、DuckDuckGo、YouTube、Amazon 等,返回结构化的 JSON 搜索结果。它适合需要快速获取网页、新闻、图片、购物、学术、本地地图或视频等信息的场景。
主要能力
- 支持多种搜索引擎与垂直搜索:通用网页、新闻、图片、购物、学术、本地/地图、视频、YouTube 等。
- 提供 Light 版本引擎(如 google_light、google_images_light、google_news_light、google_shopping_light、google_videos_light、duckduckgo_light),优化速度与成本,推荐默认使用。
- 完整版引擎(如 google、bing、duckduckgo、google_scholar、google_maps、youtube 等)可获取知识图谱、本地包、内嵌购物、精选摘要等更丰富信息。
- 支持分页(num、start)、国家/语言本地化(gl、hl)、精确地理位置(location)、时间过滤(tbs,如 qdr:d 过去一天、qdr:w 过去一周、qdr:m 过去一月)、安全搜索(safe)和强制刷新(no_cache)。
- 可作为原生工具直接调用,也可通过 HTTP 接口或 serpapi CLI 使用。
使用方式
- 设置 API 密钥:export SERPAPI_API_KEY="your-api-key-here"。
- 若环境中存在原生 serpapi_search 工具,可直接调用,并建议传入 mode="compact" 以去除冗余元数据,降低 token 消耗。示例(MCP 伪代码):serpapi_search(params={"engine": "google_light", "q": "query"}, mode="compact")。实际调用语法取决于代理运行时。
- 若无原生工具,可使用 HTTP 接口:GET https://serpapi.com/search.json,通过 --data-urlencode 传入参数。示例:curl -G "https://serpapi.com/search.json" --data-urlencode "q=coffee shops in Austin" --data-urlencode "engine=google_light" --data-urlencode "api_key=${SERPAPI_KEY}"。
- 或使用 serpapi CLI(安装:brew install serpapi/serpapi-cli/serpapi),示例:serpapi search engine=google_light q="coffee shops in Austin"。
核心参数:engine(必填,搜索引擎)、q(必填,查询词)、api_key(必填,API 密钥);可选 num(结果数量,多数引擎最大 100,默认 10)、start(分页偏移)、gl(国家代码,默认 us)、hl(语言代码,默认 en)、location(城市/地区,优先于 gl)、tbs(时间过滤)、safe(安全搜索级别 active 或 off)、no_cache(传 "true" 绕过缓存)。注意:youtube 引擎使用 search_query 代替 q,其他引擎使用 q。
适用场景
- 需要快速获取通用网页结果时,使用 google_light。
- 需要完整 Google 结果(含知识图谱、本地包)时,使用 google。
- 获取最新新闻用 google_news_light;图片搜索用 google_images_light;商品价格与库存用 google_shopping_light;学术论文、引用与 Tight 用 google_scholar;本地地点、评论与坐标用 google_maps;视频内容与元数据用 youtube 或 google_videos_light;替代结果用 bing;注重隐私用 duckduckgo。
- 需要按时间过滤(如过去一周)时,配合 tbs=qdr:w 使用。
- 需要地域本地化时,设置 gl 与 hl;需要精确定位城市时使用 location。
返回格式
所有引擎返回 JSON,包含 search_metadata、search_parameters 以及引擎特定的结果数组。不同引擎使用不同的顶层结果键:网页(google_light、google、bing、duckduckgo)为 organic_results;新闻为 news_results;图片为 images_results;购物为 shopping_results;职位为 jobs_results;地图为 local_results;视频为 video_results;YouTube 为 organic_results。可使用 serpapi_pagination.next 获取后续页面。
限制与错误
- 免费额度:每月 250 次搜索;付费方案见 serpapi.com/pricing。
- 401 Unauthorized:API 密钥缺失或无效,请检查仪表盘。
- 429 Rate Limit:达到月度限额,需升级方案。
- 400 Bad Request:缺少必填参数(如 q 或 engine)。
参考链接
完整文档、SerpApi Playground、API Dashboard、引擎目录等链接请见原始资料。