SeerMarTech API 文档

主题

Google Play 应用列表实时搜索 ​

POST /v3/app_data/google/app_listings/search/live

本接口使用 POST /v3/app_data/google/app_listings/search/live，用于实时搜索 Google Play 已发布的应用，并返回应用 ID、图标、描述、评论数、评分、价格、开发信息及应用等数据。

搜索结果由请求中的 title、description 和 categories 参数决定。目前支持美国地区：

  • 地区：United States
  • 地区代码：2840

接口信息 ​

  • 请求方法：POST
  • 请求路径：/v3/app_data/google/app_listings/search/live
  • 完整地址：https://api.seermartech.cn/v3/app_data/google/app_listings/search/live
  • 请求格式：JSON 数组，UTF-8 编码 平台限流以认证说明中的 30/60/120 次/分钟规则为准
  • 计费方式：每次请求计费。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数应放在通用 POST 数组中，每个数组代表一个搜索任务。

请求参数 ​

参数类型填说明
categoriesarray否应用分类。用于筛选应用列表，最多指定 10 个分类。完整分类列表可通过 /v3/app_data/google/app_listings/categories 获取。
descriptionstring否应用描述中的，最多 200 个字符。
titlestring否应用标题中的，最多 200 个字符。
filtersarray否结果过滤条件。最多设置 8 个过滤器，多个条件之间需要指定逻辑运算符 and 或 or。
order_byarray否结果排序规则。排序字段可使用与 filters 相同的字段，支持升序 asc 和降序 desc。单次请求最多设置 3 条排序规则。
limitinteger否返回的最大应用数量。默认值为 100，最大值为 1000。
offsetinteger否结果偏移量，默认值为 0。例如设置为 10 时，将跳过前 10 条结果。建议在获取不 10,000 条结果时使用。
offset_tokenstring否后续分页令牌。该值由上一响应返回。获取 100,000 条结果时，建议使用此参数以降低请求时风险。使用时，请求参数与上一请求保持一致。
tagstring否自定义任务标识，最多 255 个字符。该值会在响应任务的 data 对象中原样返回。

filters 支持的运算符 ​

支持以下运算符：

text
regex
not_regex
<
<=
>
>=
=
<>
in
not_in
like
not_like

like 和 not_like 支持 % 通符，可匹任意长度的字符串空字符串。

过滤器示例：

json
[
  ["item.rating.value", ">", 4],
  "and",
  ["item.reviews_count", ">=", 100]
]

可用过滤字段可通过以下接口查询：

text
GET /v3/app_data/google/app_listings/available_filters

order_by 排序格式 ​

排序规则格式为：

text
字段名,排序方向

例如：

json
[
  "item.rating.value,desc",
  "item.reviews_count,desc"
]

多个排序规则使用数组分隔，最多设置 3 条。

请求示例 ​

curl ​

bash
curl --location --request POST \
  "https://api.seermartech.cn/v3/app_data/google/app_listings/search/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "title": "vpn",
      "description": "vpn",
      "categories": ["TOOLS"],
      "order_by": [
        "item.rating.value,desc"
      ],
      "filters": [
        ["item.rating.value", ">", 4]
      ],
      "limit": 10
    }
  ]'

Python ​

python
import requests

url = "https://api.seermartech.cn/v3/app_data/google/app_listings/search/live"

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

# 请求体是 JSON 数组
payload = [
    {
        "title": "vpn",
        "description": "vpn",
        "order_by": [
            "item.rating.value,desc"
        ],
        "filters": [
            ["item.rating.value", ">", 4]
        ],
        "limit": 3,
    }
]

response = requests.post(url, headers=headers, json=payload, timeout=60)
data = response.json()

if data.get("status_code") == 20000:
    print(data)
else:
    print(
        "请求失败，状态码：%s，消息：%s"
        % (data.get("status_code"), data.get("status_message"))
    )

TypeScript ​

typescript
import axios from "axios";

const response = await axios.post(
  "https://api.seermartech.cn/v3/app_data/google/app_listings/search/live",
  [
    {
      title: "vpn",
      description: "vpn",
      categories: ["TOOLS"],
      order_by: ["item.rating.value,desc"],
      filters: [["item.rating.value", ">", 4]],
      limit: 10,
    },
  ],
  {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
  }
);

