客户端 API 迁移

在 2027 年前迁移基础 Google CSE 搜索

保留支持的 cse().list() 调用和 items 解析，修改 endpoint 与 key 来迁移第一页网页搜索，并明确 cx、分页和图片搜索的限制。

google-api-python-client — python diff
 from googleapiclient.discovery import build
 
 service = build('customsearch', 'v1',
-    developerKey='YOUR_GOOGLE_KEY',
+    developerKey='YOUR_SEARCH1API_KEY',
+    client_options={'api_endpoint': 'https://api.search1api.com/compat/google/'},
 )
 response = service.cse().list(q='hono workers', cx='YOUR_OLD_CX', num=5).execute()

什么时候适合迁移

Google Custom Search JSON API 已停止接受新客户，现有客户需要在 2027 年 1 月 1 日前完成迁移。Search1API 使用自己的 Google 引擎提供第一页网页搜索兼容端点，不调用即将停服的 CSE API。

原服务参考资料: Google Custom Search JSON API notice

可以保留什么

Google Python 客户端中支持的 cse().list() 调用。
items[].title、link、snippet 等结果字段的解析。
使用 Search1API key 的 key 查询参数鉴权，也可改用 Bearer 请求头。

切换前需要确认

仅支持第一页网页搜索：num 为 1–10，start 必须为 1。图片搜索和 SafeSearch 请求会报错。
cx 只是兼容占位，不加载 Google 保存的站点或排序规则，需要显式重建站点限制。
结果可能不同，不提供总结果数估计、pagemap 或 nextPage。被忽略的选项会列在 X-Search1API-Ignored 中。

迁移现有客户端

确认应用是否依赖分页、图片搜索或 cx 背后保存的配置。
创建 Search1API key 并修改 endpoint。Python SDK 的 base 必须以 /compat/google/ 结尾，保留末尾斜杠。
切换流量前，验证实际查询、显式站点限制和错误处理。

HTTP · first-page web search — bash
curl --get 'https://api.search1api.com/compat/google/customsearch/v1' \
  --data-urlencode 'q=hono workers' \
  --data-urlencode 'num=5' \
  -H "Authorization: Bearer $SEARCH1API_API_KEY"

示例与兼容技术文档保持一致。切换生产流量前，请用自己的查询验证过滤条件和结果处理。

客户端示例:google-api-python-client / HTTP clients查看兼容技术文档

搜索使用 Search1API 积分，计入账户原有速率限制。读取页面全文或同时选择多个引擎可能增加费用，请查看各协议的计费说明。

查看定价

迁移常见问题

替换 cx 就能导入原搜索引擎吗？

不能。cx 可以保留在支持的客户端调用里，但不会导入 Google 保存的配置。单个站点使用 siteSearch，多站点可使用原生 Search API 的 include_sites 和 exclude_sites。

可以继续使用 Google Python SDK 吗？

文档中列出的基础调用可以。google-api-python-client 2.201.0 已通过本地 api_endpoint 覆盖、结果解析和 HttpError 处理测试。其他框架封装可能需要单独配置 endpoint。

嵌入网页的 Google Search Element 也能迁移吗？

这里迁移的是 Custom Search JSON API，不替换 Google 嵌入式 JavaScript Search Element 或它的站内搜索界面。