5 分钟跑通:用 curl 调谷歌搜索 API

想验证一个数据想法,最省事的路径不是装 SDK、也不是先写脚本,而是在命令行里发一条请求,亲眼看到返回的 JSON 长什么样。这篇就干这一件事:用 curl 调通谷歌搜索 API,顺手把结果格式化、翻页、本地化都试一遍。整个过程不需要任何依赖,有 curl 就行。

第一条请求

export SERPBASE_API_KEY="你的 API Key"

curl -s -X POST https://api.serpbase.dev/google/search \\
-H "X-API-Key: $SERPBASE_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{"q": "coffee grinder review", "hl": "en", "gl": "us"}'

返回是一个 JSON 信封:status 为 0 表示成功,elapsed_ms 是耗时,credits_charged 是本次扣掉的点数(search 端点每次成功请求 1 credit),真正的结果在 organic 数组里——每条含 rank、title、link、snippet 等字段。

参数、字段与计费细节以 SerpBase 官方文档 为准;上面四个参数(q/hl/gl/page)是日常最常用的,device 仅搜索端点支持,可取 default/pc/mobile。

三条最常用的进阶命令

用 jq 只看自然结果的标题和链接:

curl -s -X POST https://api.serpbase.dev/google/search \\
-H "X-API-Key: $SERPBASE_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{"q": "coffee grinder review"}' \\
| jq -r '.organic[] | "\\(.rank)\\t\\(.title)\\t\\(.link)"'

翻页:第 2 页就是多传一个 page(from 1 起):

-d '{"q": "coffee grinder review", "page": 2}'

换市场:同一个词看日本区结果:

-d '{"q": "コーヒーミル おすすめ", "hl": "ja", "gl": "jp"}'

Windows 用户的两个坑

参数速查

顺带一提端点家族:/google/news、/google/videos 同样 1 credit,/google/images、/google/maps/search 是 2 credits——把 URL 换掉、结果数组名换掉(news/videos/images/places),curl 用法完全一样。

成本与下一步

跑通这套动作 1 credit 都用不到几次:100 次免费试用足够把每个端点各打几轮、把 jq 管道调顺手。真正的批量采集再交给脚本(定时任务、翻页去重这些前面写过),curl 的定位就是想法到手、30 秒验证。

报错先看信封里的 error 字段:1001 是 key 不对,1020 是余额不足,1029 是触发限流——退避几秒再试;完整的错误码表和重试策略,可以翻之前那篇报错排查手册。

FAQ

为什么不直接用 Postman? 也可以,但 curl 能进 CI、能贴进 README、能被别人原样复制执行。命令行里的可复现,比 GUI 里的一步步点击值钱。

返回结果太长,想存下来慢慢看? 末尾加 > result.json 即可;配合 jq 的 -S 还能排序键,两次请求 diff 起来更清楚。

hl 和 gl 到底影响什么? 语言和地区都会改变排序与本地化模块(比如地图包、购物结果),做市场对比时固定一个、动另一个,别两个一起换。

把这条命令存成 alias,下次想到任何"搜索结果里有没有 X"的问题,先敲一行再看要不要写代码。