console.log(response.data);

响应结构 ​

接口返回 JSON 对象 tasks 数组。每个任务对应请求数组中的一个任务对象。

顶层字段 ​

字段类型说明
versionstring当前 API 版本。
status_codeinteger通用响应状态码。成功通常为 20000。完整错误码请参考 /v3/appendix/errors。
status_messagestring通用状态消息。
timestring请求执行耗时，单位为秒。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_countintegertasks 数组中的任务总数。
tasks_errorintegertasks 数组中返回错误的任务数。
tasksarray任务结果数组。

任务字段 ​

字段类型说明
idstring任务唯一标识，UUID 格式。
status_codeinteger任务状态码，通常在 10000 至 60000 范围。
status_messagestring任务状态消息。
timestring任务执行耗时。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_countintegerresult 数组中的数量。
patharray请求 API 路径。
dataobject与 POST 请求中提交的参数基本一致。
resultarray搜索结果数组。

result 字段 ​

字段类型说明
total_countinteger数据库中符合条件的结果总数。
countinteger当前结果数组中的应用数量。
offsetinteger当前结果偏移量。
offset_tokenstring后续分页令牌。获取大量结果时，可将用于下一次请求。
itemsarray应用及数据。

items 字段 ​

字段类型说明
app_idstring应用 ID。
se_domainstring搜索引擎域名，例如 play.google.com。
location_codeinteger地区代码，目前为 2840。
language_codestring语言代码，例如 en。
check_urlstring搜索结果对应的直接 URL，可用于核验结果准确性。
time_updatestring搜索数据最近更新时间，通常为 ISO 8601 或 UTC 时间格式。
itemobject应用详细信息。

item 应用 ​

字段类型说明
typestring结果类型，目前可能为 google_play_info_organic。
rank_groupinteger在相同 type 结果组中的排名。
rank_absoluteinteger在所有返回应用中的绝对排名。
positionstring结果在搜索结果页中的位置，目前为 left。
app_idstring应用 ID。
titlestring应用标题。
urlstringGoogle Play 应用页 URL。
iconstring应用图标 URL。
descriptionstring应用描述。
reviews_countinteger应用评论总数。
ratingobject应用平均评分。
priceobject应用价格信息。
is_freeboolean是否为应用。
main_categorystring应用所属的 Google Play 主分类。
installsstring应用量的近似显示值，例如 500+。
installs_countinteger应用量的数值。
developerstring开发名称。
developer_idstringGoogle Play 中的开发 ID。
developer_urlstring开发主页 URL。
developer_emailstring开发邮箱。
developer_addressstring开发地址，可能为 null。
developer_websitestring开发官方网站。
versionstring当前应用版本。
minimum_os_versionstring安应用所需的最低操作系统版本。
sizestring应用大小，可能为 null。
released_datestring应用发布日期，UTC 格式。
last_update_datestring应用最近更新时间，UTC 格式。
update_notesstring开发提供的最近版本更新说明。
imagesarray应用页中的图片 URL 列表。
videosarray应用页中的视频 URL 列表。
similar_appsarray与当前应用相似的应用列表。
more_apps_by_developerarray同一开发发布的应用。
genresarray应用所属类型或分类。
tagsarray应用标签。

rating 评分对象 ​

字段类型说明
rating_typestring评分类型，目前为 Max5。
valuefloat当前平均评分。
votes_countinteger评分或反馈数量。
rating_maxinteger评分最大值。对于 Max5，该值为 5。

price 价格对象 ​

字段类型说明
currentfloat当前价格。
regularfloat常规价格，可能为 null。
max_valuefloat价格区间的最大值，可能为 null。
currencystring价格币种的 ISO 代码。
is_price_rangeboolean是否以价格区间形式展示。
displayed_pricestring结果页面中显示的原始价格文本。

响应示例 ​

