Apple 应用数据支持地区列表

通过调用本接口，可以获取 App Data API 中 Apple 数据源当前支持的地区列表。

如需完整地区单，可下载官方提供的 CSV 文件（更新时间：2026-04-06）： https://cdn.本平台.com/v3/locations/locations_app_data_apple_2026_04_06.csv

注意：

1. 当前 /v3/app_data/apple/app_listings/search/live/ 以及 /v3/databases/app_store/listings/ 支持 United States，地区代码为 2840。
2. 俄罗斯与白俄罗斯地区目前在平台 API 的所有服务中均不再支持。

接口说明

• 请求方式：GET
• 接口地址：https://api.seermartech.cn/v3/app_data/apple/locations
• 计费：
• 参考价：约 ¥0.0000 / 次
• 扣费：以响应中的 cost 字段为准

接口返回 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	任务状态信息，可参考 /v3/appendix-errors/
time	string	任务执行耗时，单位秒
cost	float	当前任务费用，单位 USD
result_count	integer	result 数组中的数量
path	array	URL 路径
data	object	GET 请求 URL 中传的参数
result	array	地区结果数组

tasks[].result[] 字段

字段	类型	说明
location_code	integer	地区代码
location_name	string	地区称
location_name_parent	string | null	上级地区名称
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_name_parent 对应的上级地区可能是：

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

但对于 Apple App Data API，当前支持国家级地区，因此该字段始终为 null。

请求示例

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)
print(response.json)

TypeScript

import axios from "axios";

axios({
 method: "get",
 url: "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);
 });

响应示例

{
 "version": "0.1.20220420",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.4267 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1234 sec.",
 "cost": 0,
 "result_count": 1,
 "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"
 }
 ]
 }
 ]
}

状态码说明

• 顶层 status_code 表示整个请求的处理状态
• tasks[].status_code 表示单个任务的处理状态
• 常见成功状态为 20000
• 完整错误码与状态信息可参考 /v3/appendix/errors

使用建议

• 在发起 Apple 应用数据查询前，调用本接口确认可用地区，传无效 location_code
• 若你要使用 /v3/app_data/apple/app_listings/search/live/ 或 /v3/databases/app_store/listings/，目前应使用 2840
• 可定期拉取并缓存地区列表，用于前端下拉选项、参数校验和任务构建

实用场景

• 校验投放地区参数：在发起 Apple 应用检索或榜单查询前，验证 location_code 是否可用，减少无效请求与参数错误。
• 构建地区选择器：将本接口返回的国家列表同步到后台或前端，生成 App Store 数据查询的地区下拉菜单。
• 限制业务范围：根据当前支持地区动态约束运营或分析师的查询范围，选到平台暂不支持的市场。
• 维护本地地区字：定期同步 location_code、国家名称和 ISO 代码，方便与报表、国家维表和数据仓库做映射。
• 预检查美国市场任务：在调用支持美国的接口前，确认使用 2840，保证应用列表检索与库表查询可以正常执行。