提交 Google Play 应用榜单任务

接口说明

该接口用于提交一个应用榜单采集任务，返回指定 Google Play 榜单中的移动应用列表。结果会根据以下维度返回：

榜单集合 app_collection
语言参数 language_name 或 language_code
地区参数 location_name 或 location_code

接口路径：

POST https://api.seermartech.cn/v3/app_data/google/app_list/task_post

你可以通过任务 id 轮询获取结果；如果在创建任务时设置了 postback_url 或 pingback_url，本平台也可以在任务完成后主动通知你的服务端。

计费说明

该接口按两部分计费：

创建任务本身
返回结果数量（按每 100 条结果计费）

例如，若设置 "depth": 101，则会按 200 条结果计费。

深度计费建议：

系统按每 100 条结果为一个计费单位处理
建议将 depth 设置为 100 的倍数
depth过 100 时，如果平台返回 100 条结果，将产生额外扣费

扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求方式

所有 POST 数据使用 UTF-8 编码的 JSON 格式提交，请求体为 JSON 数组：

json

[
 {
 "app_collection": "topselling_free",
 "location_code": 2840,
 "language_code": "en",
 "depth": 100
 }
]

请求限制

每分钟最多可发起 2000 次 API 调用
每次 POST 最多可 100 个任务
若单次请求中任务数 100，出部分会返回错误 40006

任务回调说明

你可以通过以下两种方式接收任务完成通知：

pingback_url：任务完成后，本平台向你指定的 URL 发起 GET 请求
postback_url：任务完成后，本平台向你指定的 URL 发起 POST 请求，并将结果以 gzip 压缩格式发送

注意事项：

若你的服务端在 10 秒未响应，请求会因时中断 -时后，任务会 /v3/app_data/google/app_list/tasks_ready 列表，可改为主动拉取
postback_url / pingback_url 中可使用 $id 和 $tag 变量，发送时会被替换为真实值
URL 中的特殊字符会被 URL 编码，例如 # 会编码为 %23

请求参数

字段名	类型	说明
`app_collection`	string	填。要采集的 Google Play 榜单集合。可选值：`featured`、`topselling_paid`、`topselling_free`、`topselling_new_free`、`topselling_new_paid`、`topgrossing`、`movers_shakers`。注意：当选择 `featured` 时，不能同时使用 `app_category`。
`location_name`	string	搜索引擎地区完整名称。未指定 `location_code` 时填。使用该字段时，无需再传 `location_code`。示例：`West Los Angeles,California,United States`。地区列表可通过 `/v3/app_data/google/locations` 获取。
`location_code`	integer	搜索引擎地区代码。未指定 `location_name` 时填。使用该字段时，无需再传 `location_name`。示例：`9061121`。地区列表可通过 `/v3/app_data/google/locations` 获取。
`language_name`	string	搜索引擎语言完整名称。未指定 `language_code` 时填。使用该字段时，无需再传 `language_code`。示例：`English`。语言列表可通过 `/v3/app_data/google/languages` 获取。
`language_code`	string	搜索引擎语言代码。未指定 `language_name` 时填。使用该字段时，无需再传 `language_name`。示例：`en`。语言列表可通过 `/v3/app_data/google/languages` 获取。
`priority`	integer	任务优级，可选。可选值：`1`（普通优级，默认）、`2`（高优级）。高优级任务会产生额外费用，扣费以响应头 `X-SeerMarTech-Charge-CNY` 为准。
`depth`	integer	采集深度，可选。表示返回的应用数量。默认值：`100`；最大值：`200`。建议设置为 100 的倍数。系统按每 100 条结果计费。
`app_category`	string	应用分类，可选。用于按 Google Play 分类过滤结果。示例：`family`。分类列表可通过 `/v3/app_data/google/categories` 获取。注意：当 `app_collection` 为 `featured` 时不可使用该参数。
`age_rating`	string	年龄分级过滤，可选。可选值：`ages_up_to_5`、`ages_6_8`、`ages_9_12`。默认返回所有年龄段应用。注意：该参数在同时设置 `"category": "family"` 时生效。
`tag`	string	用户自定义任务标识，可选。最长 255 个字符。可用于在结果中识别和匹任务，设置后会原样出现在响应的 `data` 对象中。
`postback_url`	string	任务结果回传地址，可选。任务完成后，本平台会向该地址发送 POST 请求，并附带 gzip 压缩结果。示例：`http://your-server.com/postbackscript?id=$id`、`http://your-server.com/postbackscript?id=$id&tag=$tag`。
`postback_data`	string	`postback_url` 的返回数据类型。指定 `postback_url` 时填。可选值：`advanced`、`html`。
`pingback_url`	string	任务完成通知地址，可选。任务完成后，本平台会向该地址发送 GET 请求。示例：`http://your-server.com/pingscript?id=$id`、`http://your-server.com/pingscript?id=$id&tag=$tag`。

