Keywords Data 的 WP 地区列表

本接口用于获取 Keywords Data 服务中可用的 Google 地理定位地区列表。支持以下 GET 请求路径：

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

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

本接口采用 Google 地理定位规则，可使用 Google 支持的大多数地区类型；不支持 Okrug 类型。邮政编码可用于创建任务，但对应任务通常不会返回数据。

> 目前，俄罗斯和白俄罗斯的所有地区均不受支持。

调用完整地区列表接口可获取可用地区；调用带 $country 的路径可按国家筛选地区。$country 应替换为目标国家标识。

计费

本接口不收费，响应中的 cost 通常为 0。

请求示例

cURL

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

Python

import requests

url = "https://api.seermartech.cn/v3/keywords_data/wp/locations"

headers = {
    "Authorization": "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json",
}

# 获取 Keywords Data 支持的 WP 地区
response = requests.get(url, headers=headers, timeout=30)
result = response.json()

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        f"请求失败：{result.get('status_code')} - "
        f"{result.get('status_message')}"
    )

TypeScript

import axios from "axios";

// 获取 Keywords Data 支持的 WP 地区
const response = await axios.get(
  "https://api.seermartech.cn/v3/keywords_data/wp/locations",
  {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
  }
);

const result = response.data;

if (result.status_code === 20000) {
  console.log(result);
} else {
  console.error(`请求失败：${result.status_code} - ${result.status_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	地区结果数组。

data 字段

字段	类型	说明
api	string	API 分类，固定为 keywords_data。
function	string	调用功能，固定为 locations。
se	string	数据源标识，本接口为 wp。

result 地区字段

字段	类型	说明
location_code	integer	地区代码，用于后续数据任务中的地区定位。
location_name	string	地区完整名称。
location_code_parent	integer	上级地区代码。
country_iso_code	string	地区所属国家的 ISO 国家代码。
location_type	string	地区类型，与 Google 地理定位目标类型对应。

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

{
  "location_code": 9041134,
  "location_name": "Vienna International Airport,Lower Austria,Austria",
  "location_code_parent": 20044
}

，location_code_parent: 20044 对应的上级地区可能为：

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

响应示例

{
  "version": "3.20191128",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.4305 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.4305 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "keywords_data",
        "wp",
        "locations"
      ],
      "data": {
        "api": "keywords_data",
        "function": "locations",
        "se": "wp"
      },
      "result": [
        {
          "location_code": 20044,
          "location_name": "Lower Austria,Austria",
          "location_code_parent": null,
          "country_iso_code": "AT",
          "location_type": "State"
        }
      ]
    }
  ]
}

实用场景

• 构建查询地区选择器：同步可用地区代码与名称，为 SEO 平台、广告分析或运营后台提供标准化地区下拉选项。
• 校验任务的地区参数：在提交搜索量、排名或趋势查询前验证 location_code，减少因无效地区导致的任务失败。
• 按国家维护本地化词库：通过国家筛选接口获取目标市场的地区列表，为多国家、多语言库建立统一的地域维度。
• 分析地区层级覆盖范围：利用 location_code_parent 建立国家、州省、城市及细分地区之间的层级，支持区域 SEO 数据汇总。
• 匹业务服务区域：将企业门店、物流覆盖区或服务城市映射至平台地区代码，生成面向指定地区的监测任务。