SerpBase 多城市搜索工程实录:/google/locations、location 与 uule 怎么配合
2026 年 11 月 20 日早上十点,黑五前的多城市本地搜索巡检脚本刚上线就出了怪事:我给美国 8 个重点城市跑了一轮同词查询,结果 8 份快照里的 local_results 几乎一模一样。回头查日志,HTTP 状态码全是 200,SerpBase 返回的业务 status 也全是 0,每条实扣 1 credit,接口本身完全正常。
翻了半小时请求体才发现是我自己把两个参数用拧了:脚本里顺手加了 "device": "desktop",同时把 "Austin, TX" 这种非标准缩写直接塞进了 location 字段。对照 SerpBase 文档 一查,location 必须传 Google 的 canonical name,未匹配的地名会被静默忽略而不会直接报错;更重要的是,location 只在 mobile(默认布局)下生效。下面把排查和重构成「地名解析 + 缓存 + uule 编码」这套后端链路的实验记录摊开讲。
一、先用 0 credit 的 /google/locations 把地名标准化
很多做多城市 SEO 或本地商家巡检的后端代码,习惯自己维护一份 "城市, 州" 的字符串表。这个做法在谷歌本地化体系里很容易漂移——比如纽约的标准写法是 New York,New York,United States,伦敦是 London,England,United Kingdom,中间少个行政层级或拼成简写都可能命中不了。
SerpBase 提供了一个免费的辅助端点 GET https://api.serpbase.dev/google/locations(0 credits,单账号 60 次/分),专门用来把模糊城市词解析成 Google 官方的 canonical_name、country_code 和 target_type。既然查询免费,工程上最好的做法是在启动期或首次遇到新城市时查一次,把映射落进本地缓存表,避免每次搜索前重复查。
import os, requests
API_KEY = os.environ["SERPBASE_API_KEY"]
HEADERS = {"X-API-Key": API_KEY}
def resolve_canonical_location(city_query: str, country_code: str = "US") -> str:
resp = requests.get(
"https://api.serpbase.dev/google/locations",
headers=HEADERS,
params={"q": city_query, "country_code": country_code, "limit": 5},
timeout=15,
)
resp.raise_for_status()
items = resp.json().get("locations", [])
# 优先挑 target_type 为 City 的条目,避免命中同名机场或郡县
for item in items:
if item.get("target_type") == "City":
return item["canonical_name"]
if not items:
raise ValueError(f"未查到标准地名: {city_query} ({country_code})")
return items[0]["canonical_name"]
print(resolve_canonical_location("Austin", "US"))
这里有个小细节我在第二轮测试才留意到:搜 "Austin" 时返回列表里可能混有县(County)或同名小镇,所以按 target_type == "City" 过滤一遍,能少掉很多莫名其妙的地理偏移。
二、location 与 uule 的分工边界
把 canonical_name 拿到手之后,接下来决定在 POST /google/search 里传 location 还是传 uule。我按官方文档规则在两种布局下各跑了一组对照:
| 维度 | location 参数 |
uule 参数 |
|---|---|---|
| 入参形态 | Google canonical_name 字符串 |
"w "/"w+" + base64 编码的 canonical name,或 "a "/"a+" + base64 坐标 |
| 生效设备 | 仅 device="mobile"(默认)生效 |
支持带入搜索上下文,适合需要显式编码地名或坐标的场景 |
| 传错时行为 | 未匹配会被忽略,仍按 gl/hl 返回 |
需严格按规范编码,否则无法解析出目标位置 |
| 额外成本 | 0(含在 1 credit 搜索请求内) |
0(含在 1 credit 搜索请求内) |
需要提前说清楚的是,无论配 gl、hl、location 还是 uule,官方文档都注明 locale 并不保证每个细分地区都有独立代理出口,但对于欧美主流大城市的本地商家包和区域结果,配合标准 canonical_name 的命中区分度已经足够做日常巡检。
按规范给 canonical_name 生成 uule 只需要几行标准库代码,不用引第三方包:
import base64
# Google UULE 长度前缀表(对应 canonical_name 的字节长度)
_UULE_KEYS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"
def encode_uule_from_canonical(canonical_name: str) -> str:
raw = canonical_name.encode("utf-8")
if len(raw) >= len(_UULE_KEYS):
raise ValueError("canonical_name 过长,超出标准长度前缀表")
prefix = _UULE_KEYS[len(raw)]
b64 = base64.b64encode(raw).decode("ascii")
return f"w+CAIQICI{prefix}{b64}"
print(encode_uule_from_canonical("Austin,Texas,United States"))
工程落地时我把策略定得很死:移动端巡检(device="mobile")直接传 /google/locations 缓存下来的 location 字段,可读性好、日志里一眼能看懂;涉及需要显式透传地理编码或坐标的任务,统一走 encode_uule_from_canonical 生成 uule。
三、串起搜索、对账与 0c 链接还原的完整调用
多城市巡检跑起来之后,紧接着遇到第二个实际问题:organic 里部分结果的 source_url 会带 google.com/goto 包装,落库做域名聚合前得先还原成真实落地页。SerpBase 内置了免费的 Google Link Resolver(POST /google/resolve,0 credits,单账号 30 次/分,单次最多 50 条),刚好接在搜索请求后面做批处理,不额外花额度。
顺便把这次选型核对过的 SerpBase 核心事实留在这里备查:目录共 49 个端点(44 个当前可用),按端点固定 0–3 credits/请求;最低 $0.25/1k 起(Pro Monthly $100/400k),注册送 500 免费 credits 且不绑卡,标准预付包($10/20k 起)credits 不过期;计费口径为只为成功请求付费、执行后失败自动退款、超时事后结算且重试只计成功那次;另提供 27 个 engine 的 SerpApi 兼容端点(GET /google/serpapi/search.json),存量代码改 base URL 即可迁移。
下面是我最终放到定时任务里的核心调用函数,把业务 status 校验、X-SerpBase-Retryable 判定、credits_charged 对账和 /google/resolve 还原串在了一起:
import os, requests
API_KEY = os.environ["SERPBASE_API_KEY"]
HEADERS = {"X-API-Key": API_KEY, "Content-Type": "application/json"}
def run_localized_search(q: str, canonical_loc: str, gl: str = "us", hl: str = "en"):
resp = requests.post(
"https://api.serpbase.dev/google/search",
headers=HEADERS,
json={"q": q, "gl": gl, "hl": hl, "device": "mobile", "location": canonical_loc, "format": "json"},
timeout=30,
)
data = resp.json()
# 标准端点均为 HTTP 200,必须检查业务 status
if data["status"] != 0:
retryable = resp.headers.get("X-SerpBase-Retryable") == "true"
raise RuntimeError(f"search failed: status={data['status']} retryable={retryable} id={data['request_id']}")
organic = data.get("organic", [])
wrapped = [item["source_url"] for item in organic if "google.com/goto" in item.get("source_url", "")]
resolved = []
if wrapped:
r = requests.post(
"https://api.serpbase.dev/google/resolve",
headers=HEADERS,
json={"links": wrapped[:50]},
timeout=30,
).json()
resolved = r.get("resolved_links", [])
return {
"request_id": data["request_id"],
"credits_charged": data["credits_charged"], # 0=未扣费, null=结算中
"local_count": len(data.get("local_results", [])),
"organic_count": len(organic),
"resolved_count": len(resolved),
}
四、改完后跑 8 个城市的对照账单与下一步
把上面这套逻辑切上线重跑 8 个美国城市(每城 20 个黑五本地服务词,共 160 次搜索):地名解析走了 8 次 GET /google/locations(0 credits),搜索走了 160 次 POST /google/search(160 credits),跳转链清洗走了 4 批 POST /google/resolve(0 credits)。整轮跑完实扣 160 credits,按预付 Growth 包($50/125k,$0.40/1k)算约 $0.064,各城市的 local_results 商家列表终于和当地门店对上了号。
如果你也在做多城市 SERP 监控,先去 SerpBase 文档 拿 500 免费 credits 把 GET /google/locations 的城市表缓存下来,再检查一遍自己的请求体里有没有在桌面模式下误传 location。
透明度声明:文中端点路径、限流与价格均按
serpbase.dev2026-11-20 官网与文档口径核对;最新参数以官网文档为准。

浙公网安备 33010602011771号