SERP 地点列表

接口概述

该接口用于获取 SERP 支持的地点列表，适用于设置任务时选择地域参数。

支持以下请求方式：

• GET /v3/serp/wp/locations
• GET /v3/serp/wp/locations/$country

说明：

• /v3/serp/wp/locations：返回可用地点
• /v3/serp/wp/locations/$country：按国家筛选地点列表，$country 为国家 ISO 代码，例如 us

参考价：，不计费。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

注意事项

• 俄罗斯和白俄罗斯的所有地点当前均不再受支持。
• 返回结果中的地点可用于后续 SERP 任务的地域定向。
• 除 WordPress 搜索场景外，平台 API 还为搜索引擎维护独立地点列表；如需完整地点数据文件，可联系平台获取或参考文档。

请求参数

该接口为 GET 请求，无请求体。

路径参数

字段名	类型	说明
country	string	可选。国家 ISO 代码，用于按国家过滤地点列表。例如：us

响应结构

接口返回 JSON 数据，顶层 tasks 数组。

顶层字段

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

状态码和状态信息的完整列表可参考 /v3/appendix/errors。

tasks[] 字段

字段名	类型	说明
id	string	任务唯一标识，UUID 格式
status_code	integer	任务状态码，范围通常为 10000-60000
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": 9041134,
 "location_name": "Vienna International Airport,Lower Austria,Austria",
 "location_code_parent": 20044
}

说明：

• location_code 表示当前地点编码
• location_code_parent 表示上级地点编码
• 若 location_code_parent = 20044，则该上级地点可能对应：

{
 "location_code": 20044,
 "location_name": "Lower Austria,Austria"
}

location_type 示例：

• "Country"
• "State"

请求示例

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)
result = response.json

print(result)

按国家筛选：

import requests

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

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

print(result)

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((response) => {
 // 输出结果数据
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

按国家筛选：

import axios from "axios";

const country = "us";

axios({
 method: "get",
 url: `https://api.seermartech.cn/v3/serp/wp/locations/${country}`,
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
})
 .then((response) => {
 // 输出结果数据
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

响应示例

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

错误码说明

该接口使用统一响应状态机制：

• 顶层 status_code：表示整个请求的执行状态
• tasks[].status_code：表示单个任务的执行状态

常见成功状态：

状态码	说明
20000	请求成功

更多错误码与说明请参考 /v3/appendix/errors。

使用说明

当你需要为 SERP 任务设置地点时，建议按以下流程使用本接口：

1. 调用 /v3/serp/wp/locations 获取地点列表，或通过国家代码缩小范围
2. 从返回结果中选取合适的 location_code
3. 在后续 SERP 任务请求中传相应地点参数，实现地域定向采集

如果你的业务只某个国家，优使用带国家参数的路径，可减少无数据处理量。

实用场景

• 筛选投放地区：按国家获取可用地点编码，为排名采集或页面抓取任务精确地域，提升本地化 SEO 分析准确性。
• 构建地点映射表：批量拉取地点列表，建立 location_code 与业务后台地区名称的映射，便于任务自动化下发。
• 限定国家范围：使用 /v3/serp/wp/locations/$country 获取目标国家地点，减少数据洗成本，加快区域项目部署。
• 定位父子地域层级：利用 location_code_parent 识别州、省、城市等上下级，支持区域聚合统计与分层分析。
• 校验任务参数：在正式提交 SERP 采集前校验地点是否受支持，因无效地域代码导致任务失败。