SerpBase 的 device 与 location：让搜索结果站在目标市场（附免费地名查询）

同一个关键词，在北京搜和在慕尼黑搜，结果可以完全不同。排名数据如果不说清「站在哪看」，就没有可比性。SerpBase 用 device 和 location 两个参数控制视角，配错一个，整批数据的方向就偏了。

这篇把两个参数和配套的免费地名查询讲清楚。

device：三档，默认是手机

device 接受三个值：

• mobile（默认）：手机布局
• pc：桌面布局
• default：等同 mobile

手机和桌面不是「同一份结果换个皮肤」——知识面板、模块位置、甚至部分结果都会不同。做排名监控时，同一批词必须固定同一个 device，否则今天手机、明天桌面，曲线会莫名其妙地跳。

location：要的是 canonical name

location 不是随便写个城市名，它要 Google 的规范地名（canonical name），格式像这样：

Munich,Bavaria,Germany

两个硬规则：

免费查规范地名

不用猜，有个免费接口：

curl "https://api.serpbase.dev/google/locations?q=munich&country_code=de&limit=2" \\
-H "X-API-Key: $SERP_BASE_API_KEY"

返回：

{
"status": 0,
"locations": [
{
"canonical_name": "Munich,Bavaria,Germany",
"name": "Munich",
"country_code": "DE",
"target_type": "City"
}
]
}

这个接口 0 credits，每分钟 60 次。参数：q（必填，匹配地名或规范名）、country_code（ISO 两位码，强烈建议带上——Paris 在法国和美国德州都有）、limit（1 到 100，默认 20）。

完整流程：先查地名，再搜索

import os
import requests

KEY = os.environ["SERP_BASE_API_KEY"]
BASE = "https://api.serpbase.dev"
HEAD = {"X-API-Key": KEY}

def canonical_location(city: str, country: str) –> str:
data = requests.get(f"{BASE}/google/locations", headers=HEAD,
params={"q": city, "country_code": country, "limit": 1},
timeout=(5, 30)).json()
if data.get("status") != 0 or not data.get("locations"):
raise ValueError(f"地名未找到: {city}, {country}")
return data["locations"][0]["canonical_name"]

loc = canonical_location("munich", "de")

data = requests.post(f"{BASE}/google/search", headers=HEAD, timeout=(5, 30), json={
"q": "crossfit software",
"gl": "de",
"hl": "de",
"device": "mobile", # location 只在 mobile 生效
"location": loc,
}).json()

print(data.get("status"), len(data.get("organic", [])))

三件套要一致

gl（国家）、hl（语言）、location（城市）是配套的：

gl=de 配 hl=en 也能跑，但返回的是德语市场里的英文结果——除非你就是要这个，否则别这么配。

五个坑

坑 1：用 pc 配 location。 被忽略，等于没传。要做地域定位，必须 mobile。

坑 2：地名不在列表。 静默忽略，不报错。每次都校验返回的 locations 是否为空。

坑 3：gl 和 location 国家不一致。 gl=us 配 Munich,Bavaria,Germany，结果会互相打架。三件套一起定。

坑 4：以为 location 保证代理出口。 文档明确：locale 参数不保证每个地区都有代理出口。它影响的是查询上下文，不是网络出口。

坑 5：不记录参数。 排名数据不带 device/location，三个月后没人能解释「为什么这天的数据不一样」。

小结

视角三件套：device 固定（mobile 或 pc）、location 用 canonical name、gl/hl 与市场一致；地名用免费的 /google/locations 查，一次 0 credits。做多市场监控时，这套参数比任何分析技巧都重要——数据先可比，分析才有意义。

参数与地名列表以 SerpBase 文档 为准。你们监控时固定 device 吗？评论区聊聊。