监控任务的广告详情
接口信息
- 接口名称: 监控任务的广告详情
- 请求方法: 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 |
服务器内部错误 |
注意事项
- 广告 ID 必须是有效的系统内部 ID
- 响应中的 URL 已转换为 CDN 地址
- 所有时间戳均为 Unix 时间戳(秒)
- AI 分析字段仅在视频广告中返回
- 部分字段可能为空,取决于广告类型和数据完整性