提交 Google Play 应用搜索任务

POST /v3/app_data/google/app_searches/task_post

该接口用于创建 Google Play 应用搜索任务。创建任务后，本平台会根据指定的 keyword，结合 language 和 location 条件，抓取该下在 Google Play 中排名的应用结果。

接口说明

• 请求方式：POST
• 请求地址：https://api.seermartech.cn/v3/app_data/google/app_searches/task_post

你可以通过任务返回的唯一 id 后续获取结果；如果在创建任务时传 postback_url 或 pingback_url，本平台也可以在任务完成后主动回传或通知结果。

计费说明

该接口的费用由两部分组成：

• 创建任务本身的费用
• 返回结果数量对应的费用

应用搜索结果按每 30 条结果 为一个计费单。例如：

• depth: 30：按 30 条计费
• depth: 31：按 60 条计费

建议将 depth 设为 30 的倍数，以便更贴合平台处理方式。

由于原文未给出固定单价，本文不展示固定人民币参考价。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求格式与限制

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

[
 {
 "keyword": "vpn",
 "location_code": 2840,
 "language_code": "en",
 "depth": 30
 }
]

调用限制：

• 每分钟最多可提交 2000 次 API 调用
• 每次 POST 最多可 100 个任务
• 如果单次请求中任务数 100，出部分会返回错误 40006

结果获取方式

任务提交成功后，你可以通过以下方式获取结果：

1. 使用返回的任务 id 获取结果
2. 创建任务时指定 postback_url，任务完成后本平台会将结果以 gzip 压缩的 POST 请求发送到该地址
3. 创建任务时指定 pingback_url，任务完成后本平台会向该地址发送 GET 通知

注意事项：

• 如果你的回调服务在 10 秒未响应，请求会因时被中止 -时后，该任务会转 /v3/app_data/google/app_searches/tasks_ready 列表
• 实错误码和错误信息取决于你的服务端

---

请求参数

任务字段说明

字段名	类型	说明
keyword	string	填。搜索，最长 700 个字符。所有 %## 会被解码，字符 + 会被解码为空格。如需传递 %，请写为 %25；如需传递 +，请写为 %2B。
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。示例：English。可通过 /v3/app_data/google/languages 获取可用语言。
language_code	string	搜索语言代码。可选。使用该字段时无需再传 language_name。示例：en。可通过 /v3/app_data/google/languages 获取可用语言。
priority	integer	任务优级，可选。1 = 普通优级（默认），2 = 高优级。高优级会产生额外费用，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。
depth	integer	抓取深度，可选。表示希望返回的 Google Play 搜索结果数量。默认值：30；最大值：200。建议设置为 30 的倍数。每 30 条结果按一个计费单计算。
tag	string	自定义任务标识，可选，最大 255 个字符。可用于将任务与业务系统记录；提交后可在响应的 data 对象中看到该值。
postback_url	string	结果回传地址，可选。任务完成后，本平台会将结果以 gzip 压缩的 POST 请求发送到该地址。支持使用 $id 作为任务 ID 变量、$tag 作为 URL 编码后的标签变量。示例：http://your-server.com/postbackscript?id=$id 或 http://your-server.com/postbackscript?id=$id&tag=$tag。特殊字符会被 URL 编码，例如 # 会编码为 %23。
postback_data	string	postback_url 的返回数据类型。当指定 postback_url 时填。可选值：advanced、html。
pingback_url	string	任务完成通知地址，可选。任务完成后，本平台会向该地址发起 GET 请求。支持使用 $id 作为任务 ID 变量、$tag 作为 URL 编码后的标签变量。示例：http://your-server.com/pingscript?id=$id 或 http://your-server.com/pingscript?id=$id&tag=$tag。特殊字符会被 URL 编码，例如 # 会编码为 %23。

---

响应说明

接口返回 JSON 数据，根对象中 tasks 数组，表示本次提交的任务列表。

顶层响应字段

