SERP / Seznam / 地域列表

接口说明

该接口用于获取 Seznam SERP 可用的地域列表。你可以获取地域，也可以通过国家 ISO 代码按国家筛选地域。

本接口不收费，响应中的 cost 通常为 0。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

注意：俄罗斯和白俄罗斯的所有地域当前在平台范围均不再支持。

请求地址

• GET https://api.seermartech.cn/v3/serp/wp/locations
• GET https://api.seermartech.cn/v3/serp/wp/locations/$country

路径参数

字段名	类型	说明
country	string	可选。国家 ISO 代码，用于按国家筛选地域列表。示例：us

返回结果

接口返回 JSON 数据，顶层 tasks 数组，每个任务中地域列表结果。

顶层字段

字段名	类型	说明
version	string	当前 API 版本
status_code	integer	通用状态码，完整列表见 /v3/appendix/errors
status_message	string	通用状态信息，完整列表见 /v3/appendix/errors
time	string	执行耗时，单位秒
cost	float	本次请求总费用，单位 USD
tasks_count	integer	tasks 数组中的任务数量
tasks_error	integer	返回错误的任务数量
tasks	array	任务数组

tasks[] 字段

字段名	类型	说明
id	string	任务唯一标识，UUID 格式
status_code	integer	任务状态码，范围通常为 10000-60000，完整列表见 /v3/appendix/errors
status_message	string	任务状态信息
time	string	任务执行耗时，单位秒
cost	float	任务费用，单位 USD
result_count	integer	result 数组中的数量
path	array	URL 路径
data	object	GET 请求 URL 中传的参数
result	array	返回的地域列表

result[] 字段

字段名	类型	说明
location_code	integer	地域编码
location_name	string	地域完整名称
location_code_parent	integer	上级地域编码
country_iso_code	string	地域所属国家的 ISO 代码
location_type	string	地域类型

说明：原文中 location_code_parent、City、Region、Country 以及 Baidu 的说明与当前页面主题存在混杂，使用时建议优依据当前接口返回数据结构进行处理，不要依赖 location_code_parent 推断层级。

认证方式

请求头统一使用 Bearer Token：

Authorization: Bearer smt_live_YOUR_KEY

请求示例

cURL

curl --location --request GET "https://api.seermartech.cn/v3/serp/wp/locations" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json"

按国家筛选：

curl --location --request GET "https://api.seermartech.cn/v3/serp/wp/locations/us" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json"

Python

import requests

url = "https://api.seermartech.cn/v3/serp/wp/locations"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
data = response.json

if data.get("status_code") == 20000:
 print(data)
else:
 print(f"error. Code: {data.get('status_code')} Message: {data.get('status_message')}")

TypeScript

import axios from "axios";

// 获取地域列表
axios({
 method: "get",
 url: "https://api.seermartech.cn/v3/serp/wp/locations",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
})
 .then(function (response) {
 // 输出返回结果
 console.log(response.data);
 })
 .catch(function (error) {
 console.error(error);
 });

响应示例

{
 "version": "0.1.20220428",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.3936 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "serp",
 "function": "locations",
 "se": "seznam"
 },
 "result": []
 }
 ]
}

状态码说明

状态码	说明
20000	请求成功
10000-60000	任务级状态码范围，含义见 /v3/appendix/errors

使用建议

• 在创建 Seznam SERP 查询任务前，调用本接口获取最新可用地域列表。
• 如需限制查询范围，建议通过国家 ISO 代码筛选，再从返回结果中选择对应地域编码。
• 地域支持范围可能变化，生产环境中建议定期同步地域数据。
• 由于部分原始示例存在搜索引擎和路径不一致的，集成时请以本页列出的请求地址为准。

实用场景

• 同步地域主数据：定期拉取 Seznam 可用地域列表，建立地域字，减少人工维护成本。
• 校验投放或抓取参数：在提交 SERP 查询前校验 location_code 是否有效，因地域参数错误导致任务失败。
• 按国家构建地域选择器：基于国家 ISO 代码筛选地域，为运营后台或客户前端提供更准确的地域下拉选择。
• 监控地域支持变更：定时比对历史地域列表，及时发现新增、下线或限制的地域，降低业务中断风险。
• 支持本地化 SEO 分析：为不同国家或城市维度的排名抓取任务预匹可用地域，提高本地搜索分析的准确性。