Google 应用数据支持的地区列表

GET /v3/app_data/google/locations

本接口用于获取 Google 应用数据 API 支持的地区列表。支持按国家筛选地区，并返回地区名称、上级地区、国家 ISO 代码及地区类型等信息。

接口契约：

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

目前，Google 应用列表搜索接口和 Google Play 应用列表数据库支持美国，地区代码为 2840。

> 由于服务范围调整，俄罗斯和白俄罗斯的地区目前不再受支持。

计费说明

本接口不收取调用费用，响应中的 cost 通常为 0。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求说明

获取地区

GET /v3/app_data/google/locations

按国家筛选地区

GET /v3/app_data/google/locations/$country

，$country 为国家筛选值。国家名称空格或特殊字符时，应进行 URL 编码。

本接口无需请求体，也不使用 POST 请求。

请求示例

cURL

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

按国家筛选：

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

Python

import requests

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

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

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, response.text)

TypeScript

import axios from "axios";

axios
  .get("https://api.seermartech.cn/v3/app_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.response?.data || 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	GET 请求 URL 中传的参数
result	array	地区结果数组

data 字段

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

result 地区字段

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

location_name_parent 用于表示当前地区的上级行政区。例如：

{
  "location_code": 1006473,
  "location_name": "Altrincham,England,United Kingdom",
  "location_name_parent": "England,United Kingdom"
}

上述结果中的上级地区可能对应以下地区记录：

{
  "location_code": 20339,
  "location_name": "England,United Kingdom"
}

响应示例

{
  "version": "0.1.20220420",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.4267 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",
        "app_data",
        "google",
        "locations"
      ],
      "data": {
        "api": "app_data",
        "function": "locations",
        "se": "google"
      },
      "result": [
        {
          "location_code": 2840,
          "location_name": "United States",
          "location_name_parent": null,
          "country_iso_code": "US",
          "location_type": "Country"
        }
      ]
    }
  ]
}

状态码与错误处理

请优检查以下字段：

1. HTTP 响应状态码；
2. 顶层 status_code；
3. 任务级 tasks[].status_code；
4. 对应的 status_message。

当 status_code 为 20000 时，表示请求成功。发生错误时，应根据状态码和消息定位认证、参数或服务处理问题。

实用场景

• 获取支持地区单：在应用排名、应用商店数据分析系统中动态加载可用地区，提交不受支持的地区参数。
• 校验地区代码：在任务创建前验证地区代码和国家归属，减少因地区参数无效导致的任务失败。
• 构建国家筛选器：按国家获取 Google 应用数据支持的地区，为 SEO 或 ASO 分析后台提供分级地区选择。
• 维护地区维度数据：同步地区名称、上级地区和 ISO 国家代码，统一不同报表中的地理维度。
• 识别可用市场范围：根据地区类型和支持状态确定应用市场分析覆盖范围，制定区域化推广策略。