# 视频自然流量列表接口

## 接口信息

- **接口名称**: 获取视频自然流量列表
- **请求方法**: POST
- **接口地址**: `/open-api/v1/data`
- **接口路径**: `/v4/api/open/video/list`
- **接口描述**: 根据过滤条件获取视频自然流量列表信息，支持分页查询
- **价格说明**: 获取一条数据结果消耗1 credit

**请求头:**

- Content-Type: application/json
- Accept: application/json

## 请求参数

### 请求结构

| 参数名 | 类型   | 描述                        | 示例                      | 必填 | 默认值 |
| ------ | ------ | --------------------------- | ------------------------- | ---- | ------ |
| key    | string | 用户申请的外部 api 请求 key | "your_api_key_here"       | 是   |        |
| uri    | string | 接口路径                    | "/v4/api/open/video/list" | 是   |        |
| params | object | 接口入参对象                | 见参数列表                | 是   |        |

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

| 参数名             | 类型    | 必填 | 描述                                                                                                                               |
| ------------------ | ------- | ---- |----------------------------------------------------------------------------------------------------------------------------------|
| search_type        | Integer | 否   | 搜索类型：1-综合搜索（默认），2-视频文案搜索，3-视频主播名称搜索，4-视频链接搜索                                                                                     |
| keyword            | String  | 否   | 搜索关键词，根据 search_type 在不同字段中进行模糊匹配搜索                                                                                              |
| type               | Integer | 否   | 视频类型：1-自然流量视频，2-TikTok 小店视频                                                                                                      |
| region             | Array   | 否   | 国家/地区，地区列表，支持多个地区筛选，如：["US", "CN", "JP"]                                                                                         |
| create_time_start  | Long    | 否   | 时间，视频创建时间开始时间戳（秒），用于筛选指定时间范围内创建的视频                                                                                               |
| create_time_end    | Long    | 否   | 时间，视频创建时间结束时间戳（秒），用于筛选指定时间范围内创建的视频                                                                                               |
| follower_count_min | Long    | 否   | 创作者丝数最小值，用于筛选粉丝数大于等于此值的主播发布的视频                                                                                                   |
| follower_count_max | Long    | 否   | 创作者丝数最大值，用于筛选粉丝数小于等于此值的主播发布的视频                                                                                                   |
| play_count_min     | Long    | 否   | 视频播放数最小值，用于筛选播放数大于等于此值的视频                                                                                                        |
| play_count_max     | Long    | 否   | 视频播放数最大值，用于筛选播放数小于等于此值的视频                                                                                                        |
| digg_count_min     | Long    | 否   | 视频点赞数最小值，用于筛选点赞数大于等于此值的视频                                                                                                        |
| digg_count_max     | Long    | 否   | 视频点赞数最大值，用于筛选点赞数小于等于此值的视频                                                                                                        |
| digg_play_rate_min | Double  | 否   | 点赞率最小值，用于筛选点赞播放比大于等于此值的视频（点赞数/播放数）                                                                                               |
| digg_play_rate_max | Double  | 否   | 点赞率最大值，用于筛选点赞播放比小于等于此值的视频（点赞数/播放数）                                                                                               |
| comment_count_min  | Long    | 否   | 视频评论数最小值，用于筛选评论数大于等于此值的视频                                                                                                        |
| comment_count_max  | Long    | 否   | 视频评论数最大值，用于筛选评论数小于等于此值的视频                                                                                                        |
| share_count_min    | Long    | 否   | 视频分享数最小值，用于筛选分享数大于等于此值的视频                                                                                                        |
| share_count_max    | Long    | 否   | 视频分享数最大值，用于筛选分享数小于等于此值的视频                                                                                                        |
| current_page       | Integer | 是   | 当前页码，从 1 开始，用于分页查询                                                                                                               |
| page_size          | Integer | 是   | 每页大小，每页返回的数量                                                                                                                   |
| sort_key           | String  | 否   | 排序字段：create_time（创建时间）、play_count（播放数）、digg_count（点赞数）、comment_count（评论数）、share_count（分享数）、digg_play_rate（点赞播放比），默认为 create_time |
| sort_type          | String  | 否   | 排序方式：asc-升序排列，desc-降序排列（默认）                                                                                                      |
| platform           | String  | 否   | 平台类型，用于筛选特定平台类型的落地页，如：shopify、woocommerce、shoplazza、magento、wix、shopline、squarespace、shopyy                                                                                                |

### 请求示例

```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": "/v4/api/open/video/list",
    "params": {
      "search_type": 1,
      "keyword": "fashion",
      "type": 1,
      "region": ["US", "CA"],
      "create_time_start": 1640995200,
      "create_time_end": 1643673600,
      "follower_count_min": 10000,
      "follower_count_max": 1000000,
      "play_count_min": 1000,
      "play_count_max": 1000000,
      "digg_count_min": 100,
      "digg_count_max": 50000,
      "digg_play_rate_min": 0.01,
      "digg_play_rate_max": 0.1,
      "comment_count_min": 10,
      "comment_count_max": 1000,
      "share_count_min": 5,
      "share_count_max": 500,
      "current_page": 1,
      "page_size": 20,
      "sort_key": "play_count",
      "sort_type": "desc",
      "platform": "tiktok_shop"
    }
  }'
```

## 响应参数

