Google Ads Advertisers 地区列表

GET /v3/serp/google/ads_advertisers/locations

概述

用于获取 SERP API 中 google/ads_advertisers 支持的地区列表。调用本接口不会产生费用。

• 请求方式：GET
• 请求地址：https://api.seermartech.cn/v3/serp/google/ads_advertisers/locations
• 参考价：（扣费以响应头 X-SeerMarTech-Charge-CNY 为准）

注意：俄罗斯和白俄罗斯的所有地区目前在平台 API 的服务中均不再支持。

响应结构

接口返回 JSON 数据，顶层 tasks 数组，每个任务中对应结果。

顶层字段

字段名	类型	说明
version	string	API 当前版本
status_code	integer	通用状态码，完整列表见 /v3/appendix/errors
status_message	string	通用信息说明，完整列表见 /v3/appendix/errors
time	string	执行时间，单位秒
cost	float	所有任务总费用，单位 USD
tasks_count	integer	tasks 数组中的任务数量
tasks_error	integer	tasks 数组中返回错误的任务数量
tasks	array	任务数组

tasks[] 字段

字段名	类型	说明
id	string	任务唯一标识，UUID 格式
status_code	integer	任务状态码，范围通常为 10000-60000，完整列表见 /v3/appendix/errors
status_message	string	任务信息说明
time	string	任务执行时间，单位秒
cost	float	任务费用，单位 USD
result_count	integer	result 数组中的数量
path	array	URL 路径
data	object	GET 请求 URL 中传的参数
result	array	返回结果数组

result[] 字段

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

地区层级示例

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

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

if data.get("status_code") == 20000:
 print(data)
else:
 print(f"error. Code: {data.get('status_code')} Message: {data.get('status_message')}")

TypeScript

import axios from "axios";

axios({
 method: "get",
 url: "https://api.seermartech.cn/v3/serp/google/ads_advertisers/locations",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
}).then((response) => {
 // 返回结果
 console.log(response.data);
}).catch((error) => {
 console.error(error);
});

响应示例

{
 "version": "0.1.20241101",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0669 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "serp",
 "function": "locations",
 "se": "google",
 "se_type": "ads_advertisers"
 },
 "result": []
 }
 ]
}

状态码说明

• 顶层 status_code = 20000 表示请求成功。
• 各任务的 status_code 用于标识单个任务执行状态。
• 完整错误码与状态信息请参考：/v3/appendix/errors

使用说明

调用本接口后，可获得 google/ads_advertisers 维度下可用的地区列表。通常用于：

1. 拉取可用地区单；
2. 读取 location_code；
3. 在后续 SERP 广告主接口中传对应地区参数。

由于地区数据可能存在层级，建议同时保存：

• 当前地区编码 location_code
• 上级地区编码 location_code_parent
• 地区名称 location_name
• 国家代码 country_iso_code
• 地区类型 location_type

这样便于后续做国家、省州、城市、机场等不同层级的聚合与筛选。

实用场景

• 同步投放地区字：将可用 location_code 定期同步到系统，保证广告主 SERP 查询时使用有效地区参数。
• 校验地区：在提交广告监测任务前校验地区是否受支持，减少因无效地区导致的请求失败。
• 构建地区层级映射：基于 location_code_parent 建立国家、省州、城市等层级结构，便于多层级广告分析。
• 支持本地化广告研究：按国家、区域或机场等细粒度地区查询广告主展示，本地市场竞争调研。
• 标准化多系统地区编码：将外部营销系统中的地区名称映射到本接口标准编码，提升跨系统数据一致性。