# 广告产品榜单列表接口

## 接口信息

- **接口名称**: 获取广告产品榜单列表
- **请求方法**: POST
- **接口地址**: `/open-api/v1/data`
- **接口路径**: `/v3/api/open/rank/ad-product/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/list" | 是   |        |
| params | object | 接口入参对象                | 见参数列表                          | 是   |        |

### 请求体参数 (params 对象)

| 参数名           | 类型    | 必填 | 描述                                                      |
| ---------------- | ------- | ---- |---------------------------------------------------------|
| current_page     | Integer | 是   | 当前页码，分页查询的当前页数，从 1 开始                                   |
| page_size        | Integer | 是   | 每页大小，分页查询的每页记录数                                         |
| sort_key         | String  | 是   | 排序字段：count_growth-播放量增长，growth_rate-增长率，video_count-广告数 |
| sort_type        | String  | 是   | 排序类型：desc-降序，asc-升序                                     |
| time             | Integer | 是   | 时间：日期开始的零点时间，如天则传当日零点，周则传当周开始零点，月则传当月开始零点               |
| type             | Integer | 是   | 时间类型：1-日榜，2-周榜，3-月榜                                     |
| 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  | 否   | 国家/地区，投放地区，多个用逗号分隔                                      |

### 请求示例

```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/list",
    "params": {
      "current_page": 1,
      "page_size": 20,
      "sort_key": "count_growth",
      "sort_type": "desc",
      "time": 1,
      "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  | 响应时间戳（可为空）     |
| sign      | String  | 响应签名（可为空）       |
| remaining_credits | Long    | 当前请求后的剩余可用积分 |
| consumed_credits  | Long    | 本次请求消耗的积分 |
| success   | Boolean | 请求是否成功             |
| fail      | Boolean | 请求是否失败             |

### 产品榜单信息字段

| 字段名        | 类型    | 描述                                  |
| ------------- | ------- | ------------------------------------- |
| id            | String  | 产品唯一标识 ID                       |
| image         | String  | 产品主图片 URL                        |
| title         | String  | 产品标题                              |
| currency      | String  | 产品价格货币类型                      |
| price         | Double  | 产品价格                              |
| usd_price     | Double  | 产品美元价格                          |
| min_cpm       | Double  | 最小 CPM（千次展示成本），可为空      |
| max_cpm       | Double  | 最大 CPM（千次展示成本），可为空      |
| count_growth  | Long    | 数据增长量（播放量增长）              |
| video_count   | Long    | 视频数量                              |
| growth_rate   | Double  | 增长率                                |
| is_collection | Boolean | 是否已收藏                            |
| platform      | String  | 平台标识（如："shopify"、"shopline"） |

### 分页信息字段

| 字段名       | 类型    | 描述         |
| ------------ | ------- | ------------ |
| total_count  | Long    | 总记录数     |
| page_count   | Long    | 总页数       |
| current_page | Long    | 当前页码     |
| page_size    | Long    | 每页记录数   |
| is_next      | Boolean | 是否有下一页 |

## 响应示例

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "id": "67a2d72695f8665640581129",
        "image": "https://cdn-product.pipispy.com/pimg_7560a46afc0d626f9f70.png",
        "title": "Hermès Avalon Throw Blanket",
        "currency": "USD",
        "price": 149.99,
        "platform": "shopify",
        "usd_price": 149.99,
        "count_growth": 175621,
        "video_count": 14,
        "growth_rate": 0.2957,
        "is_collection": false
      },
      {
        "id": "674bf2ec6b331c3c04ad0a9a",
        "image": "https://cdn-product.pipispy.com/pimg_a15c12f7d699c40dc6d5.jpg",
        "title": "Compression Backpack",
        "currency": "INR",
        "price": 9499.0,
        "platform": "shopify",
        "usd_price": 110.8,
        "count_growth": 44047,
        "video_count": 6,
        "growth_rate": 3.0072,
        "is_collection": false
      },
      {
        "id": "65c024af7ffbbd340830304e",
        "image": "https://cdn-product.pipispy.com/pimg_603e433b11adfc4d1107.jpg",
        "title": "Furry Dino Bear | Handmade Jointed Teddy Bear Gift-Getahug",
        "currency": "USD",
        "price": 12.98,
        "platform": "shopline",
        "usd_price": 12.98,
        "min_cpm": 864.23,
        "max_cpm": 3467.1,
        "count_growth": 33316,
        "video_count": 5,
        "growth_rate": 0.011,
        "is_collection": false
      }
    ],
    "page": {
      "total_count": 101654,
      "page_count": 5083,
      "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. min_cpm 和 max_cpm 字段可能为空值（null），表示该产品暂无 CPM 数据
8. platform 字段显示具体的电商平台名称，如"shopify"、"shopline"等
9. 响应中的 version 字段表示 API 版本，timestamp 和 sign 字段目前为 null
10. success 和 fail 字段用于标识请求处理状态