商家搜索 API：Google Shopping 支持地区列表

接口说明

该接口用于获取 Merchant API 支持的 Google Shopping 地区列表。

注意：由于地区支持策略变更，俄罗斯和白俄罗斯的所有地区已不再受支持。

你可以通过本接口获取可用地区，也可以在请求路径中附加国家 ISO 代码查看某个国家下的地区列表。

• 获取地区： GET /v3/merchant/google/locations
• 按国家筛选： GET /v3/merchant/google/locations/$country

，$country 为国家 ISO 代码，例如 us。

计费说明

本接口调用。

• 参考价约 ¥0.0000 / 次
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

请求地址

GET https://api.seermartech.cn/v3/merchant/google/locations
GET https://api.seermartech.cn/v3/merchant/google/locations/$country

路径参数

字段名	类型	说明
country	string	可选。国家 ISO 代码；如需按国家筛选地区列表，请传该值。示例：us

响应结构

接口返回 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_name_parent	string	上级地区名称。例如：location_name = "Arkansas,United States"，location_name_parent = "United States"
country_iso_code	string	地区对应的国家 ISO 代码
location_type	string	地区类型

请求示例

cURL

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

Python

import requests

url = "https://api.seermartech.cn/v3/merchant/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(f'error. Code: {result.get("status_code")} Message: {result.get("status_message")}')

TypeScript

import axios from "axios";

// 获取 Google Shopping 支持地区列表
axios({
 method: "get",
 url: "https://api.seermartech.cn/v3/merchant/google/locations",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
})
 .then(function (response) {
 const result = response.data;
 console.log(result);
 })
 .catch(function (error) {
 console.log(error);
 });

按国家筛选示例

例如获取美国地区列表：

cURL

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

响应示例

{
 "version": "3.20191128",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.4305 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "merchant",
 "function": "locations",
 "se": "google"
 },
 "result": []
 }
 ]
}

错误码说明

• 顶层 status_code 表示整个请求的执行结果
• tasks[].status_code 表示单个任务的执行结果
• 完整错误码与提示信息请参考：/v3/appendix/errors

使用建议

• 在创建 Merchant 任务前，调用本接口确认目标地区是否受支持
• 如果你的业务面向某个国家，建议使用 /v3/merchant/google/locations/$country 降低结果集处理成本
• 地区支持范围可能发生变化，建议定期拉取最新列表并缓存到本地系统中

实用场景

• 校验投放国家：在创建 Google Shopping 采集任务前，验证目标国家和地区是否受支持，提交无效任务。
• 构建地区下拉选项：为运营后台或客户自助生成可选国家/地区列表，减少人工错误。
• 同步地区主数据：定期拉取支持地区并写本地数据库，保证商家分析系统中的地区维度与平台 API 保持一致。
• 过滤不可用市场：在批量创建多国家任务时，自动排除不支持地区，提升任务成功率和数据覆盖质量。
• 规范地区映射：基于 location_code、country_iso_code 和地区名称建立标准化映射，便于后续报表统计与多源数据。