SERP WP 地点列表

GET /v3/serp/seznam/locations

接口方法与路径：

GET /v3/serp/wp/locations
GET /v3/serp/wp/locations/{country}

该接口用于获取 SERP WP 数据源支持的地理位置列表。可通过国家 ISO 代码筛选指定国家或地区的地点数据。

调用此接口不收费；扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

> 俄罗斯和白俄罗斯的地点目前不受支持。

请求参数

路径参数

参数	类型	填	说明
country	string	否	国家 ISO 代码，用于筛选指定国家的地点列表。例如：us。

请求示例

获取支持的地点：

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

获取美国地点列表：

curl --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/us"

response = requests.get(
    url,
    headers={
        "Authorization": "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json"
    },
    timeout=30
)

response.raise_for_status()
result = response.json()

# 输出返回的地点列表
print(result)

TypeScript 示例

import axios from "axios";

async function getLocations() {
  const response = await axios.get(
    "https://api.seermartech.cn/v3/serp/wp/locations/us",
    {
      headers: {
        Authorization: "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json"
      }
    }
  );

  // 输出接口返回结果
  console.log(response.data);
}

getLocations().catch((error) => {
  console.error(error.response?.data || error.message);
});

响应说明

接口返回 JSON 数据，顶层 tasks 数组。每个任务对象请求状态、请求参数及地点列表结果。

顶层字段

字段	类型	说明
version	string	当前 API 版本。
status_code	integer	局状态码。20000 表示请求成功。错误码说明请参考错误码文档。
status_message	string	局状态说明。
time	string	请求执行耗时，单位为秒。
cost	float	平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_count	integer	tasks 数组中的任务数量。
tasks_error	integer	执行失败的任务数量。
tasks	array	任务结果数组。

tasks 任务字段

字段	类型	说明
id	string	任务唯一标识符，采用 UUID 格式。
status_code	integer	任务状态码，取值通常在 10000 至 60000 范围。
status_message	string	任务状态说明。
time	string	任务执行耗时，单位为秒。
cost	float	平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_count	integer	result 数组中的结果数量。
path	array	本次请求对应的 URL 路径信息。
data	object	GET 请求 URL 中传的参数信息。
result	array	地点数据列表。

result 地点字段

字段	类型	说明
location_code	integer	地点代码，用于在后续 SERP 任务中指定目标地点。
location_name	string	地点完整名称。
location_code_parent	integer	上级地点的代码。
country_iso_code	string	地点所属国家或地区的 ISO 代码。
location_type	string	地点类型，例如 City、Country。

> 除中国可使用 Country 类型外，大多数国家支持 City 类型地点。请勿通过 location_code_parent 匹地点层级；多数国家不支持区域级或国家级搜索结果定位。

响应示例

{
  "version": "0.1.20220428",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.3936 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "12345678-1234-1234-1234-123456789abc",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.3936 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "serp",
        "wp",
        "locations",
        "us"
      ],
      "data": {
        "api": "serp",
        "function": "locations",
        "se": "wp",
        "country": "us"
      },
      "result": [
        {
          "location_code": 2840,
          "location_name": "United States",
          "location_code_parent": 0,
          "country_iso_code": "US",
          "location_type": "Country"
        }
      ]
    }
  ]
}

实用场景

• 查询可用地点代码：在创建 SERP 排名采集任务前获取合法的 location_code，因地点参数无效导致任务失败。
• 筛选目标国家城市：按国家 ISO 代码获取城市列表，为本地化 SEO、门店推广和区域监控建立地点。
• 构建多城市排名监控：批量读取重点城市的地点代码，自动生成同一在不同城市的搜索结果监控任务。
• 校验客户投放区域：将客户提供的国家或城市名称与接口地点数据进行匹，统一地域命名和定位编码。
• 维护地点数据字：定期同步支持的地点及层级信息，为 SEO 报表、竞品区域分析和自动化任务系统提供标准化基础数据。