# 监控任务的广告详情

## 接口信息

- **接口名称**: 监控任务的广告详情
- **请求方法**: POST
- **接口地址**: `open-api/v1/monitor/data`
- **接口路径**: `/v3/api/ad-monitor-task/ad-details`
- **接口描述**:
    - 获取监控广告详情
    - 价格说明: `免费`

**请求头:**

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

## 请求参数

### 请求结构

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

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

| 参数名   | 类型     | 必填 | 描述   |
|-------|--------|----|------|
| ad_id | string | true | 广告id |


### 请求示例

```bash
curl -X POST "https://www.pipispy.com/open-api/v1/monitor/data" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "key": "your_api_key_here",
    "uri": "/v3/api/ad-monitor-task/ad-details",
    "params": {
      "ad_id": "1160096586185797"
    }
  }'
```

## 响应参数

### 响应体结构

```json
{
  "code": 200,
  "message": "success",
  "data": {},
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "success": true,
  "fail": false
}
```

##### 主要响应字段

| 字段名称          | 类型    | 描述             |
| ----------------- | ------- | ---------------- |
| **ads_history**   | object  | 广告历史变化数据 |
| **advertisement** | object  | 广告详细信息     |
| **version**       | string  | API 版本号       |
| **timestamp**     | long    | 响应时间戳       |
| **sign**          | string  | 响应签名         |
| **remaining_credits** | Long          | 当前请求后的剩余可用积分 |
| **consumed_credits**  | Long          | 本次请求消耗的积分 |
| **success**       | boolean | 请求是否成功     |
| **fail**          | boolean | 请求是否失败     |

##### 广告历史字段 (ads_history)

| 字段名称    | 类型   | 描述             |
| ----------- | ------ | ---------------- |
| ad_cost     | object | 广告花费历史数据 |
| adset_count | object | 广告组数历史数据 |

##### 历史数据时间线字段 (timeline)

| 字段名称 | 类型   | 描述                   |
| -------- | ------ | ---------------------- |
| count    | double | 数值                   |
| date     | string | 日期 (YYYY-MM-DD 格式) |

##### 广告详情字段 (advertisement)

| 字段名称            | 类型   | 描述                                         |
| ------------------- | ------ | -------------------------------------------- |
| id                  | string | 广告 ID，系统内部唯一标识                    |
| active_days         | long   | 广告投放天数                                 |
| ad_audience         | object | 广告受众信息                                 |
| ad_audience_reach   | long   | 广告触达人数                                 |
| ad_caption          | string | 广告描述                                     |
| ad_content          | string | 广告文案内容                                 |
| ad_cost             | double | 广告花费金额                                 |
| ad_forecast         | long   | 广告预测状态 (1:Testing 2:Scaling 3:Winning) |
| ad_link             | string | 广告链接                                     |
| ad_link_description | string | 广告链接描述                                 |
| ad_platform         | array  | 广告投放平台列表                             |
| ad_started_at       | long   | 广告创建时间                                 |
| ad_status           | long   | 广告状态 (1:活跃 2:不活跃 3:下架)            |
| ad_title            | string | 广告标题                                     |
| adset_count         | long   | 广告组数量                                   |
| advertiser          | object | 广告主信息                                   |
| button_text         | string | 按钮文本                                     |
| button_type         | string | 按钮类型                                     |
| cards               | array  | 轮播图列表                                   |
| country             | array  | 投放国家列表                                 |
| first_discovered_at | long   | 广告首次发现时间                             |
| images              | array  | 广告图片列表                                 |
| landing_page_type   | long   | 落地页类型                                   |
| landing_pages       | array  | 落地页 URL 列表                              |
| language            | string | 广告语言                                     |
| last_discovered_at  | long   | 广告最后更新时间                             |
| latest_actived_at   | long   | 广告最后活跃时间                             |
| media_format        | long   | 媒体格式类型                                 |
| products            | array  | 广告产品列表                                 |
| source_ad_id        | string | 源广告 ID                                    |
| store               | object | 广告店铺信息                                 |
| user_collected      | long   | 用户是否收藏 (1:已收藏 2:未收藏)             |
| videos              | array  | 广告视频列表                                 |
| size                | string | 尺寸信息                                     |
| clarity             | string | 清晰度信息                                   |
| aspect_ratio        | string | 宽高比信息                                   |
| ai_analysis         | object | AI 分析结果                                  |

##### AI 分析对象字段 (ai_analysis)

| 字段名称                    | 类型   | 描述           |
| --------------------------- | ------ | -------------- |
| ai_analysis_human_presenter | string | 是否真人演示者 |
| ai_analysis_language        | string | 视频语言       |
| ai_analysis_main_hook       | string | 主要钩子内容   |
| ai_analysis_script          | string | 视频脚本       |
| ai_analysis_tags            | array  | 视频标签列表   |

##### 广告主信息对象字段 (advertiser)

| 字段名称               | 类型   | 描述                     |
| ---------------------- | ------ | ------------------------ |
| id                     | string | 广告主 ID                |
| name                   | string | 广告主名称               |
| ad_count               | long   | 广告主广告数量           |
| ad_country             | array  | 广告主投放国家           |
| ads_library_link       | string | 广告库链接               |
| adset_count            | long   | 广告组数量               |
| e_commerce_platform    | string | 电商平台                 |
| like_count             | long   | 点赞数量                 |
| profile_picture_url    | string | 头像 URL                 |
| source_advertiser_id   | string | 源广告主 ID              |
| source_advertiser_link | string | 源广告主链接             |
| user_blocked           | long   | 用户是否屏蔽 (1:是 2:否) |

##### 产品信息对象字段 (products)

