从 Serper.dev 迁移

如果你在用 Serper.dev，迁移非常简单：两边都是 POST + JSON 请求体，核心参数一致。主要改动只有 URL、请求头名称，以及用 type 参数代替按路径区分垂类。

快速切换

之前（Serper.dev）：

curl -X POST https://google.serper.dev/search \
  -H "X-API-KEY: $SERPER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "coffee", "gl": "us", "hl": "en", "num": 10, "page": 2, "tbs": "qdr:w"}'

之后（SerpHubAPI）：

curl -X POST https://api.serphubapi.com/v1/search \
  -H "X-API-Key: $SERPHUBAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "coffee", "engine": "google", "gl": "us", "hl": "en", "num": 10, "page": 2, "time_range": "week"}'

Python 写法：

import os, httpx

# 之前：httpx.post("https://google.serper.dev/search", headers={"X-API-KEY": key}, json=body)
r = httpx.post(
    "https://api.serphubapi.com/v1/search",
    headers={"X-API-Key": os.environ["SERPHUBAPI_API_KEY"]},
    json={"q": "coffee", "engine": "google", "gl": "us", "hl": "en", "num": 10},
)
organic = r.json()["results"].get("organic", [])

端点对照

Serper.dev	SerpHubAPI
POST google.serper.dev/search	POST /v1/search，type=web
POST google.serper.dev/news	type=news
POST google.serper.dev/images	type=images
POST google.serper.dev/videos	type=videos
POST google.serper.dev/shopping	type=shopping
POST google.serper.dev/maps / /places	type=maps
POST google.serper.dev/scholar	type=scholar
POST google.serper.dev/autocomplete	type=autocomplete
POST scrape.serper.dev	POST /v1/fetch，或搜索时加 include_content
—	engine=bing / engine=yandex（网页）

基础地址统一为 https://api.serphubapi.com。

参数对照

Serper.dev	SerpHubAPI	说明
X-API-KEY 请求头	X-API-Key 请求头（或 Authorization: Bearer）	请求头名不区分大小写，实际只需换 Key 值
q	q	相同
gl	gl	相同
hl	hl	相同
num	num	1–100，条数多少价格不变
page	page	相同，从 1 开始
tbs=qdr:d	time_range=day
tbs=qdr:w	time_range=week
tbs=qdr:m	time_range=month
tbs=qdr:y	time_range=year
tbs=qdr:h、自定义日期范围	—	不支持
location	—	不支持，请用 gl / hl
autocorrect	—	不支持
—	engine	auto（默认）、google、bing、yandex
—	mode	live（默认）或 cache_first（半价，命中缓存免费）
—	include_content	同一次调用里抓取前 N 个网页的 Markdown 正文
—	format	json 或 markdown

返回字段对照

Serper.dev	SerpHubAPI
searchParameters	params
credits	meta.credits_charged（10 = 一次实时搜索）
organic	results.organic
news	results.news
images[].imageUrl / thumbnailUrl	results.images[].image / thumbnail
videos	results.videos
shopping[].source	results.shopping[].merchant
places[].title / ratingCount	results.places[].name / reviews
peopleAlsoAsk	results.people_also_ask
relatedSearches[].query	results.related_searches[]（纯字符串）
knowledgeGraph	results.knowledge_graph
suggestions[].value	results.suggestions[]（纯字符串）
—	meta.id——调用 ID，30 天内可通过 GET /v1/searches/{id} 回看

字段一律使用 snake_case。

结构差异

	Serper.dev	SerpHubAPI
引擎	Google	Google、Bing、Yandex（engine=auto 自动选择并切换）
选择垂类	每个垂类一个路径	一个端点，用 type 参数
返回结构	各垂类各自的字段，camelCase	统一结构，snake_case
调用 ID 与存档	—	meta.id，/v1/searches/{id} 存档 30 天
网页正文	单独的抓取端点	搜索时加 include_content，或用 /v1/fetch
面向 LLM 的输出	JSON	JSON 或 Markdown（format=markdown）
计费方式	预付积分包	预付积分；充值余额永不过期；失败、空结果、缓存命中均免费
错误	HTTP 状态码 + 消息	{"error": {"code", "message"}}，错误码稳定——见错误码

迁移清单

1. 在 /dashboard/keys 创建 Key。
2. 基础地址改为 https://api.serphubapi.com/v1/search，用 type 代替路径。
3. 把 tbs 换成 time_range。
4. 把 camelCase 返回字段改成 results 下对应的 snake_case 字段。
5. 从 meta.credits_charged 读取费用，代替 credits。
6. 抽几个查询对比结果，然后切换流量。