SeerMarTech API 文档

主题

Apple App Listings 实时搜索 ​

POST /v3/app_data/apple/app_listings/search/live

本接口使用 POST 方法，路径为：

/v3/app_data/apple/app_listings/search/live

用于实时搜索 App Store 中发布的应用，并返回应用 ID、图标、评论数、评分、价格、开发信息及应用。搜索结果取决于请求中设置的 title、description 和 categories 参数。

> 当前支持美国地区，地区代码为 2840。

计费与请求限制 ​

  • 本接口按请求计费。
  • 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。
  • 请求体使用 UTF-8 编码的 JSON 格式。
  • POST 请求体是 JSON 数组，每次调用最多 1 个任务。 平台限流以认证说明中的 30/60/120 次/分钟规则为准。
  • 同时发送的请求数量最多为 30 个。

请求参数 ​

请求体中的每个任务对象支持以下字段：

字段类型填说明
categoriesarray否应用分类。指定的分类用于筛选应用列表，最多支持 10 个分类。可通过分类接口获取完整分类列表：/v3/app_data/apple/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 条结果时请求时。该值由上一次响应返回。使用 offset_token 时，请求参数与上一次请求保持一致。
tagstring否用户自定义任务标识，最多 255 个字符。该值会原样返回在响应任务的 data 对象中，便于请求与结果。

filters 过滤条件 ​

支持以下运算符：

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

使用 like 或 not_like 时，可以使用 % 匹任意长度的字符串空字符串。

过滤条件示例：

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

可用过滤字段列表：

/v3/app_data/apple/app_listings/available_filters

order_by 排序示例 ​

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

：

  • asc：升序排列
  • desc：降序排列

请求示例 ​

cURL ​

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

Python ​

python
import requests

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

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

payload = [
    {
        "title": "vpn",
        "description": "vpn",
        "order_by": [
            "item.rating.value,desc"
        ],
        "filters": [
            ["item.rating.value", ">", 4]
        ],
        "limit": 2,
    }
]

response = requests.post(url, headers=headers, json=payload)
result = response.json()

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        "请求失败，状态码：{}，消息：{}".format(
            result.get("status_code"),
            result.get("status_message"),
        )
    )

TypeScript ​

typescript
import axios from "axios";

const payload = [
  {
    title: "vpn",
    description: "vpn",
    order_by: ["item.rating.value,desc"],
    filters: [["item.rating.value", ">", 4]],
    limit: 2,
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/app_data/apple/app_listings/search/live",
    payload,
    {
      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);
  });

响应结构 ​

接口返回 JSON 对象 tasks 数组任务执行结果。

顶层字段 ​

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

tasks 任务字段 ​

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

result 结果字段 ​

字段类型说明
total_countinteger数据库中符合条件的结果总数。
countinteger当前响应中返回的结果数量。
offsetinteger当前结果的偏移量。
offset_tokenstring获取后续结果时使用的翻页令牌。
itemsarray应用及数据数组。

items 应用结果字段 ​

字段类型说明
app_idstring应用 ID。
se_domainstring请求中使用的搜索引擎域名。
location_codeinteger地区代码。
language_codestring语言代码。
check_urlstring对应搜索结果页面的直接 URL，可用于核验结果准确性。
time_updatestring搜索数据的最后更新时间，ISO 8601 格式。
itemobject应用详细信息。

item 应用字段 ​

字段类型说明
typestring结果类型，当前可能为 app_store_info_organic。
rank_groupinteger在相同 type 结果组中的排名。不同类型结果之间不会计该排名。
rank_absoluteinteger应用在结果中的绝对排名。
positionstring结果在搜索页面中的位置，目前为 left。
app_idstring应用 ID。
titlestring应用标题。
subtitlestring应用副标题。
urlstringApp Store 应用页 URL。
iconstring应用图标 URL。
descriptionstring应用描述。
reviews_countinteger应用评论总数。
ratingobject应用平均评分。
priceobject应用价格信息。
is_freeboolean是否为应用。
main_categorystring应用主要分类。
categoriesarray应用所属的分类。
languagesarray应用支持的语言。
advisoriesarray应用年龄分级及使用限制信息。
developerstring开发名称。
developer_idstringApp Store 中的开发 ID。
developer_urlstringApp Store 开发页面 URL。
versionstring当前应用版本。
minimum_os_versionstring安应用所需的最低操作系统版本。
sizestring应用大小。
released_datestring应用发布日期，UTC 时间格式：yyyy-MM-dd HH-mm-ss +00:00。
last_update_datestring应用最后更新时间，UTC 时间格式：yyyy-MM-dd HH-mm-ss +00:00。
update_notesstring开发提供的最新更新说明。
imagesarray应用页中的图片 URL。
similar_appsarray与当前应用相似的应用。
more_apps_by_developerarray同一开发发布的应用。

