# 店铺广告投放时间表接口

## 接口信息

- **接口名称**: 店铺广告投放时间表接口
- **请求方法**: GET
- **接口地址**: `/open-api/v1/data`
- **接口路径**: `/v3/api/open/store/detail/ad-schedule`
- **接口描述**:
    - 查询指定店铺在不同平台（TikTok/Facebook）的广告投放时间表数据
    - 按日期统计每天的广告投放数量
    - 支持按时间范围筛选，了解店铺的广告投放节奏
    - 帮助分析店铺的广告投放策略和活跃周期
    - 价格说明: `免费`

**请求头:**

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

## 请求参数

### 请求结构

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

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

| 参数名     | 类型    | 必填  | 描述                                                         |
| ---------- | ------- | ----- | ------------------------------------------------------------ |
| id         | string  | true  | 店铺 ID 为 13 位字符串（例如：`c2d5b2547218a`），对应店铺榜单列表接口返回结果中的 `store_id` 字段 |
| type       | integer | false | 平台类型：1-TikTok平台，2-Facebook平台，默认为1              |
| time_start | long    | false | 开始时间，时间戳（秒），不传则不限制开始时间                 |
| time_end   | long    | false | 结束时间，时间戳（秒），不传则不限制结束时间                 |


### 请求示例

```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/detail/ad-schedule",
    "params": {
      "id": "c2d5b2547218a",
      "type": 1,
      "time_start": 1704067200,
      "time_end": 1706745599
    }
  }'
```

## 响应参数

### 响应体结构

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "day": 1704067200,
        "ad_count": 150
      },
      {
        "day": 1704153600,
        "ad_count": 165
      },
      {
        "day": 1704240000,
        "ad_count": 142
      }
    ]
  },
  "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 | 请求是否失败             |

### 响应结果信息字段

| 字段名 | 类型          | 描述             |
| ------ | ------------- | ---------------- |
| data   | Array[Object] | 每日投放数据列表 |

#### data 数组元素结构（每日投放数据）

| 字段名   | 类型 | 描述                             |
| -------- | ---- | -------------------------------- |
| day      | Long | 统计日期，时间戳（秒）           |
| ad_count | Long | 该日广告投放数量                 |

**说明**：
- 数据按日期升序排列，从最早的日期到最新的日期
- 只返回广告数量大于0的日期数据
- 根据 type 参数不同，统计的是不同平台的广告数量


## 响应示例

### TikTok 平台数据示例（type=1）

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "day": 1704067200,
        "ad_count": 150
      },
      {
        "day": 1704153600,
        "ad_count": 165
      },
      {
        "day": 1704240000,
        "ad_count": 142
      },
      {
        "day": 1704326400,
        "ad_count": 178
      },
      {
        "day": 1704412800,
        "ad_count": 155
      },
      {
        "day": 1704499200,
        "ad_count": 188
      },
      {
        "day": 1704585600,
        "ad_count": 195
      },
      {
        "day": 1704672000,
        "ad_count": 210
      },
      {
        "day": 1704758400,
        "ad_count": 185
      },
      {
        "day": 1704844800,
        "ad_count": 172
      }
    ]
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "fail": false,
  "success": true
}
```

### Facebook 平台数据示例（type=2）

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "day": 1704067200,
        "ad_count": 85
      },
      {
        "day": 1704153600,
        "ad_count": 92
      },
      {
        "day": 1704240000,
        "ad_count": 78
      },
      {
        "day": 1704326400,
        "ad_count": 95
      },
      {
        "day": 1704412800,
        "ad_count": 88
      },
      {
        "day": 1704499200,
        "ad_count": 102
      },
      {
        "day": 1704585600,
        "ad_count": 110
      },
      {
        "day": 1704672000,
        "ad_count": 98
      },
      {
        "day": 1704758400,
        "ad_count": 105
      },
      {
        "day": 1704844800,
        "ad_count": 92
      }
    ]
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "fail": false,
  "success": true
}
```

### 不限时间范围示例（不传 time_start 和 time_end）

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "day": 1672531200,
        "ad_count": 45
      },
      {
        "day": 1672617600,
        "ad_count": 52
      },
      {
        "day": 1672704000,
        "ad_count": 48
      },
      ...
      {
        "day": 1706745600,
        "ad_count": 210
      }
    ]
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "fail": false,
  "success": true
}
```

## 错误码说明

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

## 使用说明

### 1. 平台类型说明
- **type=1（TikTok平台）**：
  - 统计店铺在 TikTok 平台每日的广告投放数量
  - 数据来源：TikTok 广告视频数据

- **type=2（Facebook平台）**：
  - 统计店铺在 Facebook 平台每日的广告投放数量
  - 数据来源：Facebook 广告数据

### 2. 时间范围
- **time_start 和 time_end 均为可选参数**：
  - 如果不传任何时间参数，则返回店铺所有历史投放数据
  - 如果只传 time_start，返回从该时间点到最新的投放数据
  - 如果只传 time_end，返回从最早到该时间点的投放数据
  - 如果都传，返回该时间范围内的投放数据
  - 时间戳单位为秒

### 3. 数据排序
- 数据按统计日期（day字段）**升序**排列
- 从最早的日期排到最新的日期
- 便于观察投放趋势的时间演变

### 4. 数据过滤
- 只返回广告数量大于0的日期
- 如果某天没有广告投放，该日期不会出现在结果中
- 确保返回的都是有效的投放数据