Google Play 应用排名实时查询

POST /v3/dataforseo_labs/google/keywords_for_app/live

本接口使用 POST /v3/dataforseo_labs/google/keywords_for_app/live，返回指定 Google Play 应用当前排名的列表、指标及应用在 Google Play 搜索结果中的排名信息。

查询结果针对请求中指定的 app_id。数据每周更新，最新更新时间可通过 /v3/dataforseo_labs/status/ 查询。

接口信息

请求方法：POST
请求路径：/v3/dataforseo_labs/google/keywords_for_app/live
请求地址：https://api.seermartech.cn/v3/dataforseo_labs/google/keywords_for_app/live
请求格式：application/json
请求体格式：JSON 数组，每次请求最多 1 个任务平台限流以认证说明中的 30/60/120 次/分钟规则为准

本接口支持设置返回数量、结果筛选条件和排序规则。

计费说明

每次请求按任务计费。参考价以本平台当前计费为准，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数

请求体是 JSON 数组：

json

[
  {
    "app_id": "org.telegram.messenger",
    "location_code": 2840,
    "language_code": "en",
    "limit": 10
  }
]

任务参数

参数	类型	填	说明
`app_id`	string	是	Google Play 应用 ID。该值位于应用页 URL 的 `id` 参数中。例如，`https://play.google.com/store/apps/details?id=org.telegram.messenger` 中的应用 ID 为 `org.telegram.messenger`。
`location_name`	string	条件填	地区名。未指定 `location_code` 时提供。当前接口支持美国地区，示例值：`United States`。
`location_code`	integer	条件填	地区代码。未指定 `location_name` 时提供。当前接口支持美国地区，示例值：`2840`。
`language_name`	string	条件填	语言名。未指定 `language_code` 时提供。当前接口支持英语，示例值：`English`。
`language_code`	string	条件填	语言代码。未指定 `language_name` 时提供。当前接口支持英语，示例值：`en`。
`filters`	array	否	结果筛选条件。最多可同时设置 8 个筛选条件。多个条件之间需要使用 `and` 或 `or` 逻辑运算符。支持的运算符：`<`、`<=`、`>`、`>=`、`=`、`<>`、`in`、`not_in`。
`order_by`	array	否	结果排序规则。可使用与 `filters` 相同的字段和排序表达式。排序方向支持 `asc` 和 `desc`，多个排序规则使用逗号分隔，单次请求最多设置 3 条。
`limit`	integer	否	最多返回的数量。默认值为 `100`，最大值为 `1000`。
`offset`	integer	否	结果偏移量。默认值为 `0`。例如设置为 `10` 时，将跳过前 10 条结果，返回后续数据。
`tag`	string	否	用户自定义任务标识，用于请求与响应，最长 255 个字符。指定的值会原样返回在响应的 `data` 对象中。

地区与语言

可通过以下接口获取可用的地区和语言列表：

GET /v3/dataforseo_labs/locations_and_languages

当前接口限制：

地区：支持 United States，代码为 2840
语言：支持 English，代码为 en

筛选示例

以下示例表示返回搜索量大于或等于 500 的：

json

[
  {
    "app_id": "org.telegram.messenger",
    "location_name": "United States",
    "language_name": "English",
    "filters": [
      [
        "keyword_data.keyword_info.search_volume",
        ">=",
        500
      ]
    ],
    "limit": 10
  }
]

多个筛选条件示例：

json

[
  {
    "app_id": "org.telegram.messenger",
    "location_code": 2840,
    "language_code": "en",
    "filters": [
      [
        "keyword_data.keyword_info.search_volume",
        ">=",
        500
      ],
      "and",
      [
        "ranked_serp_element.serp_item.rank_absolute",
        "<=",
        20
      ]
    ],
    "limit": 10
  }
]

响应结构

接口返回 JSON 对象 tasks 任务数组。

顶层字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	通用响应状态码。成功通常为 `20000`。
`status_message`	string	通用状态消息。
`time`	string	请求执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务总数。
`tasks_error`	integer	`tasks` 数组中执行失败的任务数量。
`tasks`	array	任务结果数组。

`tasks` 任务字段

字段	类型	说明
`id`	string	任务唯一标识，UUID 格式。
`status_code`	integer	任务状态码，取值范围通常为 `10000`–`60000`。
`status_message`	string	任务状态消息。
`time`	string	任务执行耗时。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的数量。
`path`	array	请求路径信息。
`data`	object	请求中提交的任务参数。
`result`	array	查询结果数组。

