Pipispy APIEnglish

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

监控任务的广告列表

接口信息

  • 接口名称: 监控任务的广告列表
  • 请求方法: 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 服务器内部错误