rating 评分字段 ​

字段类型说明
rating_typestring评分类型，目前为 Max5。
valuefloat应用平均评分。
votes_countinteger评分反馈数量。当前场景下该字段可能为 null。
rating_maxinteger评分上限。对于 Max5，最大值为 5。

price 价格字段 ​

字段类型说明
currentfloat当前价格。
regularfloat常规价格。
max_valuefloat最高价格，适用于价格区间。
currencystring价格使用的货币 ISO 代码。
is_price_rangeboolean是否以价格区间形式提供。
displayed_pricestring结果页面中展示的原始价格文本。

similar_apps 和 more_apps_by_developer 字段 ​

这两个数组中的应用对象以下字段：

字段类型说明
app_idstring应用 ID。
titlestring应用标题。
urlstringApp Store 应用页 URL。

响应示例 ​

json
{
  "version": "0.1.20260717",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.2633 sec.",
  "cost": 0.101,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.2500 sec.",
      "cost": 0.101,
      "result_count": 1,
      "path": [
        "v3",
        "app_data",
        "apple",
        "app_listings",
        "search",
        "live"
      ],
      "data": {
        "api": "app_data",
        "function": "search",
        "se": "apple",
        "title": "vpn",
        "order_by": [
          "item.rating.value,desc"
        ],
        "filters": [
          ["item.rating.value", ">", 4]
        ],
        "limit": 2
      },
      "result": [
        {
          "total_count": 1,
          "count": 1,
          "offset": 0,
          "offset_token": "eyJvZmZzZXQiOjF9",
          "items": [
            {
              "app_id": "1451197812",
              "se_domain": "apps.apple.com",
              "location_code": 2840,
              "language_code": "en",
              "check_url": "https://apps.apple.com/us/search?term=vpn",
              "time_update": "2023-05-23T10:16:19.000000Z",
              "item": {
                "type": "app_store_info_organic",
                "rank_group": 1,
                "rank_absolute": 1,
                "position": "left",
                "app_id": "1451197812",
                "title": "VPN Tracker",
                "subtitle": "Secure VPN",
                "url": "https://apps.apple.com/us/app/vpn-tracker/id1451197812",
                "icon": "https://is1-ssl.mzstatic.com/image/thumb/example/icon.png",
                "description": "VPN application description.",
                "reviews_count": 120,
                "rating": {
                  "rating_type": "Max5",
                  "value": 4.6,
                  "votes_count": null,
                  "rating_max": 5
                },
                "price": {
                  "current": 0,
                  "regular": 0,
                  "max_value": 0,
                  "currency": "USD",
                  "is_price_range": false,
                  "displayed_price": "Free"
                },
                "is_free": true,
                "main_category": "Utilities",
                "categories": [
                  "Utilities",
                  "Productivity"
                ],
                "languages": [
                  "EN"
                ],
                "advisories": [],
                "developer": "equinux AG",
                "developer_id": "1451197812",
                "developer_url": "https://apps.apple.com/us/developer/equinux-ag/id1451197812?platform=iphone",
                "version": "Version 1.4",
                "minimum_os_version": "Requires iOS 9.3 or later.",
                "size": "48.7 MB",
                "released_date": null,
                "last_update_date": "2023-04-17 09:39:48 +00:00",
                "update_notes": "World Connect now offers servers in 27 additional countries.",
                "images": [],
                "similar_apps": [],
                "more_apps_by_developer": []
              }
            }
          ]
        }
      ]
    }
  ]
}

错误处理 ​

建议根据顶层和任务级别的 status_code、status_message 实现错误处理：

  • 顶层 status_code：表示整个请求的处理状态。
  • 任务级 status_code：表示任务的处理状态。
  • tasks_error：表示失败任务数量。
  • status_message：提供对应的状态说明。

完整错误码请参考错误码文档：/v3/appendix/errors

实用场景 ​

  • 搜索竞品应用：按标题、描述和分类发现美国 App Store 中的竞品，支持竞品单构建与市场格局分析。
  • 筛选高评分应用：使用评分、评论数等字段过滤结果，快速定位用户认可度较高的应用作为对标对象。
  • 分析应用商店覆盖：通过标题和描述搜索应用，评估目标的应用数量与竞争程度。
  • 监测竞品商业化信息：读取价格、状态、价格区间和货币字段，比较不同应用的定价策略。
  • 构建开发产品矩阵：利用 more_apps_by_developer 获取同一开发的应用，分析产品布局和交叉竞争。

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

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