监控任务的广告列表
接口信息
- 接口名称: 监控任务的广告列表
- 请求方法: POST
- 接口地址:
open-api/v1/monitor/data
- 接口路径:
/v3/api/ad-monitor-task/ad-library-list
- 接口描述:
- 广告库查询 - 根据监控任务ID查询该任务下的所有广告数据
- 维度筛选 - 支持按多种条件筛选广告,包括:
- 关键字搜索
- 广告创建时间范围
- 广告预测状态(Testing/Scaling/Winning)
- 广告组数量范围
- 广告结束时间范围
- 广告投放时长范围
- 覆盖人数范围
- 广告花费范围
- 媒体格式(视频/图片/轮播图)
- 视频时长范围
- 按钮文本(CTA)
- 广告平台(Facebook/Instagram等)
- 广告状态(活跃/不活跃/下架)
- 产品价格范围
- 产品创建时间范围
- 落地页URL
- 广告文案内容
- 关联产品ID列表
- 排序和分页 - 支持按多种字段排序和分页查询
- 价格说明:
免费
请求头:
- Content-Type: application/json
- Accept: application/json
请求参数
请求结构
| 参数名 |
类型 |
描述 |
示例 |
必填 |
默认值 |
| key |
string |
用户申请的外部 api 请求 key |
"your_api_key_here" |
是 |
|
| uri |
string |
接口路径 |
"/v3/api/ad-monitor-task/ad-library-list" |
是 |
|
| params |
object |
接口入参对象 |
见参数列表 |
是 |
|
请求体参数 (params 对象)
| 参数名 |
类型 |
必填 |
描述 |
| task_id |
string |
true |
任务id |
| keyword |
string |
false |
搜索关键词 |
| ad_started_at_start |
integer |
false |
广告创建时间(起),时间戳,单位s |
| ad_started_at_end |
integer |
false |
广告创建时间(止),时间戳,单位s |
| ad_forecast_list |
array[integer] |
false |
广告预测,可取值: 1:Testing, 2:Scaling, 3:Winning |
| adset_count_start |
integer |
false |
广告组数(起) |
| adset_count_end |
integer |
false |
广告组数(止) |
| ad_ended_at_start |
integer |
false |
广告结束时间(起),时间戳,单位s |
| ad_ended_at_end |
integer |
false |
广告结束时间(止),时间戳,单位s |
| active_days_start |
integer |
false |
广告时长(起) |
| active_days_end |
integer |
false |
广告时长(止) |
| ad_audience_reach_start |
integer |
false |
覆盖(起) |
| ad_audience_reach_end |
integer |
false |
覆盖(止) |
| ad_cost_start |
double |
false |
广告花费(起) |
| ad_cost_end |
double |
false |
广告花费(止) |
| media_format_list |
array[integer] |
false |
媒体格式,可取值: 1:视频, 2:图片, 3:轮播图 |
| video_duration_start |
integer |
false |
视频时长(起),时间戳,单位s |
| video_duration_end |
integer |
false |
视频时长(止),时间戳,单位s |
| button_text_list |
array[string] |
false |
按钮文本-cta |
| ad_platform_list |
array[string] |
false |
广告平台,可取值: FACEBOOK, INSTAGRAM, AUDIENCE_NETWORK, MESSENGER |
| ad_status_list |
array[integer] |
false |
广告状态,可取值: 1:活跃, 2:不活跃, 3:下架 |
| product_price_usd_start |
double |
false |
产品价格(起),美元 |
| product_price_usd_end |
number |
false |
产品价格(止),美元 |
| product_creation_time_start |
integer |
false |
产品创建时间(起),时间戳,单位s |
| product_creation_time_end |
integer |
false |
产品创建时间(止,时间戳,单位s |
| landing_page |
string |
false |
落地页URL |
| ad_content |
string |
false |
广告文案 |
| related_product_id_list |
array[string] |
false |
产品 ID |
| order_by |
string |
false |
排序字段, 可取值: ad_started_at(广告开始时间) ad_ended_at(广告结束时间) active_days(投放天数) adCost(广告花费) ad_audience_reach(覆盖人数) latest_actived_at(最近活跃时间) |
| direction |
string |
false |
排序方式, 可取值:desc(降序), asc(升序) |
| page |
integer |
false |
页码(默认值1) |
| perPage |
integer |
false |
每页数据数量(默认值10) |
请求示例
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-library-list",
"params": {
"order_by": "ad_started_at",
"direction": "desc",
"page": 1,
"ad_started_at_start": 1753574400,
"ad_started_at_end": 1761350399,
"per_page": 20,
"task_id": "68fa2e36789edb5700215e03",
"media_format_list": [
1,
2,
3
],
"button_text_list": [
"Add to cart",
"Apply now",
"Book now",
"Buy now"
]
}
}'
响应参数
响应体结构
{
"code": 200,
"message": "success",
"data": {},
"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 |
请求是否失败 |
响应结果信息字段
分页信息字段
| 字段名 |
类型 |
描述 |
| per_page |
integer |
每页显示数量 |
| total |
integer |
总记录数 |
| last_page |
integer |
最后一页页码 |
| current_page |
integer |
当前页码 |
广告数据字段(data数组中的对象)
| 字段名 |
类型 |
描述 |
| id |
string |
广告唯一标识ID |
| ad_title |
string |
广告标题 |
| ad_content |
string |
广告文案内容 |
| ad_caption |
string |
广告说明文字 |
| ad_link |
string |
广告在Facebook广告库的链接 |
| ad_started_at |
integer |
广告开始投放时间戳(秒) |
| ad_ended_at |
integer |
广告结束时间戳(秒) |
| first_discovered_at |
integer |
首次发现时间戳(秒) |
| last_discovered_at |
integer |
最后发现时间戳(秒) |
| latest_actived_at |
integer |
最近活跃时间戳(秒) |
| active_days |
integer |
广告活跃天数 |
| ad_status |
integer |
广告状态(1:活跃,2:不活跃,3:下架) |
| ad_forecast |
integer |
广告预测状态(1:Testing,2:Scaling,3:Winning) |
| ad_cost |
double |
广告花费金额 |
| ad_audience_reach |
integer |
广告覆盖人数 |
| adset_count |
integer |
广告组数量 |
| media_format |
integer |
媒体格式(1:视频,2:图片,3:轮播图) |
| landing_page_type |
integer |
落地页类型 |
| button_type |
string |
按钮类型(如:APPLY_NOW) |
| button_text |
string |
按钮文本内容 |
| country |
array |
广告投放国家列表 |
| ad_platform |
array |
广告投放平台(FACEBOOK、INSTAGRAM等) |
| landing_pages |
array |
落地页URL列表 |
视频信息字段(videos数组中的对象)
| 字段名 |
类型 |
描述 |
| duration |
integer |
视频时长(秒) |
| cover_url |
string |
视频封面图片URL |
| url |
string |
视频文件URL |
| width |
integer |
视频宽度(像素) |
| height |
integer |
视频高度(像素) |
广告主信息字段(advertiser对象)
| 字段名 |
类型 |
描述 |
| id |
string |
广告主ID |
| name |
string |
广告主名称 |
| source_advertiser_id |
string |
源广告主ID |
| profile_picture_url |
string |
广告主头像URL |
| like_count |
integer |
广告主点赞数 |
| ad_count |
integer |
广告主总广告数 |
| ad_country |
array |
广告主投放国家列表 |
| ads_library_link |
string |
广告主在Facebook广告库的链接 |
响应示例
{
"code": 200,
"message": "success",
"data": {
"per_page": 20,
"total": 1,
"data": [
{
"country": [
"NL"
],
"ad_caption": "werkenbijcoolblue.nl/winkel-alkmaar",
"button_type": "APPLY_NOW",
"videos": [
{
"duration": 15,
"cover_url": "https://cdn.pipidata.com/images/0e62b0d751f21752a0b1ab5b69f7a183949b87627d7f59a1638890cd01331b19.png",
"width": 720,
"url": "https://cdn.pipidata.com/videos/810468b5afa64b5f8ab521d319f02e9edc81e5de50df84b1f8a6c2966f805009.mp4",
"height": 1280
}
],
"ad_content": "Wil je werken met de leukste collega’s? Word onderdeel van ons team. #WerkenbijCoolblue #Alkmaar",
"last_discovered_at": 1755532885,
"ad_title": "Word onderdeel van ons team.",
"ad_ended_at": 1755500400,
"ad_link": "https://www.facebook.com/ads/library/?id=1779094526050412",
"ad_forecast": 2,
"id": "1779094526050412",
"latest_actived_at": 1755500400,
"landing_page_type": 3,
"advertiser": {
"like_count": 463298,
"profile_picture_url": "https://cdn.pipidata.com/images/b467aa4e0f396674a14f1ffaa99a1d76.png",
"ad_count": 14383,
"source_advertiser_id": "422603325536",
"name": "Coolblue",
"id": "422603325536",
"ad_country": [
"NL",
"BE",
"DE",
"ES",
"HU"
],
"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"
},
"ad_cost": 1559.74,
"first_discovered_at": 1755532885,
"landing_pages": [
"https://www.werkenbijcoolblue.nl/winkels/?location=alkmaar"
],
"ad_audience_reach": 11192,
"adset_count": 1,
"ad_status": 1,
"media_format": 1,
"ad_platform": [
"FACEBOOK",
"INSTAGRAM"
],
"button_text": "Apply now",
"ad_started_at": 1755500400,
"active_days": 1
}
],
"last_page": 1,
"current_page": 1
},
"version": "v1",
"timestamp": null,
"sign": null,
"remaining_credits": 9980,
"consumed_credits": 0,
"success": true,
"fail": false
}
错误码说明
| 错误码 |
描述 |
| 200 |
成功 |
| 400 |
请求参数错误 |
| 500 |
服务器内部错误 |