# 店铺广告 Meta 广告资料库投放趋势分析接口

## 接口信息

- **接口名称**: 店铺广告 Meta 广告资料库投放趋势分析接口
- **请求方法**: POST
- **接口地址**: `/open-api/v1/data`
- **接口路径**: `/v3/api/open/ppspy/pp-stores/analysis/ad-trend`
- **接口描述**: 获取指定店铺在Meta广告资料库中的广告投放趋势数据，包括活跃广告数、广告总数、新增广告数的历史变化趋势
- **价格说明**: `免费`
- 
**请求头:**

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

## 请求参数

### 请求结构

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

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

| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| id | String | 是 | 店铺唯一标识ID，为13位字符串（例如：`c2d5b2547218a`），对应店铺榜单列表接口返回结果中的 `store_id` 字段 |
| start_time | Long | 是 | 查询的开始时间，Unix时间戳（秒级）。用于指定统计的起始日期 |
| end_time | Long | 是 | 查询的结束时间，Unix时间戳（秒级）。用于指定统计的结束日期。建议时间范围不要超过90天以获得最佳性能 |

### 请求示例

```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/analysis/ad-trend",
    "params": {
        "id": "c2d5b2547218a",
        "start_time": 1700000000,
        "end_time": 1707776000
    }
  }'
```

## 响应参数

### 响应体结构

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "active_ad_count_history": [],
    "ad_count_history": [],
    "ad_started_history": [],
    "is_logged_in": false
  },
  "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)

| 字段名 | 类型 | 描述 |
| ------ | ---- | ---- |
| active_ad_count_history | Array | 活跃广告数历史变化数据，记录每天活跃投放中的广告数量。活跃广告是指在当天仍在投放状态的广告 |
| ad_count_history | Array | 广告总数历史变化数据，记录每天累计的广告总数量。这是一个累积值，包含所有历史广告（活跃+已停止） |
| ad_started_history | Array | 新增广告数历史变化数据，记录每天新开始投放的广告数量。表示当天首次上线的新广告 |
| is_logged_in | Boolean | 用户是否已登录，用于标识数据权限状态 |

### 历史数据项字段 (HistoryItem)

active_ad_count_history、ad_count_history、ad_started_history 数组中的每个元素包含以下字段：

| 字段名 | 类型 | 描述 |
| ------ | ---- | ---- |
| date | String | 统计日期，格式为 yyyy-MM-dd（例如：2024-01-15） |
| count | Long | 该日期对应的数量值。根据所属数组不同，分别表示：活跃广告数、广告总数或新增广告数 |

## 响应示例

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "active_ad_count_history": [
      {
        "date": "2024-01-01",
        "count": 125
      },
      {
        "date": "2024-01-02",
        "count": 138
      },
      {
        "date": "2024-01-03",
        "count": 145
      }
    ],
    "ad_count_history": [
      {
        "date": "2024-01-01",
        "count": 1500
      },
      {
        "date": "2024-01-02",
        "count": 1523
      },
      {
        "date": "2024-01-03",
        "count": 1548
      }
    ],
    "ad_started_history": [
      {
        "date": "2024-01-01",
        "count": 15
      },
      {
        "date": "2024-01-02",
        "count": 23
      },
      {
        "date": "2024-01-03",
        "count": 25
      }
    ],
    "is_logged_in": false
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "success": true,
  "fail": false
}
```
## 错误码说明

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