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 |
|
请求示例
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"
}
}'
响应参数
响应体结构
{
"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 |
是否有下一页 |
响应示例
{
"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 |
服务器内部错误 |