# 店铺 Meta 广告资料库最常用广告文案列表接口

## 接口信息

- **接口名称**: 获取店铺最常用广告文案列表
- **请求方法**: POST
- **接口地址**: `/open-api/v1/data`
- **接口路径**: `/v3/api/open/ppspy/pp-stores/ad-content/most-used`
- **接口描述**: 获取指定店铺在Meta广告资料库中使用频率最高的广告文案列表，包括文案内容、使用该文案的广告数量、活跃广告数、投放时间等信息，帮助分析店铺的核心广告文案策略
- **价格说明**: `免费`
- 
**请求头:**

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

## 请求参数

### 请求结构

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

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

| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| id | String | 是 | 店铺唯一标识ID，为13位字符串（例如：`c2d5b2547218a`），对应店铺榜单列表接口返回结果中的 `store_id` 字段 |
| order_by | String | 否 | 排序字段。可选值：`ad_count`-按广告数量排序，`active_ad_count`-按活跃广告数排序，`latest_ad_started_at`-按最近广告日期排序。默认值：`ad_count` |
| direction | String | 否 | 排序方式。可选值：`desc`-降序（从大到小/从新到旧），`asc`-升序（从小到大/从旧到新）。默认值：`desc` |
| page_size | Long | 否 | 每页记录数，指定单页返回的文案数量。默认值：20 |
| current_page | Long | 否 | 当前页码，页码从1开始。默认值：1 |

### 请求示例

```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/ppspy/pp-stores/ad-content/most-used",
    "params": {
        "id": "c2d5b2547218a",
        "order_by": "ad_count",
        "direction": "desc",
        "page_size": 20,
        "current_page": 1
    }
  }'
```

## 响应参数

### 响应体结构

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "current_page": 1,
    "data": [],
    "first_page_url": "",
    "from": 1,
    "is_logged_in": false,
    "last_page": 1,
    "last_page_url": "",
    "next_page_url": null,
    "path": "",
    "per_page": 20,
    "prev_page_url": null,
    "to": 20,
    "total": 100
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "success": true,
  "fail": false
}
```

### 响应字段说明

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

### 分页数据字段 (data.data)

| 字段名 | 类型 | 描述 |
| ------ | ---- | ---- |
| current_page | Long | 当前页码 |
| data | Array | 广告文案列表 |
| first_page_url | String | 第一页的URL地址 |
| from | Long | 起始记录位置（当前页第一条记录在总结果集中的位置） |
| is_logged_in | Boolean | 用户是否已登录，用于标识数据权限状态 |
| last_page | Long | 最后一页的页码（总页数） |
| last_page_url | String | 最后一页的URL地址 |
| next_page_url | String | 下一页的URL地址，如果没有下一页则为null |
| path | String | API请求路径 |
| per_page | Long | 每页记录数 |
| prev_page_url | String | 上一页的URL地址，如果没有上一页则为null |
| to | Long | 结束记录位置（当前页最后一条记录在总结果集中的位置） |
| total | Long | 总记录数 |

### 广告文案字段 (Datum)

| 字段名 | 类型 | 描述 |
| ------ | ---- | ---- |
| id | String | 文案记录唯一标识ID |
| ad_content_md5 | String | 广告文案内容的MD5哈希值，用于标识相同内容的文案 |
| ad_content | String | 广告文案内容 |
| ad_count | Long | 使用该文案的广告总数量，表示该文案被复用的次数 |
| active_ad_count | Long | 使用该文案的活跃广告数量（当前正在投放的广告数） |
| ad_started_at | Long | 该文案首次投放时间，Unix时间戳（秒级） |
| ad_ended_at | Long | 该文案最后一次投放结束时间，Unix时间戳（秒级） |
| active_days | Long | 该文案的累计投放天数 |
| latest_ad_started_at | Long | 使用该文案的最近一条广告的开始时间，Unix时间戳（秒级） |
| percentage | Double | 该文案占店铺所有文案的使用比例（0.0-1.0） |

## 响应示例

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "current_page": 1,
    "data": [
      {
        "id": "content_001",
        "ad_content_md5": "a1b2c3d4e5f6g7h8i9j0",
        "ad_content": "Shop now and get 50% off! Limited time offer. Free shipping on orders over $50. Don't miss out on this amazing deal!",
        "ad_count": 85,
        "active_ad_count": 23,
        "ad_started_at": 1680000000,
        "ad_ended_at": 1700000000,
        "active_days": 230,
        "latest_ad_started_at": 1699500000,
        "percentage": 0.125
      },
      {
        "id": "content_002",
        "ad_content_md5": "b2c3d4e5f6g7h8i9j0k1",
        "ad_content": "New arrivals! Check out our latest collection. Premium quality at affordable prices.",
        "ad_count": 62,
        "active_ad_count": 18,
        "ad_started_at": 1685000000,
        "ad_ended_at": 1699800000,
        "active_days": 170,
        "latest_ad_started_at": 1699200000,
        "percentage": 0.091
      },
      {
        "id": "content_003",
        "ad_content_md5": "c3d4e5f6g7h8i9j0k1l2",
        "ad_content": "Best seller! Thousands of 5-star reviews. Order yours today!",
        "ad_count": 48,
        "active_ad_count": 0,
        "ad_started_at": 1670000000,
        "ad_ended_at": 1695000000,
        "active_days": 290,
        "latest_ad_started_at": 1694500000,
        "percentage": 0.071
      }
    ],
    "first_page_url": "https://api.example.com/contents?page=1",
    "from": 1,
    "is_logged_in": false,
    "last_page": 10,
    "last_page_url": "https://api.example.com/contents?page=10",
    "next_page_url": "https://api.example.com/contents?page=2",
    "path": "https://api.example.com/contents",
    "per_page": 20,
    "prev_page_url": null,
    "to": 20,
    "total": 200
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "success": true,
  "fail": false
}
```

## 错误码说明

| 错误码 | 描述           |
| ------ | -------------- |
| 200    | 成功           |
| 400    | 请求参数错误   |
| 401    | 未授权         |
| 403    | 权限不足       |
| 500    | 服务器内部错误 |