从 SerpApi 迁移

SerpApi 参数与返回字段到 SerpHubAPI 的对照表，改几行代码即可切换。

SerpHubAPI 沿用你熟悉的参数名（q、gl、hl、num），大多数 SerpApi 集成只需改 URL、鉴权请求头和几个字段名就能迁过来。

快速切换

之前（SerpApi）：

import requests

r = requests.get("https://serpapi.com/search", params={
    "engine": "google",
    "q": "coffee",
    "gl": "us",
    "hl": "en",
    "num": 10,
    "api_key": SERPAPI_KEY,
})
for item in r.json().get("organic_results", []):
    print(item["position"], item["title"], item["link"])

之后（SerpHubAPI）：

import requests

r = requests.post("https://api.serphubapi.com/v1/search",
    headers={"X-API-Key": SERPHUBAPI_KEY},          # shapi_xxxxxxxx
    json={
        "engine": "google",
        "q": "coffee",
        "gl": "us",
        "hl": "en",
        "num": 10,
    })
for item in r.json()["results"].get("organic", []):
    print(item["position"], item["title"], item["link"])

参数对照

SerpApi	SerpHubAPI	说明
`GET https://serpapi.com/search`	`POST https://api.serphubapi.com/v1/search`	用 JSON 请求体代替查询字符串
`api_key`（查询参数）	`X-API-Key` 请求头（或 `Authorization: Bearer`）	Key 不出现在 URL 中
`q`	`q`	相同。SerpApi 的 Yandex 用 `text`，我们所有引擎统一用 `q`
`engine=google`	`engine=google`，`type=web`
`engine=bing` / `engine=yandex`	`engine=bing` / `engine=yandex`	网页结果
`engine=google_news` 或 `tbm=nws`	`engine=google`，`type=news`
`engine=google_images` 或 `tbm=isch`	`engine=google`，`type=images`
`engine=google_videos` 或 `tbm=vid`	`engine=google`，`type=videos`
`engine=google_shopping` 或 `tbm=shop`	`engine=google`，`type=shopping`
`engine=google_maps`	`engine=google`，`type=maps`	结果在 `results.places`
`engine=google_scholar`	`engine=google`，`type=scholar`
`engine=google_autocomplete`	`engine=google`，`type=autocomplete`	结果在 `results.suggestions`
`gl`	`gl`	相同
`hl`	`hl`	相同
`num`	`num`	1–100
`start`（偏移量）	`page`（从 1 开始）	`page = start / num + 1`
`tbs=qdr:d` / `qdr:w` / `qdr:m` / `qdr:y`	`time_range=day` / `week` / `month` / `year`	其他 `tbs` 取值无对应
`no_cache=true`	`mode=live`（默认）
默认（允许返回缓存）	`mode=cache_first`	半价；命中缓存免费
`output=html`	—	需要文本渲染时用 `format=markdown`
`location`、`uule`、`google_domain`、`device`	—	不支持，请用 `gl` / `hl`
`GET /searches/{id}.json`	`GET /v1/searches/{id}`	存档保留 30 天
`GET /account.json`	`GET /v1/account`

返回字段对照

SerpApi	SerpHubAPI
`search_metadata.id`	`meta.id`
`search_metadata.status`	`meta.status`
`search_parameters`	`params`
`organic_results`	`results.organic`
`news_results`	`results.news`
`images_results`	`results.images`（`original` → `image`）
`video_results`	`results.videos`
`shopping_results`	`results.shopping`（`source` → `merchant`）
`local_results`	`results.places`（`title` → `name`）
`related_questions`	`results.people_also_ask`
`related_searches[].query`	`results.related_searches[]`（纯字符串）
`knowledge_graph`	`results.knowledge_graph`
`error`（字符串）	`error.code` + `error.message`

结构差异

	SerpApi	SerpHubAPI
请求方式	`GET` + 查询字符串	`POST` + JSON 请求体
鉴权	查询参数 `api_key`	请求头 `X-API-Key` 或 `Authorization: Bearer`
选择引擎	每个引擎、每个垂类一个 `engine` 值	`engine` + `type`；`engine=auto` 由我们选择并自动切换
返回结构	各引擎不同	所有引擎统一一套结构
单次费用	响应中不体现	每个响应都有 `meta.credits_charged`
计费方式	月度订阅	预付积分；充值余额永不过期；空结果免费
网页正文	不在搜索调用内	搜索时加 `include_content`，或用 `/v1/fetch`
输出格式	JSON 或 HTML	JSON 或 Markdown（`format=markdown`）
错误	`error` 字符串	`{"error": {"code", "message"}}`，错误码稳定

迁移清单

在 /dashboard/keys 创建 Key。
改为 POST + JSON + X-API-Key。
把 engine=google_* / tbm 换成 type。
把 start 换成 page。
重命名返回字段（organic_results → results.organic 等）。
按 error.code 处理错误——见错误码。
抽几个查询对比结果，确认无误后切换流量。