| 字段名称            | 类型   | 描述         |
| ------------------- | ------ | ------------ |
| id                  | string | 产品 ID      |
| name                | string | 产品名称     |
| ad_count            | long   | 产品广告数量 |
| category_id         | string | 分类 ID      |
| category_name       | string | 分类名称     |
| creation_time       | long   | 创建时间     |
| currency            | string | 货币类型     |
| image_url           | string | 产品图片 URL |
| price               | double | 产品价格     |
| price_usd           | double | 产品美元价格 |
| source_product_link | string | 源产品链接   |

##### 店铺信息对象字段 (store)

| 字段名称            | 类型   | 描述          |
| ------------------- | ------ | ------------- |
| id                  | string | 店铺 ID       |
| name                | string | 店铺名称      |
| ad_count            | long   | 店铺广告数量  |
| categories          | array  | 店铺分类列表  |
| e_commerce_platform | string | 电商平台      |
| e_commerce_types    | array  | 电商类型列表  |
| logo_url            | string | 店铺 Logo URL |
| source_store_link   | string | 源店铺链接    |

##### 店铺分类对象字段 (categories)

| 字段名称 | 类型   | 描述         |
| -------- | ------ | ------------ |
| id       | string | 分类 ID      |
| name_en  | string | 分类英文名称 |
| name_zh  | string | 分类中文名称 |

##### 视频信息对象字段 (videos)

| 字段名称  | 类型   | 描述           |
| --------- | ------ | -------------- |
| url       | string | 视频 URL       |
| cover_url | string | 封面 URL       |
| duration  | long   | 视频时长（秒） |
| width     | long   | 视频宽度       |
| height    | long   | 视频高度       |

##### 图片信息对象字段 (images)

| 字段名称 | 类型   | 描述     |
| -------- | ------ | -------- |
| url      | string | 图片 URL |
| width    | long   | 图片宽度 |
| height   | long   | 图片高度 |

##### 轮播图信息对象字段 (cards)

| 字段名称   | 类型   | 描述                     |
| ---------- | ------ | ------------------------ |
| url        | string | 媒体 URL                 |
| cover_url  | string | 封面 URL                 |
| duration   | long   | 时长（视频）             |
| width      | long   | 宽度                     |
| height     | long   | 高度                     |
| media_type | long   | 媒体类型 (1:视频 2:图片) |


## 响应示例

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "ads_history": {
      "ad_cost": {
        "timeline": [
          {
            "date": "2025-10-23",
            "count": 0.7
          }
        ]
      },
      "adset_count": {
        "timeline": [
          {
            "date": "2025-10-23",
            "count": 5
          }
        ]
      },
      "ad_active_day": {
        "timeline": [
          {
            "date": "2025-10-23",
            "count": 1
          }
        ]
      }
    },
    "advertisement": {
      "country": [
        "NL"
      ],
      "cards": null,
      "ad_caption": "www.coolblue.nl",
      "ad_audience": null,
      "button_type": "ORDER_NOW",
      "language": null,
      "videos": [
        {
          "duration": 15,
          "cover_url": "https://cdn.pipidata.com/images/b29269c786c7f9338b95649e19787a86.png",
          "width": 720,
          "url": "https://cdn.pipidata.com/videos/f3ba152d8c133802075a79fe0b64d8c4.mp4",
          "height": 900
        }
      ],
      "ad_content": "Op zoek naar een snelle printer? Gevonden.",
      "last_discovered_at": 1761203655,
      "ad_title": "Nu besteld in de app, morgen in huis.",
      "ad_cost_min": 0.6,
      "products": null,
      "ad_ended_at": 1761202800,
      "ad_link": "https://www.facebook.com/ads/library/?id=1160096586185797",
      "ad_forecast": 1,
      "id": "1160096586185797",
      "latest_actived_at": 1761202800,
      "ad_link_description": null,
      "landing_page_type": 3,
      "source_ad_id": null,
      "advertiser": {
        "like_count": 463298,
        "profile_picture_url": "https://cdn.pipidata.com/images/b467aa4e0f396674a14f1ffaa99a1d76.png",
        "ad_count": 18788,
        "source_advertiser_id": "422603325536",
        "name": "Coolblue",
        "source_advertiser_link": null,
        "id": "422603325536",
        "ad_country": [
          "NL",
          "BE",
          "HU",
          "DE",
          "ES",
          "AT",
          "IE",
          "LT",
          "RO",
          "SI",
          "GR"
        ],
        "ads_library_link": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=ALL&is_targeted_country=false&media_type=all&search_type=page&view_all_page_id=422603325536",
        "adset_count": null,
        "e_commerce_platform": null
      },
      "images": null,
      "ad_cost": 0.7,
      "first_discovered_at": 1761203655,
      "estimated_conversion_max": 1,
      "landing_pages": [
        "https://www.coolblue.nl/printers/hp/hp-laserjet"
      ],
      "ad_audience_reach": 38,
      "store": null,
      "adset_count": 5,
      "ad_status": 1,
      "media_format": 1,
      "ad_platform": [
        "FACEBOOK",
        "INSTAGRAM"
      ],
      "estimated_conversion_min": 1,
      "impression": 70,
      "button_text": "Order now",
      "ad_started_at": 1761202800,
      "active_days": 1,
      "ad_cost_max": 0.9
    }
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "success": true,
  "fail": false
}
```

## 错误码说明

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

## 注意事项
1. 广告 ID 必须是有效的系统内部 ID
2. 响应中的 URL 已转换为 CDN 地址
3. 所有时间戳均为 Unix 时间戳（秒）
4. AI 分析字段仅在视频广告中返回
5. 部分字段可能为空，取决于广告类型和数据完整性