响应结构

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

顶层字段

字段名	类型	说明
`version`	string	当前 API 版本
`status_code`	integer	接口通用状态码
`status_message`	string	接口通用状态信息
`time`	string	执行耗时，单位秒
`cost`	float	本次请求总费用，单位 USD
`tasks_count`	integer	`tasks` 数组中的任务数
`tasks_error`	integer	返回错误的任务数
`tasks`	array	任务结果数组

`tasks` 数组中的字段

字段名	类型	说明
`id`	string	任务唯一标识，UUID 格式
`status_code`	integer	任务状态码，范围通常为 `10000-60000`
`status_message`	string	任务状态信息
`time`	string	该任务执行耗时，单位秒
`cost`	float	该任务费用，单位 USD
`result_count`	integer	`result` 数组中的数
`path`	array	URL 路径
`data`	object	与提交时传参数一致的任务数据
`result`	array / null	结果数组。对于任务提交接口，该值通常为 `null`

建议对 status_code 和任务级错误做完整异常处理。状态码说明可参考 /v3/appendix/errors。

请求示例

cURL

bash

curl --location --request POST "https://api.seermartech.cn/v3/app_data/google/app_list/task_post" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "app_collection": "topselling_free",
 "location_code": 2840,
 "language_code": "en",
 "depth": 100
 }
]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/app_data/google/app_list/task_post"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

# 请求体为 JSON 数组
data = [
 {
 "app_collection": "topselling_free",
 "location_code": 2840,
 "language_code": "en",
 "depth": 100
 },
 {
 "app_collection": "topselling_free",
 "location_code": 2840,
 "language_code": "en",
 "depth": 100,
 "priority": 2,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 "app_collection": "topselling_free",
 "location_code": 2840,
 "language_code": "en",
 "postback_data": "html",
 "postback_url": "https://your-server.com/postbackscript"
 }
]

response = requests.post(url, headers=headers, json=data)
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

typescript

import axios from "axios";

const postArray = [
 {
 app_collection: "topselling_free",
 location_code: 2840,
 language_code: "en",
 depth: 100
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/app_data/google/app_list/task_post",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 data: postArray
})
 .then((response) => {
 // 返回任务提交结果
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

响应示例

json

{
 "version": "0.1.20220422",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0818 sec.",
 "cost": 0.0012,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "app_data",
 "function": "app_list",
 "se": "google",
 "app_collection": "topselling_free",
 "location_code": 2840,
 "language_code": "en",
 "depth": 100,
 "app_category": "shopping",
 "se_type": "app_list",
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 }
 ]
}

状态与错误处理

顶层 status_code = 20000 表示请求成功受理
单个任务也有各自的 status_code，应分别检查
若单次 POST含 100 个任务，出部分会返回 40006
若回调地址 10 秒无响应，任务不会丢失，而会转 /v3/app_data/google/app_list/tasks_ready

使用建议

优使用 location_code 和 language_code，名称匹歧义。
depth 建议设置为 100 或 200，更符合平台处理方式。
若需要按儿童分级筛选，确保 app_category 使用 family。
若业务需要异步批量采集，建议结合 tag、pingback_url 或 postback_url 使用。

实用场景

监控热门榜单变化：定期抓取 topselling_free、topgrossing 等榜单，追踪头部应用排名变化，应用市场竞争分析。
筛选细分类机会：按 app_category 提取特定品类榜单，快速识别教育、购物、家庭等垂类中的增长机会。
分析区域发行策略：结合 location_code 与 language_code 对比不同国家/语言环境下的榜单差异，支持本地化投放与出海决策。
追踪儿童应用市场：使用 family 分类与 age_rating 组合筛选儿童适龄应用，家长产品、教育产品或广告合规研究。
构建异步采集流水线：通过 tag、pingback_url、postback_url 组织批量任务回传，提升大规模榜单监控与数据库效率。

提交 Google Play 应用榜单任务 ​

接口说明 ​

计费说明 ​

请求方式 ​

请求限制 ​

任务回调说明 ​

请求参数 ​

响应结构 ​

顶层字段 ​

tasks 数组中的字段 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

状态与错误处理 ​

使用建议 ​

实用场景 ​