# 店铺广告文案分析接口

本文档包含两个接口：TikTok 平台广告文案分析接口和 Facebook 平台广告文案分析接口。

---

## 一、TikTok 平台广告文案分析接口

### 接口信息

- **接口名称**: TikTok 平台广告文案分析接口
- **请求方法**: POST
- **接口地址**: `/open-api/v1/data`
- **接口路径**: `/v3/api/open/store/tiktok/ad-copy-analysis`
- **接口描述**:
    - 查询指定店铺在 TikTok 平台的广告文案统计分析数据
    - 按广告名和文案内容聚合，统计每个文案组合的使用次数和播放量
    - 支持按播放次数、广告数量排序
    - 帮助分析店铺在 TikTok 平台使用的高效文案组合
    - 价格说明: `免费`

**请求头:**

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

### 请求参数

#### 请求结构

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

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

| 参数名       | 类型    | 必填  | 描述                                                         |
| ------------ | ------- | ----- | ------------------------------------------------------------ |
| id           | string  | true  | 店铺 ID 为 13 位字符串（例如：`c2d5b2547218a`），对应店铺榜单列表接口返回结果中的 `store_id` 字段 |
| current_page | integer | false | 当前页码，默认为1                                            |
| page_size    | integer | false | 每页数量，默认为10                                           |
| sort_key     | string  | false | 排序字段：play_count-播放次数，ad_count-广告数量，默认为play_count |
| sort_type    | string  | false | 排序方式：desc-降序，asc-升序，默认为desc                    |

#### 请求示例

```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/store/tiktok/ad-copy-analysis",
    "params": {
      "id": "c2d5b2547218a",
      "current_page": 1,
      "page_size": 10,
      "sort_key": "play_count",
      "sort_type": "desc"
    }
  }'
```

### 响应参数

#### 响应体结构

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "tikTok_copy_analysis": [
      {
        "ad_name": "Summer Fashion Collection",
        "copywriter": "Get 50% OFF on all summer items! Limited time offer 🔥",
        "ad_count": 25,
        "play_count": 5280000
      },
      {
        "ad_name": "Fitness Tracker Pro",
        "copywriter": "Track your health goals with our smart fitness tracker ⭐",
        "ad_count": 18,
        "play_count": 3850000
      }
    ],
    "current_page": 1,
    "page_size": 10,
    "total": 156,
    "page_count": 16
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "fail": false,
  "success": true
}
```

#### 响应字段说明

| 字段名    | 类型    | 描述                     |
| --------- | ------- | ------------------------ |
| code      | Integer | 响应状态码，200 表示成功 |
| message   | String  | 响应消息                 |
| data      | Object  | 响应数据                 |
| version   | String  | API 版本                 |
| timestamp | String  | 响应时间戳               |
| sign      | String  | 响应签名                 |
| remaining_credits | Long    | 当前请求后的剩余可用积分 |
| consumed_credits  | Long    | 本次请求消耗的积分 |
| success   | Boolean | 请求是否成功             |
| fail      | Boolean | 请求是否失败             |

#### 响应结果信息字段

| 字段名               | 类型          | 描述                   |
| -------------------- | ------------- | ---------------------- |
| tikTok_copy_analysis | Array[Object] | TikTok文案分析数据列表 |
| current_page         | Integer       | 当前页码               |
| page_size            | Integer       | 每页数量               |
| total                | Long          | 总记录数               |
| page_count           | Integer       | 总页数                 |

#### tikTok_copy_analysis 数组元素结构

| 字段名      | 类型   | 描述                                   |
| ----------- | ------ | -------------------------------------- |
| ad_name     | String | 广告名称                               |
| copywriter  | String | 广告文案内容                           |
| ad_count    | Long   | 使用该广告名和文案组合的广告数量       |
| play_count  | Long   | 使用该广告名和文案组合的总播放次数     |

#### 响应示例

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "tikTok_copy_analysis": [
      {
        "ad_name": "Summer Fashion Collection",
        "copywriter": "🔥 Get 50% OFF on all summer items! Limited time offer. Shop now and save big on trendy outfits!",
        "ad_count": 25,
        "play_count": 5280000
      },
      {
        "ad_name": "Fitness Tracker Pro",
        "copywriter": "⭐ Track your health goals with our smart fitness tracker. Monitor steps, calories, heart rate & more!",
        "ad_count": 18,
        "play_count": 3850000
      },
      {
        "ad_name": "Smart Home Camera",
        "copywriter": "🏠 Protect your home 24/7 with HD camera. Motion detection, night vision, easy setup!",
        "ad_count": 15,
        "play_count": 2920000
      },
      {
        "ad_name": "Wireless Earbuds",
        "copywriter": "🎵 Premium sound quality meets comfort. Noise cancellation, 30hr battery life. Order today!",
        "ad_count": 12,
        "play_count": 2450000
      }
    ],
    "current_page": 1,
    "page_size": 10,
    "total": 156,
    "page_count": 16
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "fail": false,
  "success": true
}
```

### 错误码说明

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

### 使用说明

1. **数据聚合维度**：
   - 按照"广告名 + 文案内容"的组合进行聚合统计
   - 相同广告名和文案内容的广告会被合并统计

2. **排序字段**：
   - `play_count`：按总播放次数排序，适合找出高曝光的文案组合
   - `ad_count`：按广告数量排序，适合找出复用率高的文案组合