### 响应体结构

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "data": [],
    "page": {}
  }
}
```

### 响应字段说明

| 字段名    | 类型    | 描述                     |
| --------- | ------- | ------------------------ |
| code      | Integer | 响应状态码，200 表示成功 |
| message   | String  | 响应消息                 |
| data      | Object  | 响应数据                 |
| data.data | Array   | 视频列表                 |
| data.page | Object  | 分页信息                 |

### 视频信息字段

| 字段名         | 类型    | 描述                                                 |
| -------------- | ------- | ---------------------------------------------------- |
| id             | String  | 视频唯一标识 ID                                      |
| video_url      | String  | 视频播放 URL，完整的视频播放链接地址                 |
| cover          | String  | 视频封面图片 URL，视频的封面图片链接地址             |
| duration       | Integer | 视频时长（秒），视频的总播放时长                     |
| play_count     | Long    | 播放次数，视频的总播放量                             |
| digg_count     | Long    | 点赞次数，视频获得的总点赞数                         |
| comment_count  | Long    | 评论次数，视频获得的总评论数                         |
| share_count    | Long    | 分享次数，视频被分享的总次数                         |
| create_time    | Long    | 视频创建时间戳（秒），视频在 TikTok 平台上的创建时间 |
| desc           | String  | 视频文案，视频的文字描述内容                         |
| app_image      | String  | 视频主播头像 URL，视频主播的头像图片链接地址         |
| nickname       | String  | 视频主播昵称，视频主播的显示昵称                     |
| follower_count | Long    | 视频主播粉丝数，视频主播的总粉丝数量                 |
| fetch_region   | String  | 数据获取地区，视频数据来源的地区标识                 |
| author_url     | String  | 视频主播主页 URL，视频主播的 TikTok 主页链接         |
| landing_page   | Array   | 落地页信息列表，视频关联的电商落地页信息             |
| products       | Array   | 商品信息列表，视频关联的商品详细信息                 |
| review_count   | Long    | 评论总数，视频的评论总数（包括回复）                 |
| tiktok_url     | String  | TikTok 视频链接，视频在 TikTok 平台上的完整链接地址  |
| is_collection  | Boolean | 是否已收藏，当前用户是否已收藏该视频                 |
| type           | Integer | 视频类型，1-普通视频，其他值-特殊类型视频            |
| carousel       | Array   | 轮播图列表，视频的轮播图片信息                       |
| shop_flag      | Integer | 店铺标识，1-普通视频，2-电商视频（tiktok_shop）      |

### 商品信息字段 (products 数组)

| 字段名   | 类型   | 描述                                       |
| -------- | ------ | ------------------------------------------ |
| image    | String | 商品图片 URL，商品的展示图片链接           |
| name     | String | 商品名称，商品的标题名称                   |
| currency | String | 货币类型，商品价格的货币单位，如：USD、CNY |
| price    | Double | 商品价格，商品的销售价格                   |
| url      | String | 商品链接，商品的购买链接地址               |

### 落地页信息字段 (landing_page 数组)

| 字段名 | 类型   | 描述                                   |
| ------ | ------ | -------------------------------------- |
| type   | String | 落地页类型，如：tiktok_shop 等平台类型 |
| url    | String | 落地页 URL，实际的落地页链接地址       |

### 轮播图信息字段 (carousel 数组)

| 字段名 | 类型    | 描述                               |
| ------ | ------- | ---------------------------------- |
| type   | Integer | 轮播图类型，2-图片类型             |
| image  | String  | 轮播图片 URL，轮播图的图片链接地址 |

### 分页信息字段

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

## 响应示例

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "id": "507f1f77bcf86cd799439011",
        "video_url": "https://example.com/video.mp4",
        "cover": "https://example.com/cover.jpg",
        "duration": 30,
        "play_count": 500000,
        "digg_count": 25000,
        "comment_count": 1200,
        "share_count": 800,
        "create_time": 1640995200,
        "desc": "时尚穿搭分享，超好看的搭配推荐",
        "app_image": "https://example.com/avatar.jpg",
        "nickname": "时尚达人",
        "follower_count": 500000,
        "fetch_region": "US",
        "author_url": "https://www.tiktok.com/@fashion_expert",
        "landing_page": [
          {
            "type": "tiktok_shop",
            "url": "https://shop.tiktok.com/product/123"
          }
        ],
        "products": [
          {
            "image": "https://example.com/product.jpg",
            "name": "时尚运动鞋",
            "currency": "USD",
            "price": 99.99,
            "url": "https://shop.tiktok.com/product/123"
          }
        ],
        "review_count": 1500,
        "tiktok_url": "https://www.tiktok.com/@fashion_expert/video/507f1f77bcf86cd799439011",
        "is_collection": false,
        "type": 1,
        "carousel": [
          {
            "type": 2,
            "image": "https://example.com/carousel1.jpg"
          }
        ],
        "shop_flag": 2
      }
    ],
    "page": {
      "total_count": 1250,
      "page_count": 63,
      "current_page": 1,
      "page_size": 20,
      "is_next": true
    }
  }
}
```

## 错误码说明

| 错误码 | 描述           |
| ------ | -------------- |
| 200    | 成功           |
| 400    | 请求参数错误   |
| 500    | 服务器内部错误 |

## 注意事项

1. 页码参数从 1 开始
2. 排序字段支持多种选项：create_time、play_count、digg_count、comment_count、share_count、digg_play_rate
3. 搜索类型支持 4 种模式，默认为综合搜索
4. 时间戳使用秒级时间戳
5. 地区参数支持多个地区数组格式
6. 点赞播放比为点赞数除以播放数的比值
7. 视频类型 1 为自然流量视频，2 为电商视频
8. 店铺标识 1 为普通视频，2 为电商视频