# App 榜单列表接口 ## 接口信息 - **接口名称**: 获取 App 投放榜单列表 - **请求方法**: POST - **接口地址**: `/open-api/v1/data` - **接口路径**: `/v3/api/open/rank/app/list` - **接口描述**: 根据过滤条件获取 App 榜单列表信息，支持分页 - **价格说明**: 获取一条数据结果消耗1 credit **请求头:** - Content-Type: application/json - Accept: application/json ## 请求参数 ### 请求结构 | 参数名 | 类型 | 描述 | 示例 | 必填 | 默认值 | | ------ | ------ | --------------------------- | ---------------------------- | ---- | ------ | | key | string | 用户申请的外部 api 请求 key | "your_api_key_here" | 是 | | | uri | string | 接口路径 | "/v3/api/open/rank/app/list" | 是 | | | params | object | 接口入参对象 | 见参数列表 | 是 | | ### 参数列表 (params 对象) | 参数名 | 类型 | 描述 | 示例 | 必填 | 默认值 | | ---------------- | ------- |----------------------------------------------------------------------------------------------------------------------------------------------------|-----------------| ---- | ------ | | current_page | integer | 当前页码 | 1 | 是 | | | page_size | integer | 每页数据量 | 20 | 是 | | | sort_key | string | 排序字段: digg_count_growth-点赞数, digg_growth_rate-增长率, video_count-广告数，app_download_count-总安装数，latest_download_count-月安装数，last_month_revenue-月收入额（USD） | "count_growth" | 是 | | | sort_type | string | 排序方式: desc-降序, asc-升序 | "desc" | 是 | | | time | integer | 时间范围: 0-默认 | 0 | 是 | | | type | integer | 时间类型: 0-默认, 1-日榜, 2-周榜, 3-月榜 | 1 | 是 | | | app_category | string | App 分类，支持多个，字符串拼接 | "id6003,id6023" | 否 | | | app_system | string | App 系统: ios/android | "ios" | 否 | | | app_type | string | App 类型: app/game | "app" | 否 | | | count_growth_max | double | 数据增长最大值(播放数增长) | 1000000 | 否 | | | count_growth_min | double | 数据增长最小值(播放数增长) | 1000 | 否 | | | growth_rate_max | double | 数据增长率最大值 | 1.0 | 否 | | | growth_rate_min | double | 数据增长率最小值 | 0.1 | 否 | | | plat_type | integer | 平台类型: 0-全部平台, 1-TikTok, 2-Facebook | 1 | 否 | | | region | string | 目标地区，支持多个，字符串拼接 | "US,CA,GB" | 否 | | | video_count_max | long | 广告数 | 1000000 | No | | | video_count_min | long | 广告数 | 1000 | No | | | app_download_count_max | long | 总安装数 | 1000000 | No | | | app_download_count_min | long | 总安装数 | 1000 | No | | | latest_download_count_max | long | 月安装数 | 1000000 | No | | | latest_download_count_min | long | 月安装数 | 1000 | No | | | last_month_revenue_max | long | 月收入额（USD） | 1000000 | No | | | last_month_revenue_min | long | 月收入额（USD） | 1000 | No | | ### 请求示例 ```bash curl -X POST "https://www.pipispy.com/open-api/v1/data" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "key": "your_api_key_here", "uri": "/v3/api/open/rank/app/list", "params": { "current_page": 1, "page_size": 20, "sort_key": "count_growth", "sort_type": "desc", "time": 1, "type": 1, "app_category": "id6003,id6023", "app_system": "ios", "app_type": "app", "count_growth_min": 1000, "count_growth_max": 1000000, "growth_rate_min": 0.1, "growth_rate_max": 1.0, "plat_type": 1, "region": "US,CA,GB" } }' ``` ## 响应参数 ### 响应体结构 ```json { "code": 200, "message": "success", "data": { "data": [ // App榜单列表项 ], "page": { // 分页信息 } }, "version": "v1", "timestamp": null, "sign": null, "remaining_credits": 9980, "consumed_credits": 20, "success": true, "fail": false } ``` ### 响应字段说明 ##### 主要响应字段 | 字段名 | 类型 | 描述 | | ------------- | ------------ | ------------ | | **code** | integer | 响应状态码 | | **message** | string | 响应消息 | | **data** | object | 响应数据对象 | | **version** | string | API 版本号 | | **timestamp** | integer/null | 时间戳 | | **sign** | string/null | 签名 | | **remaining_credits** | Long | 当前请求后的剩余可用积分 | | **consumed_credits** | Long | 本次请求消耗的积分 | | **success** | boolean | 是否成功 | | **fail** | boolean | 是否失败 | ##### 数据对象字段 | 字段名 | 类型 | 描述 | | -------- | ------------- | ------------ | | **data** | array[object] | App 榜单列表 | | **page** | object | 分页信息 | ##### 数据项字段 | 字段名 | 类型 | 描述 | | ---------------------- | ------------- | ---------------------------------- | | id | string | App 唯一标识 ID | | app_name | string | App 名称 | | icon | string | App 图标 URL | | platform | array[string] | 平台列表，如["tiktok", "facebook"] | | region | array[string] | 目标地区列表，如["US", "CA", "GB"] | | app_category | object | App 分类信息 | | app_rate | object | App 评分信息 | | app_type | string | App 类型(app/game) | | app_store | string | 应用商店(apple/google) | | app_download_count | long | 下载量 | | app_comment_count | long | 评论数 | | play_count | long | 播放数 | | video_count | long | 视频数量 | | digg_count | long | 点赞数 | | put_day | integer | 上线天数 | | found_time | long | 发现时间戳 | | latest_found_time | long | 最新发现时间戳 | | is_collection | boolean | 是否已收藏 | | last_month_revenue | object | 上月收入信息 | | play_count_growth_rate | double | 播放数增长率 | | digg_growth_rate | double | 点赞增长率 | | latest_download_count | long | 最新下载量 | | app_dev_info | object | 开发者信息 | | created_time | long | 创建时间戳 | ##### App 分类对象字段 | 字段名 | 类型 | 描述 | | ---------- | ------------- | ---------- | | id | string | 分类 ID | | name | string | 分类名称 | | type | string | 分类类型 | | app_system | string | 应用系统 | | children | array[object] | 子分类列表 | ##### App 评分对象字段 | 字段名 | 类型 | 描述 | | ------ | ------ | -------- | | score | double | 评分 | | count | long | 评分数量 | ##### 收入对象字段 | 字段名 | 类型 | 描述 | | -------- | ------ | -------------- | | unit | string | 单位(cent) | | currency | string | 货币类型(USD) | | type | string | 类型(currency) | | value | long | 收入值(分) | ##### 开发者信息对象字段 | 字段名 | 类型 | 描述 | | ----------- | ------ | -------------- | | name | string | 开发者名称 | | icon | string | 开发者图标 | | id | string | 开发者 ID | | email | string | 开发者邮箱 | | url | string | 开发者链接 | | website_url | string | 官网链接(可选) | | avatar | string | 头像(可选) | ##### 分页对象字段 | 字段名 | 类型 | 描述 | | ------------ | ------- | ------------ | | total_count | number | 总数量 | | page_count | number | 总页数 | | current_page | number | 当前页码 | | page_size | number | 每页数据量 | | is_next | boolean | 是否有下一页 | ### 响应示例 ```json { "code": 200, "message": "success", "data": { "data": [ { "platform": ["tiktok", "facebook"], "id": "17cdd4b2fc9c3e0fc0df", "icon": "https://cdn-app.pipispy.com/15b5139d7abb7892a0624fe0d96b3286.jpg", "region": [ "US", "AU", "CA", "EG", "GB", "BR", "PE", "MX", "FR", "SA", "MY", "JP", "VN", "SG", "IT", "DE", "AE", "PT", "IE", "NL", "PH", "ID", "IN", "ES", "TW", "TR" ], "app_name": "TikTok - Videos, Shop & LIVE", "app_category": { "id": "id36", "name": "App", "type": "app", "app_system": "ios", "children": [ { "id": "id6016", "name": "Entertainment", "type": "app", "app_system": "ios" }, { "id": "id6008", "name": "Photo & Video", "type": "app", "app_system": "ios" } ] }, "app_rate": { "score": 4.7, "count": 18153387 }, "app_type": "app", "app_store": "apple", "app_download_count": 99000000, "app_comment_count": 18153387, "play_count": 49774290, "video_count": 67, "digg_count": 4084565, "put_day": 2627, "found_time": 1616402946, "latest_found_time": 1751806943, "is_collection": false, "last_month_revenue": { "unit": "cent", "currency": "USD", "type": "currency", "value": 15300000000 }, "play_count_growth_rate": 0.0474, "digg_growth_rate": 0.7988, "latest_download_count": 6000000, "app_dev_info": { "website_url": "http://www.tiktok.com", "name": "TikTok Ltd.", "icon": "https://cdn-app.pipispy.com/15b5139d7abb7892a0624fe0d96b3286.jpg", "id": "1322881000", "email": "", "url": "https://apps.apple.com/us/developer/tiktok-ltd/id1322881000" }, "created_time": 1396411200 } ], "page": { "total_count": 5441, "page_count": 273, "current_page": 1, "page_size": 20, "is_next": true } }, "version": "v1", "timestamp": null, "sign": null, "remaining_credits": 9980, "consumed_credits": 20, "success": true, "fail": false } ``` ## 错误码说明 | 错误码 | 描述 | | ------ | --------------------- | | 200 | 成功 | | 400 | 请求参数错误 | | 401 | 未授权 - API 密钥无效 | | 500 | 服务器内部错误 |