Pipispy APIEnglish

数据消耗规则:1. 获取一条数据结果消耗1 数据,获取数据结果的更多数据详情不消耗数据。2. 广告监控: 每次监控 $1 / 月。单个监控有效期为一个月,一个月后自动停止。删除监控不会恢复监控次数,请谨慎删除。监控调用为随时且无限次。

监控任务的广告详情

接口信息

  • 接口名称: 监控任务的广告详情
  • 请求方法: 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

请求示例

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"
    }
  }'

响应参数

响应体结构

{
  "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:图片)

响应示例

{
  "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. 部分字段可能为空,取决于广告类型和数据完整性