`result` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型，通常为 `google`。
`app_id`	string	请求中的 Google Play 应用 ID。
`location_code`	integer	请求中的地区代码。
`language_code`	string	请求中的语言代码。
`total_count`	integer	数据库中与请求条件匹的结果总数。
`items_count`	integer	`items` 数组中的结果数量。
`items`	array	应用排名数据。

`items` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型。
`keyword_data`	object	返回的指标数据。
`ranked_serp_element`	array	应用在该下的 Google Play 搜索结果排名信息。

`keyword_data` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型。
`keyword`	string	返回的。
`location_code`	integer	地区代码。
`language_code`	string	语言代码。
`keyword_info`	object	详细指标。

`keyword_info` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型。
`last_updated_time`	string	数据更新时间，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`。
`competition`	float / null	竞争度，基于广告数据，取值范围为 `0`–`1`。Google Play 数据中通常为 `null`。
`competition_level`	string / null	付费搜索结果中的竞争等级，可取 `LOW`、`MEDIUM`、`HIGH`。未知时为 `null`，本接口通常为 `null`。
`cpc`	float / null	历史平均单次点击费用。Google Play 数据中通常为 `null`。
`search_volume`	integer	Google Play 中该的平均月搜索量。
`low_top_of_page_bid`	float / null	广告展示在第一页顶部所需的较低参考出价。Google Play 数据中通常为 `null`。
`high_top_of_page_bid`	float / null	广告展示在第一页顶部所需的较高参考出价。Google Play 数据中通常为 `null`。
`categories`	array / null	产品和服务分类。Google Play 数据中通常为 `null`。
`monthly_searches`	array / null	过去 12 个月的月度搜索量数据。Google Play 数据中通常为 `null`。

`ranked_serp_element` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型。
`serp_item`	array	搜索结果数据。

`serp_item` 字段

字段	类型	说明
`type`	string	搜索结果类型。当前支持 `google_play_search_organic`。
`rank_group`	integer	同类型搜索结果中的组排名。不同类型之间不会计算此排名。
`rank_absolute`	integer	搜索结果中的绝对排名。
`position`	string	素在搜索结果中的对齐位置，可取 `left` 或 `right`。
`app_id`	string	应用 ID。
`title`	string	应用名称。
`url`	string	Google Play 应用页 URL。
`icon`	string	应用图标 URL。
`reviews_count`	integer	应用评论总数。
`rating`	object	应用平均评分。
`is_free`	object	应用价格信息。
`developer`	string	应用开发名称。
`developer_url`	string	Google Play 开发页面 URL。
`check_url`	string	对应搜索结果页面的直接 URL，可用于核验结果准确性。
`se_results_count`	string	该对应的搜索结果数量。
`last_updated_time`	string	搜索结果数据更新时间，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`。
`previous_updated_time`	string / null	上一次搜索结果数据更新时间，UTC 格式；没有历史数据时为 `null`。

`rating` 字段

字段	类型	说明
`rating_type`	string	评分类型，当前为 `Max5`。
`value`	float	应用评分值。
`votes_count`	integer / null	评分票数。当前通常为 `null`。
`rating_max`	integer	评分上限。`Max5` 类型的上限为 `5`。

`is_free` 字段

尽管字段名称为 is_free，返回值为价格对象，字段如下：

字段	类型	说明
`current`	float	当前价格。
`regular`	float	常规价格。
`max_value`	float	最高价格；当价格以区间形式展示时使用。
`currency`	string	价格币种的 ISO 代码。
`is_price_range`	boolean	是否以价格区间形式提供。
`displayed_price`	string	搜索结果中展示的原始价格文本。

认证方式

请求时使用 Bearer Token：

http

Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

请求示例

cURL

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/dataforseo_labs/google/keywords_for_app/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "app_id": "org.telegram.messenger",
      "location_name": "United States",
      "language_name": "English",
      "filters": [
        [
          "keyword_data.keyword_info.search_volume",
          ">=",
          500
        ]
      ],
      "limit": 10
    }
  ]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/google/keywords_for_app/live"

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

# 请求体是 JSON 数组
payload = [
    {
        "app_id": "org.telegram.messenger",
        "location_name": "United States",
        "language_name": "English",
        "filters": [
            [
                "keyword_data.keyword_info.search_volume",
                ">=",
                500,
            ]
        ],
        "limit": 10,
    }
]

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 url =
  "https://api.seermartech.cn/v3/dataforseo_labs/google/keywords_for_app/live";

// 请求体是 JSON 数组
const payload = [
  {
    app_id: "org.telegram.messenger",
    location_name: "United States",
    language_name: "English",
    filters: [
      ["keyword_data.keyword_info.search_volume", ">=", 500],
    ],
    limit: 10,
  },
];

