# 店铺广告 Meta 广告资料库深度投放分析接口

## 接口信息

- **接口名称**: 获取店铺广告深度投放分析
- **请求方法**: POST
- **接口地址**: `/open-api/v1/data`
- **接口路径**: `/v3/api/open/ppspy/pp-stores/analysis/delivery`
- **接口描述**: 获取指定店铺在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/delivery"     | 是   |        |
| params | object | 接口入参对象                | 见参数列表                                           | 是   |        |

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

| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| id | String | 是 | 店铺唯一标识ID，为13位字符串（例如：`c2d5b2547218a`），对应店铺榜单列表接口返回结果中的 `store_id` 字段 |

### 请求示例

```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/delivery",
    "params": {
        "id": "c2d5b2547218a"
    }
  }'
```

## 响应参数

### 响应体结构

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "daily": {},
    "time": {},
    "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)

| 字段名 | 类型 | 描述 |
| ------ | ---- | ---- |
| daily | Object | 按星期统计的广告投放分析数据，展示店铺在每周不同日期（周日至周六）的广告投放数量和占比 |
| time | Object | 按时间段统计的广告投放分析数据，展示店铺在一天内不同时间段的广告投放数量和占比 |
| is_logged_in | Boolean | 用户是否已登录，用于标识数据权限状态 |

### 按星期统计字段 (daily)

| 字段名 | 类型 | 描述 |
| ------ | ---- | ---- |
| week_0 | Object | 周日的广告投放数据 |
| week_1 | Object | 周一的广告投放数据 |
| week_2 | Object | 周二的广告投放数据 |
| week_3 | Object | 周三的广告投放数据 |
| week_4 | Object | 周四的广告投放数据 |
| week_5 | Object | 周五的广告投放数据 |
| week_6 | Object | 周六的广告投放数据 |

每个星期数据对象 (WeekData) 包含以下字段：

| 字段名 | 类型 | 描述 |
| ------ | ---- | ---- |
| ad_count | Long | 该星期的广告投放数量 |
| percentage | Double | 该星期的广告投放占比（0.0-1.0），表示该天投放广告数占总广告数的比例 |

### 按时间段统计字段 (time)

| 字段名 | 类型 | 描述 |
| ------ | ---- | ---- |
| time_1 | Object | 06:00-09:00 时间段的广告投放数据（早晨） |
| time_2 | Object | 09:00-12:00 时间段的广告投放数据（上午） |
| time_3 | Object | 12:00-15:00 时间段的广告投放数据（中午） |
| time_4 | Object | 15:00-18:00 时间段的广告投放数据（下午） |
| time_5 | Object | 18:00-21:00 时间段的广告投放数据（傍晚） |
| time_6 | Object | 21:00-23:00 时间段的广告投放数据（晚上） |
| time_7 | Object | 23:00-06:00 时间段的广告投放数据（深夜） |

每个时间段数据对象 (TimeData) 包含以下字段：

| 字段名 | 类型 | 描述 |
| ------ | ---- | ---- |
| ad_count | Long | 该时间段的广告投放数量 |
| percentage | Double | 该时间段的广告投放占比（0.0-1.0），表示该时间段投放广告数占总广告数的比例 |

## 响应示例

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "daily": {
      "week_0": {
        "ad_count": 125,
        "percentage": 0.142
      },
      "week_1": {
        "ad_count": 138,
        "percentage": 0.157
      },
      "week_2": {
        "ad_count": 145,
        "percentage": 0.165
      },
      "week_3": {
        "ad_count": 132,
        "percentage": 0.15
      },
      "week_4": {
        "ad_count": 128,
        "percentage": 0.146
      },
      "week_5": {
        "ad_count": 95,
        "percentage": 0.108
      },
      "week_6": {
        "ad_count": 117,
        "percentage": 0.133
      }
    },
    "time": {
      "time_1": {
        "ad_count": 85,
        "percentage": 0.097
      },
      "time_2": {
        "ad_count": 156,
        "percentage": 0.178
      },
      "time_3": {
        "ad_count": 142,
        "percentage": 0.162
      },
      "time_4": {
        "ad_count": 138,
        "percentage": 0.157
      },
      "time_5": {
        "ad_count": 165,
        "percentage": 0.188
      },
      "time_6": {
        "ad_count": 98,
        "percentage": 0.112
      },
      "time_7": {
        "ad_count": 96,
        "percentage": 0.109
      }
    },
    "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    | 服务器内部错误 |