# 广告产品新品榜单列表接口 ## 接口信息 - **接口名称**: 获取广告产品新品榜单列表 - **请求方法**: 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"] | 否 | | ### 请求示例 ```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/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" } }' ``` ## 响应参数 ### 响应体结构 ```json { "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 | 是否有下一页 | ## 响应示例 ```json { "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. 页码参数从 1 开始 2. 排序字段支持多种选项：count_growth、growth_rate、video_count 3. 时间范围筛选支持多种预定义时间段 4. 平台筛选支持 TikTok 和 Facebook 平台 5. 地区参数支持多个地区用逗号分隔 6. 增长率以百分比值计算 7. 部分字段可能为空值（如 currency、usd_price、min_cpm、max_cpm） 8. 平台标识目前主要返回"shopify" 9. 图片 URL 使用 CDN 域名 cdn-product.pipispy.com 10. 产品 ID 为 24 位 MongoDB ObjectId 格式