axios
  .post(url, payload, {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
  })
  .then((response) => {
    const result = response.data;

    if (result.status_code === 20000) {
      console.log(result);
    } else {
      console.error(
        `请求失败，状态码：${result.status_code}，消息：${result.status_message}`
      );
    }
  })
  .catch((error) => {
    console.error("网络请求失败：", error.message);
  });

响应示例

json

{
  "version": "0.1.20220428",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.8401 sec.",
  "cost": 0.011,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.7210 sec.",
      "cost": 0.011,
      "result_count": 1,
      "data": {
        "api": "dataforseo_labs",
        "function": "keywords_for_app",
        "se_type": "google",
        "app_id": "org.telegram.messenger",
        "language_name": "English",
        "location_code": 2840,
        "limit": 10
      },
      "result": [
        {
          "se_type": "google",
          "app_id": "org.telegram.messenger",
          "location_code": 2840,
          "language_code": "en",
          "total_count": 1250,
          "items_count": 1,
          "items": [
            {
              "se_type": "google",
              "keyword_data": {
                "se_type": "google",
                "keyword": "telegram",
                "location_code": 2840,
                "language_code": "en",
                "keyword_info": {
                  "se_type": "google",
                  "last_updated_time": "2019-11-15 12:57:46 +00:00",
                  "competition": null,
                  "competition_level": null,
                  "cpc": null,
                  "search_volume": 5000,
                  "low_top_of_page_bid": null,
                  "high_top_of_page_bid": null,
                  "categories": null,
                  "monthly_searches": null
                }
              },
              "ranked_serp_element": [
                {
                  "se_type": "google",
                  "serp_item": [
                    {
                      "type": "google_play_search_organic",
                      "rank_group": 1,
                      "rank_absolute": 1,
                      "position": "left",
                      "app_id": "org.telegram.messenger",
                      "title": "Telegram",
                      "url": "https://play.google.com/store/apps/details?id=org.telegram.messenger",
                      "icon": "https://example.com/icon.png",
                      "reviews_count": 1000000,
                      "rating": {
                        "rating_type": "Max5",
                        "value": 4.5,
                        "votes_count": null,
                        "rating_max": 5
                      },
                      "is_free": {
                        "current": 0,
                        "regular": 0,
                        "max_value": 0,
                        "currency": "USD",
                        "is_price_range": false,
                        "displayed_price": "Free"
                      },
                      "developer": "Telegram FZ-LLC",
                      "developer_url": "https://play.google.com/store/apps/developer?id=Telegram+FZ-LLC",
                      "check_url": "https://play.google.com/store/search?q=telegram&c=apps",
                      "se_results_count": "100000",
                      "last_updated_time": "2019-11-15 12:57:46 +00:00",
                      "previous_updated_time": null
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

错误处理

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

顶层 status_code：表示整个 API 请求的处理状态。
任务级 status_code：表示单个任务的处理状态。
tasks_error：表示执行失败的任务数量。
成功状态码通常为 20000。
完整状态码和错误消息请参考本平台错误码文档。

实用场景

发现应用排名：获取目标应用在 Google Play 中获得排名的，扩大 ASO 库并识别自然流量。
筛选高搜索量词：使用 filters 筛选搜索量较高的，优优化应用标题、简介和字段。
监控排名：定期调用接口保存 rank_group 和 rank_absolute，评估应用版本更新或 ASO 调整后的排名变化。
分析竞品覆盖范围：对多个竞品应用分别查询排名，比较覆盖差异，寻找和投放机会。
评估商业价值：结合 search_volume、competition_level 和 cpc 等指标，制定应用商店优化与广告投放优级。

Google Play 应用排名实时查询 ​

接口信息 ​

计费说明 ​

请求参数 ​

任务参数 ​

地区与语言 ​

筛选示例 ​

响应结构 ​

顶层字段 ​

tasks 任务字段 ​

result 字段 ​

items 字段 ​

keyword_data 字段 ​

keyword_info 字段 ​

ranked_serp_element 字段 ​

serp_item 字段 ​

rating 字段 ​

is_free 字段 ​

认证方式 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

错误处理 ​

实用场景 ​

Google Play 应用排名实时查询

接口信息

计费说明

请求参数

任务参数

地区与语言

筛选示例

响应结构

顶层字段

`tasks` 任务字段

`result` 字段

`items` 字段

`keyword_data` 字段

`keyword_info` 字段

`ranked_serp_element` 字段

`serp_item` 字段

`rating` 字段

`is_free` 字段

认证方式

请求示例

cURL

Python

TypeScript

响应示例

错误处理

实用场景