广告产品新品榜单列表接口
接口信息
- 接口名称: 获取广告产品新品榜单列表
- 请求方法: POST
- 接口地址:
/open-api/v1/data
- 接口路径:
/v3/api/open/rank/ad-product-new/list
- 接口描述: 根据过滤条件获取广告产品新品榜单列表信息,支持分页
- 价格说明: 获取一条数据结果消耗1 credit
请求头:
- Content-Type: application/json
- Accept: application/json
请求参数
请求结构
| 参数名 |
类型 |
描述 |
示例 |
必填 |
默认值 |
| key |
string |
用户申请的外部 api 请求 key |
"your_api_key_here" |
是 |
|
| uri |
string |
接口路径 |
"/v3/api/open/rank/ad-product-new/list" |
是 |
|
| params |
object |
接口入参对象 |
见参数列表 |
是 |
|
请求体参数 (params 对象)
| 参数名 |
类型 |
必填 |
描述 |
| current_page |
Integer |
是 |
当前页码,分页查询的当前页数,从 1 开始 |
| found_time |
Double |
是 |
发现时间范围:0-默认,1-近3天,2-近7天,3-近1个月,4-近3个月,5-近6个月,6-总 |
| page_size |
Integer |
是 |
每页大小,分页查询的每页记录数 |
| sort_key |
String |
是 |
排序字段:count_growth-点赞数,growth_rate-增长率,video_count-广告数 |
| sort_type |
String |
是 |
排序类型:desc-降序,asc-升序 |
| type |
Integer |
是 |
时间类型:0-默认,1-24 小时,2-3 天,3-7 天 |
| count_growth_max |
Double |
否 |
点赞数,数据增长最大值(播放量增长),用于筛选增长量不超过指定值的产品 |
| count_growth_min |
Double |
否 |
点赞数,数据增长最小值(播放量增长),用于筛选增长量不低于指定值的产品 |
| growth_rate_max |
Double |
否 |
增长率,数据增长比例最大值,用于筛选增长率不超过指定值的产品 |
| growth_rate_min |
Double |
否 |
增长率,数据增长比例最小值,用于筛选增长率不低于指定值的产品 |
| plat_type |
Integer |
否 |
平台类型:0-全平台,1-TikTok,2-Facebook |
| region |
String |
否 |
国家/地区,投放地区,多个用逗号分隔 |
| shop_type |
string |
电商系统,"magento", "shopify", "shoplazza", "shopline", "shopyy", "squarespace", "wix", "woocommerce" |
["woocommerce"] |
请求示例
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/ad-product-new/list",
"params": {
"current_page": 1,
"found_time": 1,
"page_size": 20,
"sort_key": "count_growth",
"sort_type": "desc",
"type": 1,
"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": [],
"page": {}
},
"version": "v1",
"timestamp": null,
"sign": null,
"remaining_credits": 9980,
"consumed_credits": 20,
"success": true,
"fail": false
}
响应字段说明
| 字段名 |
类型 |
描述 |
| code |
Integer |
响应状态码,200 表示成功 |
| message |
String |
响应消息 |
| data |
Object |
响应数据 |
| data.data |
Array |
产品榜单列表 |
| data.page |
Object |
分页信息 |
| version |
String |
API 版本号 |
| timestamp |
String/Null |
时间戳 |
| sign |
String/Null |
签名信息 |
| remaining_credits |
Long |
当前请求后的剩余可用积分 |
| consumed_credits |
Long |
本次请求消耗的积分 |
| success |
Boolean |
请求是否成功 |
| fail |
Boolean |
请求是否失败 |
产品榜单信息字段
| 字段名 |
类型 |
描述 |
示例 |
| id |
String |
产品唯一标识 ID |
"6868c8124423dd56cf7ea285" |
| image |
String |
产品主图片 URL |
"https://cdn-product.pipispy.com/pimg_5207a34434df898bdaca.png" |
| title |
String |
产品标题 |
"Baby Hands & Feet Casting Kit" |
| currency |
String |
产品价格货币类型,可能为空 |
"USD", "BRL", "AUD", "EUR", "GBP", "JPY", "" |
| price |
Double |
产品价格 |
120.0, 137.9, 119.0 |
| usd_price |
Double |
产品美元价格,可能为空 |
120.0, 25.26, 77.78 |
| min_cpm |
Double |
最小 CPM(千次展示成本),可能为空 |
4712.15, 14031.55, 8670.1 |
| max_cpm |
Double |
最大 CPM(千次展示成本),可能为空 |
18890.6, 56126.19, 34680.38 |
| count_growth |
Long |
数据增长量(播放量增长) |
183674, 114088, 110683 |
| video_count |
Long |
视频数量 |
34, 8, 15 |
| growth_rate |
Double |
增长率(百分比值) |
16.9425, 1.8143, 611.5083 |
| is_collection |
Boolean |
是否已收藏 |
false |
| platform |
String |
平台标识 |
"shopify" |
分页信息字段
| 字段名 |
类型 |
描述 |
| total_count |
Long |
总记录数 |
| page_count |
Long |
总页数 |
| current_page |
Long |
当前页码 |
| page_size |
Long |
每页记录数 |
| is_next |
Boolean |
是否有下一页 |
响应示例
{
"code": 200,
"message": "success",
"data": {
"data": [
{
"id": "6868c8124423dd56cf7ea285",
"image": "https://cdn-product.pipispy.com/pimg_5207a34434df898bdaca.png",
"title": "Baby Hands & Feet Casting Kit",
"currency": "USD",
"price": 120.0,
"platform": "shopify",
"usd_price": 120.0,
"min_cpm": 4712.15,
"max_cpm": 18890.6,
"count_growth": 183674,
"video_count": 34,
"growth_rate": 16.9425,
"is_collection": false
},
{
"id": "68656c2a9a22ed62395b6d9f",
"image": "https://cdn-product.pipispy.com/pimg_8a1a4534450f949cd18c.png",
"title": "Kit Caterpillar - Bota Masculina em Couro Legítimo e Palmilha Ortopédica + Brindes Exclusivos",
"currency": "BRL",
"price": 137.9,
"platform": "shopify",
"usd_price": 25.26,
"min_cpm": 14031.55,
"max_cpm": 56126.19,
"count_growth": 114088,
"video_count": 8,
"growth_rate": 1.8143,
"is_collection": false
}
],
"page": {
"total_count": 37834,
"page_count": 1892,
"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 |
请求参数错误 |
| 500 |
服务器内部错误 |
注意事项
- 页码参数从 1 开始
- 排序字段支持多种选项:count_growth、growth_rate、video_count
- 时间范围筛选支持多种预定义时间段
- 平台筛选支持 TikTok 和 Facebook 平台
- 地区参数支持多个地区用逗号分隔
- 增长率以百分比值计算
- 部分字段可能为空值(如 currency、usd_price、min_cpm、max_cpm)
- 平台标识目前主要返回"shopify"
- 图片 URL 使用 CDN 域名 cdn-product.pipispy.com
- 产品 ID 为 24 位 MongoDB ObjectId 格式