3. **应用场景**：
   - 分析哪些广告名和文案组合获得更多播放量
   - 识别店铺在 TikTok 平台的常用文案策略
   - 优化广告文案，提升投放效果

---

## 二、Facebook 平台广告文案分析接口

### 接口信息

- **接口名称**: Facebook 平台广告文案分析接口
- **请求方法**: POST
- **接口地址**: `open-api/v1/data`
- **接口路径**: `/v3/api/open/store/facebook/ad-copy-analysis`
- **接口描述**:
    - 查询指定店铺在 Facebook 平台的广告文案统计分析数据
    - 按广告名和文案内容聚合，统计每个文案组合的使用次数和点赞数
    - 支持按点赞数、广告数量排序
    - 帮助分析店铺在 Facebook 平台使用的高互动文案组合
    - 价格说明: `免费`

**请求头:**

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

### 请求参数

#### 请求结构

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

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

| 参数名       | 类型    | 必填  | 描述                                                         |
| ------------ | ------- | ----- | ------------------------------------------------------------ |
| id           | string  | true  | 店铺 ID 为 13 位字符串（例如：`c2d5b2547218a`），对应店铺榜单列表接口返回结果中的 `store_id` 字段 |
| current_page | integer | false | 当前页码，默认为1                                            |
| page_size    | integer | false | 每页数量，默认为10                                           |
| sort_key     | string  | false | 排序字段：digg_count-点赞数，ad_count-广告数量，默认为ad_count |
| sort_type    | string  | false | 排序方式：desc-降序，asc-升序，默认为desc                    |

#### 请求示例

```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/store/facebook/ad-copy-analysis",
    "params": {
      "id": "12345",
      "current_page": 1,
      "page_size": 10,
      "sort_key": "digg_count",
      "sort_type": "desc"
    }
  }'
```

### 响应参数

#### 响应体结构

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "facebook_copy_analysis": [
      {
        "ad_name": "Summer Fashion Collection",
        "copywriter": "Get 50% OFF on all summer items! Limited time offer 🔥",
        "ad_count": 20,
        "digg_count": 125000
      },
      {
        "ad_name": "Fitness Tracker Pro",
        "copywriter": "Track your health goals with our smart fitness tracker ⭐",
        "ad_count": 16,
        "digg_count": 98000
      }
    ],
    "current_page": 1,
    "page_size": 10,
    "total": 89,
    "page_count": 9
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "fail": false,
  "success": true
}
```

#### 响应字段说明

| 字段名    | 类型    | 描述                     |
| --------- | ------- | ------------------------ |
| code      | Integer | 响应状态码，200 表示成功 |
| message   | String  | 响应消息                 |
| data      | Object  | 响应数据                 |
| version   | String  | API 版本                 |
| timestamp | String  | 响应时间戳               |
| sign      | String  | 响应签名                 |
| success   | Boolean | 请求是否成功             |
| fail      | Boolean | 请求是否失败             |

#### 响应结果信息字段

| 字段名                 | 类型          | 描述                     |
| ---------------------- | ------------- | ------------------------ |
| facebook_copy_analysis | Array[Object] | Facebook文案分析数据列表 |
| current_page           | Integer       | 当前页码                 |
| page_size              | Integer       | 每页数量                 |
| total                  | Long          | 总记录数                 |
| page_count             | Integer       | 总页数                   |

#### facebook_copy_analysis 数组元素结构

| 字段名      | 类型   | 描述                                   |
| ----------- | ------ | -------------------------------------- |
| ad_name     | String | 广告名称                               |
| copywriter  | String | 广告文案内容                           |
| ad_count    | Long   | 使用该广告名和文案组合的广告数量       |
| digg_count  | Long   | 使用该广告名和文案组合的总点赞数       |

#### 响应示例

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "facebook_copy_analysis": [
      {
        "ad_name": "Summer Fashion Collection",
        "copywriter": "🎁 Special Promotion! Get 50% OFF on all summer fashion items. Limited time only. Shop before it's gone!",
        "ad_count": 20,
        "digg_count": 125000
      },
      {
        "ad_name": "Fitness Tracker Pro",
        "copywriter": "🌟 Track your health goals with our smart fitness tracker. Monitor steps, calories, heart rate and sleep quality!",
        "ad_count": 16,
        "digg_count": 98000
      },
      {
        "ad_name": "Smart Home Camera",
        "copywriter": "💯 Protect your home 24/7 with HD security camera. Motion detection, night vision, two-way audio. Easy setup!",
        "ad_count": 14,
        "digg_count": 87500
      },
      {
        "ad_name": "Wireless Earbuds",
        "copywriter": "🚀 Premium sound quality with active noise cancellation. 30-hour battery life. Free shipping worldwide!",
        "ad_count": 11,
        "digg_count": 76000
      }
    ],
    "current_page": 1,
    "page_size": 10,
    "total": 89,
    "page_count": 9
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "fail": false,
  "success": true
}
```

### 错误码说明

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

### 使用说明

1. **数据聚合维度**：
   - 按照"广告名 + 文案内容"的组合进行聚合统计
   - 相同广告名和文案内容的广告会被合并统计

2. **排序字段**：
   - `digg_count`：按总点赞数排序，适合找出高互动的文案组合
   - `ad_count`：按广告数量排序，适合找出复用率高的文案组合

3. **应用场景**：
   - 分析哪些广告名和文案组合获得更多用户互动
   - 识别店铺在 Facebook 平台的常用文案策略
   - 优化广告文案，提升用户参与度