SERP WP 地点列表

本接口用于获取 SERP WP 支持的地点列表。支持以下请求方式：

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

可通过国家/地区 ISO 代码筛选地点。例如，使用 us 获取美国地点列表。

计费

调用本接口不收费。

支持的地点数据

可获取以下搜索引擎支持的完整地点 CSV 列表（数据更新时间：2026-09-01）：

• Google
• Bing
• Yahoo
• YouTube

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

请求参数

country 为可选路径参数，用于按国家/地区筛选地点。

参数名	类型	填	说明
country	string	否	国家/地区 ISO 代码，例如：us。

请求示例

获取地点

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/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

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

if (!response.ok) {
  throw new Error(`请求失败：${response.status} ${response.statusText}`);
}

const result = await response.json();

// 输出接口返回的地点数据
console.log(result);

响应说明

接口返回 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	地理位置分类，例如 Country（国家）或 State（州/省）。

location_code_parent 用于表示地点的行政层级。例如，机场地点的上级地点可以是所在州、省或地区。

响应示例

{
  "version": "3.20191128",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.4305 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.4305 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"
        }
      ]
    }
  ]
}

状态与错误处理

• 顶层 status_code 表示整个请求的处理状态。
• tasks[].status_code 表示单个任务的处理状态。
• 当顶层状态码为 20000 且 tasks_error 为 0 时，通常表示请求已成功完成。
• 如任务状态码非成功状态，请结合 status_message 定位认证、请求路径、参数格式或服务可用性问题。

实用场景

• 匹目标地点：根据业务投放国家、州、省或城市查询对应 location_code，确保 SERP 任务使用准确的地域参数。
• 构建本地 SEO 监控范围：获取城市及上级行政区层级，批量建立门店、服务区域或竞品所在地的排名监控任务。
• 校验多地区任务：在提交批量 SERP 请求前验证地点代码与国家代码的归属，减少因地点参数错误导致的任务失败。
• 维护地域维度数据字：将地点代码、名称和类型同步至数据库，为报表筛选、地区聚合及数据分析提供标准化维度。
• 识别区域层级：利用 location_code_parent 城市、州省和国家，支持按行政区层级汇总可见度与排名数据。