Google Ads 广告主位置列表

GET /v3/serp/google/ads_advertisers/locations

接口说明

GET /v3/serp/google/ads_advertisers/locations

获取 SERP API 支持的 Google Ads 广告主位置列表国家、地区、城市及层级的位置信息。本接口无需请求体。

> 俄罗斯和白俄罗斯的所有位置目前均不再受支持。

计费说明

当前调用本接口不收取费用，接口响应中的 cost 通常为 0。

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

请求示例

cURL

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

Python

import requests

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

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

# 获取 Google Ads 广告主位置列表
response = requests.get(url, headers=headers)

if response.status_code == 200:
    result = response.json()
    if result.get("status_code") == 20000:
        print(result)
    else:
        print(
            "接口错误。错误码: %s，错误信息: %s"
            % (result.get("status_code"), result.get("status_message"))
        )
else:
    print("HTTP 请求失败：", response.status_code)

TypeScript

import axios from "axios";

axios
  .get(
    "https://api.seermartech.cn/v3/serp/google/ads_advertisers/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);
  });

响应结构

接口返回 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 数组中返回错误的任务数量
tasks	array	任务结果数组

任务字段

字段名	类型	说明
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	serp	API 模块
function	string	locations	当前功能名称
se	string	google	搜索引擎
se_type	string	ads_advertisers	搜索类型

result 位置字段

字段名	类型	说明
location_code	integer	位置编码
location_name	string	位置完整名称
location_code_parent	integer	上级位置编码
country_iso_code	string	位置所属国家或地区的 ISO 代码
location_type	string	位置类型

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": "0.1.20241101",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0669 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "5932f7a1-3b4e-4b31-9d39-6e8b6f0a1234",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0501 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "serp",
        "google",
        "ads_advertisers",
        "locations"
      ],
      "data": {
        "api": "serp",
        "function": "locations",
        "se": "google",
        "se_type": "ads_advertisers"
      },
      "result": [
        {
          "location_code": 9041134,
          "location_name": "Vienna International Airport,Lower Austria,Austria",
          "location_code_parent": 20044,
          "country_iso_code": "AT",
          "location_type": "airport"
        }
      ]
    }
  ]
}

状态判断

建议同时检查 HTTP 状态码和响应中的 status_code：

• HTTP 请求成功后，再判断顶层或任务级 status_code。
• status_code = 20000 表示请求成功。
• 当 tasks_error 大于 0 时，应逐一检查对应任务的 status_code 和 status_message。
• 发生错误时，可根据错误码附录定位认证、请求路径或服务处理问题。

实用场景

• 构建位置编码映射表：将位置名称、国家代码和层级编码统一保存，支持广告投放、SERP 监测及报表中的标准化地域筛选。
• 生成地域层级树：利用 location_code_parent 组织国家、地区、城市及细分位置的上下级，便于开展地域聚合分析。
• 校验广告投放地域参数：在提交 Google Ads 或 SERP 任务前验证位置编码是否有效，减少因地域参数错误导致的任务失败。
• 同步多语言位置名称：获取完整位置名称并结合国家 ISO 代码建立本地化地域字，支持化 SEO 项目的地域。
• 筛选可监测的目标市场： country_iso_code 和 location_type 过滤位置，快速整理不同国家或地区的排名监测范围。