# App 列表接口 ## 接口信息 - **接口名称**: 获取 App 列表 - **请求方法**: POST - **接口地址**: `/open-api/v1/data` - **接口路径**: `/v3/api/open/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/app/list" | 是 | | | params | object | 接口入参对象 | 见参数列表 | 是 | | ### 参数列表 (params 对象) | 参数名 | 类型 | 描述 | 示例 | 必填 | 默认值 | | --------------------------------- | ------- |-----------------------------------------------------------------------------------------------------------------------| --------------- | ---- | ------ | | current_page | integer | 当前页码 | 1 | 是 | | | page_size | integer | 每页数据量 | 10 | 是 | | | plat_type | integer | 平台类型 (0:全部 1:tiktok 2:facebook) | 1 | 是 | | | search_type | integer | 搜索类型 (1:关键词 2:App 名称 3:App 描述 4:开发者名称) | 1 | 是 | | | sort | integer | 排序字段 (9:广告结束日期, 8:广告开始日期, 1:App创建时间, 2:评论数, 3:评分, 4:广告数, 5:广告播放, 6-点赞数, 7-投放天数, 10-总安装数, 11-月安装数, 12-月收入额(USD), 13-红人数) | 1 | 是 | | | sort_type | string | 排序方式 (asc:升序 desc:降序) | "desc" | 是 | | | time | long | 时间范围 (0:全部 1:昨天 7:近7天 30:近30天 90:近90天) | 7 | 是 | | | app_category | string | App 分类，支持多个，字符串拼接 | "id6003,id6023" | 否 | | | app_comment_count_max | long | App 评论数最大值 | 10000 | 否 | | | app_comment_count_min | long | App 评论数最小值 | 1000 | 否 | | | app_create_time_end | long | App创建时间，App 创建时间结束(秒) | 1643673600 | 否 | | | app_create_time_start | long | App创建时间, App 创建时间开始(秒) | 1640995200 | 否 | | | app_download_count_max | long | 总安装数, App 下载数最大值 | 10000000 | 否 | | | app_download_count_min | long | 总安装数, App 下载数最小值 | 1000000 | 否 | | | app_rating_max | double | App 评分最大值 | 5.0 | 否 | | | app_rating_min | double | App 评分最小值 | 4.0 | 否 | | | app_system | string | App 系统 (ios/android) | "ios" | 否 | | | app_type | string | App 类型 (app/game) | "app" | 否 | | | digg_count_max | long | 点赞数最大值 | 100000 | 否 | | | digg_count_min | long | 点赞数最小值 | 10000 | 否 | | | found_time_end | long | 广告开始日期, 首次发现时间结束(秒) | 1643673600 | 否 | | | found_time_start | long | 广告开始日期, 首次发现时间开始(秒) | 1640995200 | 否 | | | keyword | string | 搜索关键词 | "MercadoLibre" | 否 | | | last_month_app_download_count_max | long | 月安装数, 上个月 App 下载数最大值 | 100000 | 否 | | | last_month_app_download_count_min | long | 月安装数, 上个月 App 下载数最小值 | 10000 | 否 | | | last_month_revenue_max | double | 月收入额(USD), 上个月收入最大值(USD) | 10000.0 | 否 | | | last_month_revenue_min | double | 月收入额(USD), 上个月收入最小值(USD) | 1000.0 | 否 | | | latest_found_time_end | long | 广告结束日期, 最近发现时间结束(秒) | 1643673600 | 否 | | | latest_found_time_start | long | 广告结束日期, 最近发现时间开始(秒) | 1640995200 | 否 | | | play_count_max | long | 广告播放，播放数最大值 | 10000000 | 否 | | | play_count_min | long | 广告播放，播放数最小值 | 1000000 | 否 | | | popular_person_count_max | long | 红人数最大值 | 100 | 否 | | | popular_person_count_min | long | 红人数最小值 | 10 | 否 | | | put_day_max | long | 投放天数最大值 | 30 | 否 | | | put_day_min | long | 投放天数最小值 | 1 | 否 | | | region | string | 国家/地区 | "BR,TW,MX" | 否 | | | video_count_max | long | 广告数最大值 | 100 | 否 | | | video_count_min | long | 广告数最小值 | 10 | 否 | | ### 请求示例 ```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/app/list", "params": { "current_page": 1, "page_size": 10, "plat_type": 1, "search_type": 1, "sort": 1, "sort_type": "desc", "time": 7, "keyword": "MercadoLibre", "app_type": "app", "app_system": "ios", "app_category": "id6003,id6023", "region": "BR,TW,MX", "app_rating_min": 4.0, "app_rating_max": 5.0, "app_download_count_min": 1000000, "app_download_count_max": 10000000 } }' ``` ## 响应参数 ### 响应体结构 ```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** | string/null | 时间戳 | | **sign** | string/null | 签名 | | **remaining_credits** | Long | 当前请求后的剩余可用积分 | | **consumed_credits** | Long | 本次请求消耗的积分 | | **success** | boolean | 请求是否成功 | | **fail** | boolean | 请求是否失败 | ##### 数据对象字段 (data) | 字段名 | 类型 | 描述 | | -------- | ------------- | -------- | | **data** | array[object] | App 列表 | | **page** | object | 分页信息 | ##### 列表项字段 | 字段名 | 类型 | 描述 | | ----------------------------- | ------------- | ------------------------------ | | id | string | App 外部 ID | | platform | array[string] | 广告平台列表 (tiktok/facebook) | | app_name | string | App 名称 | | created_time | number | App 创建时间(时间戳) | | icon | string | App 图标 URL | | app_system | string | App 系统类型 (ios/android) | | app_type | string | App 类型 (app/game) | | app_store | string | App 商店 (apple/google) | | app_download_count | number | App 下载次数 | | app_comment_count | number | App 评论数量 | | play_count | number | 广告播放次数 | | video_count | number | 广告视频数量 | | digg_count | number | 广告点赞数量 | | put_day | number | 广告投放天数 | | found_time | number | 首次发现时间(时间戳) | | latest_found_time | number | 最近发现时间(时间戳) | | is_collection | boolean | 是否已收藏 | | last_month_app_download_count | number | 上个月 App 下载次数 | | popular_person_count | number | 红人数量 | | region | array[string] | 地区信息列表 | | app_category | object | App 分类信息 | | app_rate | object | App 评分信息 | | last_month_revenue | object | 上月收入信息 | | latest_data | array[object] | 最新数据列表 | | app_dev_info | object | App 开发者信息 | ##### App 分类对象字段 (app_category) | 字段名 | 类型 | 描述 | | ---------- | ------------- | ---------------------- | | id | string | 分类 ID | | name | string | 分类名称 | | type | string | 分类类型 (app/game) | | app_system | string | App 系统 (ios/android) | | children | array[object] | 子分类列表 | ##### 子分类对象字段 (children) | 字段名 | 类型 | 描述 | | ---------- | ------ | ---------------------- | | id | string | 子分类 ID | | name | string | 子分类名称 | | type | string | 子分类类型 (app/game) | | app_system | string | App 系统 (ios/android) | ##### App 评分对象字段 (app_rate) | 字段名 | 类型 | 描述 | | ------ | ------ | -------- | | score | number | 评分分数 | | count | number | 评分数量 | ##### 上月收入对象字段 (last_month_revenue) | 字段名 | 类型 | 描述 | | -------- | ------ | --------------- | | unit | string | 单位 (cent) | | currency | string | 货币类型 (USD) | | type | string | 类型 (currency) | | value | number | 收入金额(分) | ##### 最新数据对象字段 (latest_data) | 字段名 | 类型 | 描述 | | -------- | ------ | ------------------------------ | | video_id | string | 视频 ID | | platform | number | 平台类型 (1:tiktok 2:facebook) | | url | string | 视频封面 URL | | count | number | 播放次数 | ##### App 开发者信息对象字段 (app_dev_info) | 字段名 | 类型 | 描述 | | ------ | ------ | ---------- | | id | string | 开发者 ID | | name | string | 开发者名称 | ##### 分页信息字段 (page) | 字段名称 | 类型 | 描述 | | ------------ | ------- | ------------ | | total_count | number | 总记录数 | | page_count | number | 总页数 | | current_page | number | 当前页码 | | page_size | number | 每页大小 | | is_next | boolean | 是否有下一页 | ### 响应示例 ```json { "code": 200, "message": "success", "data": { "data": [ { "platform": ["tiktok"], "id": "87f57e4b74b194d57356", "icon": "https://cdn-app.pipispy.com/28a87cbcf0d6e412064780e89b3f02da.jpg", "region": ["BR", "TW"], "app_name": "Mercado Libre: Compras Online", "app_category": { "children": [ { "name": "Shopping", "app_system": "ios", "id": "id6024", "type": "app" }, { "name": "Lifestyle", "app_system": "ios", "id": "id6012", "type": "app" } ], "name": "App", "app_system": "ios", "id": "id36", "type": "app" }, "app_rate": { "score": 4.8, "count": 321513 }, "created_time": 1315540800, "app_system": "ios", "app_type": "app", "app_store": "apple", "app_download_count": 13000000, "app_comment_count": 321513, "play_count": 624429116, "video_count": 15331, "digg_count": 1897788, "put_day": 1044, "found_time": 1662073352, "latest_found_time": 1752204713, "is_collection": false, "last_month_revenue": { "unit": "cent", "currency": "USD", "type": "currency", "value": 100000 }, "latest_data": [ { "platform": 1, "url": "https://cdn-video.pipispy.com/cover_645e142802a755d4cc01.jpg", "count": 8606, "video_id": "645e142802a755d4cc01" } ], "region": ["BR", "TW"], "app_dev_info": { "id": "463624855", "name": "MercadoLibre" }, "last_month_app_download_count": 1000000, "popular_person_count": 0 } ], "page": { "total_count": 10000, "page_count": 500, "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 | 服务器内部错误 |