json
{
  "version": "0.1.20221214",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.1083 sec.",
  "cost": 0.11,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "7f2c6f1a-7f9f-4f1c-9ef5-7e2a3c7a1a11",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.1000 sec.",
      "cost": 0.11,
      "result_count": 1,
      "path": [
        "v3",
        "app_data",
        "google",
        "app_listings",
        "search",
        "live"
      ],
      "data": {
        "api": "app_data",
        "function": "search",
        "se": "google",
        "title": "vpn",
        "description": "vpn",
        "categories": ["TOOLS"],
        "order_by": [
          "item.rating.value,desc"
        ],
        "filters": [
          ["item.rating.value", ">", 4]
        ],
        "limit": 10
      },
      "result": [
        {
          "total_count": 100,
          "count": 1,
          "offset": 0,
          "offset_token": "eyJvZmZzZXQiOjEwfQ==",
          "items": [
            {
              "app_id": "com.example.vpn",
              "se_domain": "play.google.com",
              "location_code": 2840,
              "language_code": "en",
              "check_url": "https://play.google.com/store/apps/details?id=com.example.vpn&hl=en&gl=us",
              "time_update": "2023-05-23 10:16:19 +00:00",
              "item": {
                "type": "google_play_info_organic",
                "rank_group": 1,
                "rank_absolute": 1,
                "position": "left",
                "app_id": "com.example.vpn",
                "title": "Example VPN",
                "url": "https://play.google.com/store/apps/details?id=com.example.vpn&hl=en&gl=us",
                "icon": "https://play-lh.googleusercontent.com/example",
                "description": "用于保护用户隐私并提供网络连接的 VPN 应用。",
                "reviews_count": 120,
                "rating": {
                  "rating_type": "Max5",
                  "value": 4.7,
                  "votes_count": 120,
                  "rating_max": 5
                },
                "price": {
                  "current": 0,
                  "regular": null,
                  "max_value": null,
                  "currency": "USD",
                  "is_price_range": false,
                  "displayed_price": null
                },
                "is_free": true,
                "main_category": "Tools",
                "installs": "10,000+",
                "installs_count": 12500,
                "developer": "Example Developer",
                "developer_id": "example-developer",
                "developer_url": "https://play.google.com/store/apps/developer?id=example-developer",
                "developer_email": "support@example.com",
                "developer_address": null,
                "developer_website": "https://example.com",
                "version": "1.15.2",
                "minimum_os_version": "5.0",
                "size": null,
                "released_date": "2022-07-19 03:00:00 +00:00",
                "last_update_date": "2023-05-19 03:00:00 +00:00",
                "update_notes": "修复问题并改进应用性能。",
                "images": [],
                "videos": null,
                "similar_apps": [],
                "more_apps_by_developer": null,
                "genres": null,
                "tags": null
              }
            }
          ]
        }
      ]
    }
  ]
}

分页说明 ​

使用 offset ​

适用于获取不约 10,000 条结果的场景：

json
[
  {
    "title": "vpn",
    "limit": 1000,
    "offset": 1000
  }
]

使用 offset_token ​

当响应返回 offset_token 时，将复制到下一次请求中。除 offset_token 外，参数与前一次请求一致：

json
[
  {
    "title": "vpn",
    "limit": 1000,
    "offset_token": "eyJvZmZzZXQiOjEwfQ=="
  }
]

每个后续任务都会生成唯一的 offset_token。请勿修改原始查询条件后复用令牌。

错误处理 ​

建议客户端同时检查以下字段：

  • 顶层 status_code
  • 任务级 tasks[].status_code
  • status_message
  • tasks[].status_message
  • tasks_error

20000 表示请求成功。完整状态码和错误消息列表请参考：

text
/v3/appendix/errors

实用场景 ​

  • 挖掘竞品应用：按标题、描述和分类搜索目标应用，获取竞品的评分、评论量、量和版本信息，支持移动应用市场竞争分析。
  • 筛选高质量应用：使用评分、评论数和量过滤器定位优质应用，为 ASO 竞品库和市场研究提供结构化数据。
  • 分析应用商店：批量搜索标题或描述中的目标，评估对应的应用数量、分类分布和竞争程度。
  • 监控开发产品矩阵：读取 more_apps_by_developer，发现同一开发发布的应用，完善竞品和市场地图。
  • 跟踪应用版本变化：定期采集版本号、最近更新时间和更新说明，分析竞品迭代节奏并制定产品与策略。

统一入口：官网 · LLM API · 控制台

© 2026 SeerMarTech · GEO · SEO 营销数据 API