app_data/apple/locations

GET /v3/app_data/apple/locations

本接口使用 GET 方法获取 Apple App Data API 支持的地点列表。

请求路径：

GET https://api.seermartech.cn/v3/app_data/apple/locations

本接口不收取调用费用。接口返回 JSON 数据 tasks 数组及可用地点信息。也可获取完整的地点 CSV 文件，当前版本更新时间为 2026-09-01。

> 注意：目前 Apple App Listings Search 接口和 App Store Listings Database 接口支持美国，地点代码为 2840。

地点支持范围

目前 Apple App Data API 支持国家级地点，因此：

• location_type 通常为国家类型；
• location_name_parent 始终为 null；
• 俄罗斯和白俄罗斯的地点不再受支持。

请求参数

该接口为 GET 请求，无需请求参数。

计费说明

本接口调用，接口响应中的 cost 为 0。

如平台后续调整计费策略，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

响应字段

顶层字段

字段	类型	说明
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	GET 请求中使用的接口参数
result	array	地点信息数组

tasks.data 字段

字段	类型	说明
api	string	API 模块名称，固定为 app_data
function	string	接口名称，固定为 locations
se	string	搜索平台名称，固定为 apple

tasks.result 地点字段

字段	类型	说明
location_code	integer	地点代码
location_name	string	地点完整名称
location_name_parent	string / null	上级地点名称。Apple App Data API 当前支持国家级地点，因此始终为 null
country_iso_code	string	地点对应的 ISO 国家代码
location_type	string	地点类型

请求示例

cURL

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

Python

import requests

url = "https://api.seermartech.cn/v3/app_data/apple/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/app_data/apple/locations", {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
  })
  .then((response) => {
    // 响应数据
    console.log(response.data);
  })
  .catch((error) => {
    console.error("请求失败：", error.response?.data || error.message);
  });

响应示例

{
  "version": "0.1.20220420",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.4267 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.1234 sec.",
      "cost": 0,
      "result_count": 2,
      "path": [
        "v3",
        "app_data",
        "apple",
        "locations"
      ],
      "data": {
        "api": "app_data",
        "function": "locations",
        "se": "apple"
      },
      "result": [
        {
          "location_code": 2840,
          "location_name": "United States",
          "location_name_parent": null,
          "country_iso_code": "US",
          "location_type": "country"
        },
        {
          "location_code": 826,
          "location_name": "United Kingdom",
          "location_name_parent": null,
          "country_iso_code": "GB",
          "location_type": "country"
        }
      ]
    }
  ]
}

状态码

状态码	说明
20000	请求成功
状态码	请求或任务处理失败，原因请结合 status_message 判断

实用场景

• 获取支持的国家地点代码，为 Apple 应用排名、或商店数据查询生成合法的地域参数。
• 校验业务系统中的地点，因传不受支持的地点代码导致后续 API 请求失败。
• 构建 Apple 应用市场覆盖范围单，帮助 SEO 或 ASO 团队规划不同国家的应用本地化策略。
• 同步地点基础数据，在数据仓库或报表系统中统一地点名称、国家代码和地点类型。
• 限制查询范围为当前支持的国家，确保应用市场分析任务与 Apple App Data API 的能力保持一致。