Google 数据位置列表

本接口使用 GET 方法，请求路径为：

/v3/keywords_data/google/locations

用于获取数据接口支持的 Google 地理位置列表。该接口为旧版数据接口，建议新项目优使用 Google Ads 数据接口。

> 说明：由于政策原因，俄罗斯和白俄罗斯境的位置目前不受本平台服务支持。

本接口使用 Google 地理位置定位体系。位置类型：

• Autonomous Community（自治区）
• Canton（州/县级行政区）
• City（城市）
• Congressional District（国会选区）
• Country（国家）
• County（县）
• Department（省/部门）
• Governorate（省级行政区）
• Municipality（自治市）
• Prefecture（专区）
• Province（省）
• Region（地区）
• State（州）
• Territory（领地）
• Union Territory（联邦属地）

请求信息

请求方法

GET

请求地址

https://api.seermartech.cn/v3/keywords_data/google/locations

请求参数

本接口无需请求参数，也无需请求体。

认证方式

在请求头中使用 Bearer Token：

Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

计费说明

本接口当前不收取调用费用。

扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

响应结构

接口返回 JSON 数据 tasks 数组及位置列表。

顶层字段

字段名	类型	说明
version	string	当前 API 版本
status_code	integer	请求级状态码
status_message	string	请求级状态信息
time	string	请求执行耗时，单位为秒
cost	float	平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_count	integer	tasks 数组中的任务数量
tasks_error	integer	tasks 数组中返回错误的任务数量
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	请求参数及接口信息
result	array	位置列表

data 字段

字段名	类型	说明
api	string	API 名称，固定为 keywords_data
function	string	接口名称，固定为 locations
se	string	搜索引擎名称，固定为 google

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"
}

请求示例

cURL

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

Python

import requests

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

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

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

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        "请求失败，状态码：%s，信息：%s"
        % (result.get("status_code"), result.get("status_message"))
    )

TypeScript

import axios from "axios";

axios
  .get("https://api.seermartech.cn/v3/keywords_data/google/locations", {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
  })
  .then((response) => {
    const result = response.data;

    if (result.status_code === 20000) {
      console.log(result);
    } else {
      console.error(
        `请求失败，状态码：${result.status_code}，信息：${result.status_message}`
      );
    }
  })
  .catch((error) => {
    console.error("请求异常：", error.message);
  });

成功响应示例

{
  "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.1200 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "keywords_data",
        "google",
        "locations"
      ],
      "data": {
        "api": "keywords_data",
        "function": "locations",
        "se": "google"
      },
      "result": [
        {
          "location_code": 9041134,
          "location_name": "Vienna International Airport,Lower Austria,Austria",
          "location_code_parent": 20044,
          "country_iso_code": "AT",
          "location_type": "Airport"
        }
      ]
    }
  ]
}

状态码

请求级和任务级状态码用于表示接口及任务执行结果。成功时通常返回：

20000

如需查看完整状态码及错误信息，请参考本平台错误码文档。

实用场景

• 获取可用地理位置代码，为搜索量、竞争度等数据请求准确的定位范围。
• 构建国家、地区与城市级位置选择器，支持 SEO 平台按层级筛选目标市场。
• 校验用户提交的位置名称，通过 location_code 和 location_name 建立稳定的位置映射。
• 识别位置上下级，按国家、省州、城市等层级聚合数据，便于区域市场对比。
• 同步 Google 地理位置字，定期更新位置数据库，减少因位置代码过期导致的数据请求失败。