字段名	类型	说明
version	string	当前 API 版本。
status_code	integer	局状态码。完整错误码请参考 /v3/appendix/errors。建议对异常和错误状态做完整处理。
status_message	string	局状态信息。
time	string	请求执行时间，单位为秒。
cost	float	本次请求总费用。
tasks_count	integer	tasks 数组中的任务数量。
tasks_error	integer	返回错误的任务数量。
tasks	array	任务结果数组。

tasks 数组字段

字段名	类型	说明
id	string	本平台的唯一任务 ID，UUID 格式。
status_code	integer	任务状态码，范围通常为 10000-60000。
status_message	string	任务状态说明。
time	string	任务处理耗时，单位为秒。
cost	float	当前任务费用。
result_count	integer	result 数组中的数量。
path	array	请求路径。
data	object	你在请求中提交的任务参数。
result	array / null	结果数组。对于任务提交接口，此处通常为 null。

---

请求示例

cURL

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

Python

import requests

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

data = [
 {
 "keyword": "vpn",
 "location_code": 2840,
 "language_code": "en",
 "depth": 30
 },
 {
 "keyword": "vpn",
 "location_code": 2840,
 "language_code": "en",
 "depth": 30,
 "priority": 2
 },
 {
 "keyword": "vpn",
 "location_code": 2840,
 "language_code": "en",
 "postback_data": "html",
 "postback_url": "https://your-server.com/postbackscript"
 }
]

response = requests.post(url, headers=headers, json=data)
print(response.json)

TypeScript

import axios from "axios";

const postData = [
 {
 keyword: "vpn",
 location_code: 2840,
 language_code: "en",
 depth: 30
 },
 {
 keyword: "vpn",
 location_code: 2840,
 language_code: "en",
 depth: 30,
 priority: 2
 },
 {
 keyword: "vpn",
 location_code: 2840,
 language_code: "en",
 postback_data: "html",
 postback_url: "https://your-server.com/postbackscript"
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/app_data/google/app_searches/task_post",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 data: postData
})
 .then((response) => {
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error.response?.data || error.message);
 });

---

响应示例

{
 "version": "0.1.20220422",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0883 sec.",
 "cost": 0.0012,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "f1f2c3d4-1234-5678-90ab-abcdef123456",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0021 sec.",
 "cost": 0.0012,
 "result_count": 0,
 "path": [
 "v3",
 "app_data",
 "google",
 "app_searches",
 "task_post"
 ],
 "data": {
 "api": "app_data",
 "function": "app_searches",
 "se": "google",
 "keyword": "vpn",
 "location_code": 2840,
 "language_code": "en",
 "depth": 30,
 "se_type": "organic",
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 }
 ]
}

---

状态码与错误处理

建议至少处理以下几类：

• 20000：请求成功
• 20100：任务创建成功
• 40006：单次 POST 中任务数量 100
• 错误：请参考 /v3/appendix/errors

同时建议对以下做容错处理：

• 回调地址不可达
• 回调服务响应时（ 10 秒）
• 参数缺失或地区 / 语言无效
• depth出范围

使用建议

• 优使用 location_code 和 language_code，参数更稳定，便于程序化处理
• depth 尽量设置为 30、60、90 等 30 的倍数
• 若任务量较大，建议结合 tag 记录业务侧任务主键
• 如果需要自动化接收结果，优使用 postback_url
• 如果只需要任务完成通知，可使用 pingback_url

实用场景

• 监控品牌词应用排名：按定期抓取 Google Play 搜索结果，跟踪自家应用在目标市场中的自然位置。
• 分析竞品搜索占位：围绕核心功能词创建任务，识别竞品在应用商店搜索中的排名表现与覆盖范围。
• 评估 ASO 价值：对不同组合进行批量抓取，判断哪些词更容易带来靠前，优化标题与描述。
• 对比多地区搜索结果：结合不同 location_code 和 language_code 创建任务，识别应用在不同国家和语言环境下的排名差异。
• 构建自动回调采集链路：通过 postback_url 或 pingback_url 自动接收任务完成结果，减少人工轮询并提升数据库效率。